libc: add support for custom streams with fopencookie()

boards/sim/sim/sim/configs/citest/defconfig

@@ -79,6 +79,7 @@ CONFIG_SYSTEM_DUMPSTACK=y
 CONFIG_SYSTEM_NSH=y
 CONFIG_SYSTEM_POPEN=y
 CONFIG_TESTING_CXXTEST=y
+CONFIG_TESTING_FOPENCOOKIE_TEST=y
 CONFIG_TESTING_FSTEST=y
 CONFIG_TESTING_GETPRIME=y
 CONFIG_TESTING_MM=y

include/nuttx/fs/fs.h

@@ -426,6 +426,33 @@ struct inode
 
 #define FSNODE_SIZE(n) (sizeof(struct inode) + (n))
 
+/* Definitions for custom stream operations with fopencookie. The
+ * implementation is as defined in Standard C library (libc). The only
+ * difference is that we use off_t instead of off64_t. This means
+ * off_t is int64_t if CONFIG_FS_LARGEFILE is defined and int32_t if not.
+ *
+ * These callbacks can either lead to custom functions if fopencookie is used
+ * or to standard file system functions if not.
+ */
+
+typedef CODE ssize_t cookie_read_function_t(FAR void *cookie, FAR char *buf,
+                                            size_t size);
+typedef CODE ssize_t cookie_write_function_t(FAR void *cookie,
+                                             FAR const char *buf,
+                                             size_t size);
+typedef CODE off_t cookie_seek_function_t(FAR void *cookie,
+                                          FAR off_t *offset,
+                                          int whence);
+typedef CODE int cookie_close_function_t(FAR void *cookie);
+
+typedef struct cookie_io_functions_t
+{
+  FAR cookie_read_function_t *read;
+  FAR cookie_write_function_t *write;
+  FAR cookie_seek_function_t *seek;
+  FAR cookie_close_function_t *close;
+} cookie_io_functions_t;
+
 /* This is the underlying representation of an open file.  A file
  * descriptor is an index into an array of such types. The type associates
  * the file descriptor to the file state and to a set of inode operations.
@@ -497,7 +524,8 @@ struct file_struct
 {
   FAR struct file_struct *fs_next;      /* Pointer to next file stream */
   rmutex_t                fs_lock;      /* Recursive lock */
-  int                     fs_fd;        /* File descriptor associated with stream */
+  cookie_io_functions_t   fs_iofunc;    /* Callbacks to user / system functions */
+  FAR void               *fs_cookie;    /* Pointer to file descriptor / cookie struct */
 #ifndef CONFIG_STDIO_DISABLE_BUFFERING
   FAR unsigned char      *fs_bufstart;  /* Pointer to start of buffer */
   FAR unsigned char      *fs_bufend;    /* Pointer to 1 past end of buffer */

include/stdio.h

@@ -244,6 +244,11 @@ int    dprintf(int fd, FAR const IPTR char *fmt, ...) printf_like(2, 3);
 int    vdprintf(int fd, FAR const IPTR char *fmt, va_list ap)
        printf_like(2, 0);
 
+/* Custom stream operation fopencookie. */
+
+FAR FILE *fopencookie(FAR void *cookie, FAR const char *mode,
+                      cookie_io_functions_t io_funcs);
+
 /* Operations on paths */
 
 FAR FILE *tmpfile(void) fopen_like;

libs/libc/stdio/CMakeLists.txt

@@ -103,7 +103,8 @@ if(CONFIG_FILE_STREAM)
     lib_libgetstreams.c
     lib_fputwc.c
     lib_putwc.c
-    lib_fputws.c)
+    lib_fputws.c
+    lib_fopencookie.c)
 endif()
 
 target_sources(c PRIVATE ${SRCS})

libs/libc/stdio/Make.defs

@@ -48,6 +48,7 @@ CSRCS += lib_feof.c lib_ferror.c lib_rewind.c lib_clearerr.c
 CSRCS += lib_scanf.c lib_vscanf.c lib_fscanf.c lib_vfscanf.c lib_tmpfile.c
 CSRCS += lib_setbuf.c lib_setvbuf.c lib_libfilelock.c lib_libgetstreams.c
 CSRCS += lib_setbuffer.c lib_fputwc.c lib_putwc.c lib_fputws.c
+CSRCS += lib_fopencookie.c
 endif
 
 # Add the stdio directory to the build

libs/libc/stdio/lib_fclose.c

@@ -115,32 +115,33 @@ int fclose(FAR FILE *stream)
 
       nxmutex_unlock(&slist->sl_lock);
 
-      /* Check that the underlying file descriptor corresponds to an an open
-       * file.
-       */
+      /* Call user custom callback if it is not NULL. */
 
-      if (stream->fs_fd >= 0)
+      if (stream->fs_iofunc.close != NULL)
         {
-          /* Close the file descriptor and save the return status */
-
+          status = stream->fs_iofunc.close(stream->fs_cookie);
+        }
+      else
+        {
+          int fd = (int)(intptr_t)stream->fs_cookie;
 #ifdef CONFIG_FDSAN
           uint64_t tag;
           tag = android_fdsan_create_owner_tag(ANDROID_FDSAN_OWNER_TYPE_FILE,
                                                (uintptr_t)stream);
-          status = android_fdsan_close_with_tag(stream->fs_fd, tag);
+          status = android_fdsan_close_with_tag(fd, tag);
 #else
-          status = close(stream->fs_fd);
+          status = close(fd);
 #endif
+        }
 
-          /* If close() returns an error but flush() did not then make sure
-           * that we return the close() error condition.
-           */
+      /* If close() returns an error but flush() did not then make sure
+       * that we return the close() error condition.
+       */
 
-          if (ret == OK)
-            {
-              ret = status;
-              errcode = get_errno();
-            }
+      if (ret == OK)
+        {
+          ret = status;
+          errcode = get_errno();
         }
 
 #ifndef CONFIG_STDIO_DISABLE_BUFFERING

libs/libc/stdio/lib_fileno.c

@@ -41,7 +41,7 @@ int fileno(FAR FILE *stream)
 
   if (stream)
     {
-      ret = stream->fs_fd;
+      ret = (int)(intptr_t)stream->fs_cookie;
     }
 
   if (ret < 0)

libs/libc/stdio/lib_fopen.c

@@ -141,7 +141,7 @@ FAR FILE *fdopen(int fd, FAR const char *mode)
    * file descriptor locks this stream.
    */
 
-  filep->fs_fd       = fd;
+  filep->fs_cookie   = (FAR void *)(intptr_t)fd;
   filep->fs_oflags   = oflags;
 
 #ifdef CONFIG_FDSAN
@@ -150,6 +150,13 @@ FAR FILE *fdopen(int fd, FAR const char *mode)
                                      (uintptr_t)filep));
 #endif
 
+  /* Assign custom callbacks to NULL. */
+
+  filep->fs_iofunc.read  = NULL;
+  filep->fs_iofunc.write = NULL;
+  filep->fs_iofunc.seek  = NULL;
+  filep->fs_iofunc.close = NULL;
+
   return filep;
 
 errout:

libs/libc/stdio/lib_fopencookie.c

@@ -0,0 +1,156 @@
+/****************************************************************************
+ * libs/libc/stdio/lib_fopencookie.c
+ *
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.  The
+ * ASF licenses this file to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance with the
+ * License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+ * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
+ * License for the specific language governing permissions and limitations
+ * under the License.
+ *
+ ****************************************************************************/
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <string.h>
+#include <assert.h>
+#include <errno.h>
+#include <nuttx/tls.h>
+
+#include "libc.h"
+
+/****************************************************************************
+ * Private Types
+ ****************************************************************************/
+
+/****************************************************************************
+ * Private Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: cookie_read_cb
+ ****************************************************************************/
+
+static ssize_t cookie_read_cb(FAR void *cookie, FAR char *buf, size_t size)
+{
+  /* Per specification: if *read is a null pointer, then reads from the
+   * custom stream always return end of file.
+   */
+
+  return 0;
+}
+
+/****************************************************************************
+ * Name: cookie_write_cb
+ ****************************************************************************/
+
+static ssize_t cookie_write_cb(FAR void *cookie, FAR const char *buf,
+                               size_t size)
+{
+  /* Per specification: if *write is a null pointer, then output to the
+   * stream is discarded.
+   */
+
+  return size;
+}
+
+/****************************************************************************
+ * Name: cookie_seek_cb
+ ****************************************************************************/
+
+static off_t cookie_seek_cb(FAR void *cookie, FAR off_t *offset, int whence)
+{
+  /* Per specification: if *seek is a null pointer, then it is not
+   * possible to perform seek operations on the stream.
+   */
+
+  set_errno(ENOTSUP);
+  return -1;
+}
+
+/****************************************************************************
+ * Name: cookie_close_cb
+ ****************************************************************************/
+
+static int cookie_close_cb(FAR void *cookie)
+{
+  return OK;
+}
+
+/****************************************************************************
+ * Public Functions
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: fopencookie
+ ****************************************************************************/
+
+FAR FILE *fopencookie(FAR void *cookie, FAR const char *mode,
+                      cookie_io_functions_t io_funcs)
+{
+  FAR FILE *filep = NULL;
+
+  /* Call fdopen to initialize the stream. The function is called with
+   * first possible file descriptor (0-2 are reserved). This is only
+   * to pass the required checks, file descriptor is then rewritten to
+   * cookie.
+   */
+
+  filep = fdopen(3, mode);
+  if (filep == NULL)
+    {
+      return NULL;
+    }
+
+  /* Assign cookie to file descriptor (fs_cookie) and assign user
+   * defined callbacks.
+   */
+
+  filep->fs_cookie = cookie;
+  filep->fs_iofunc = io_funcs;
+
+  /* Fopencookie Linux specification allows cookie_io_functions_t to be
+   * filled only partially and thus some callbacks might be NULL and not
+   * used. For this reason we add internal callbacks that are assigned to
+   * prevent undefined behaviour and handle correct return value per
+   * fopencookie specification.
+   */
+
+  if (filep->fs_iofunc.read == NULL)
+    {
+      filep->fs_iofunc.read = cookie_read_cb;
+    }
+
+  if (filep->fs_iofunc.write == NULL)
+    {
+      filep->fs_iofunc.write = cookie_write_cb;
+    }
+
+  if (filep->fs_iofunc.seek == NULL)
+    {
+      filep->fs_iofunc.seek = cookie_seek_cb;
+    }
+
+  if (filep->fs_iofunc.close == NULL)
+    {
+      filep->fs_iofunc.close = cookie_close_cb;
+    }
+
+  return filep;
+}

libs/libc/stdio/lib_fseeko.c

@@ -87,5 +87,14 @@ int fseeko(FAR FILE *stream, off_t offset, int whence)
 
   /* Perform the fseeko on the underlying file descriptor */
 
-  return lseek(stream->fs_fd, offset, whence) == (off_t)-1 ? ERROR : OK;
+  if (stream->fs_iofunc.seek != NULL)
+    {
+      return stream->fs_iofunc.seek(stream->fs_cookie, &offset,
+                                    whence) == (off_t)-1 ? ERROR : OK;
+    }
+  else
+    {
+      return lseek((int)(intptr_t)stream->fs_cookie, offset,
+                                    whence) == (off_t)-1 ? ERROR : OK;
+    }
 }

libs/libc/stdio/lib_ftello.c

@@ -97,6 +97,7 @@ static off_t lib_getoffset(FAR FILE *stream)
 off_t ftello(FAR FILE *stream)
 {
   off_t position;
+  off_t offset = 0;
 
   /* Verify that we were provided with a stream */
 
@@ -110,7 +111,16 @@ off_t ftello(FAR FILE *stream)
    * file pointer, but will return its current setting
    */
 
-  position = lseek(stream->fs_fd, 0, SEEK_CUR);
+  if (stream->fs_iofunc.seek != NULL)
+    {
+      position = stream->fs_iofunc.seek(stream->fs_cookie, &offset,
+                                        SEEK_CUR);
+    }
+  else
+    {
+      position = lseek((int)(intptr_t)stream->fs_cookie, 0, SEEK_CUR);
+    }
+
   if (position != (off_t)-1)
     {
       return position - lib_getoffset(stream);