libc: add support for custom streams with fopencookie()

This commit adds support for custom stream via fopencookie function.
The function allows the programmer the create his own custom stream
for IO operations and hook his custom functions to it.

This is a non POSIX interface defined in Standard C library and implemented
according to it. The only difference is in usage of off_t instead of
off64_t. Programmer can use 64 bits offset if CONFIG_FS_LARGEFILE is
enabled. In that case off_t is defined as int64_t (int32_t otherwise).

Field fs_fd is removed from file_struct and fs_cookie is used instead
as a shared variable for file descriptor or user defined cookie.

The interface will be useful for future fmemopen implementation.

Signed-off-by: Michal Lenc <[email protected]>

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/nuttx/lib/lib.h

@@ -110,6 +110,13 @@ extern "C"
 
 FAR struct streamlist *lib_get_streams(void);
 FAR struct file_struct *lib_get_stream(int fd);
+
+/* Functions contained in lib_stdio_cb.c  ***********************************/
+
+ssize_t lib_fread_cb(FAR void *cookie, FAR char *buf, size_t size);
+ssize_t lib_fwrite_cb(FAR void *cookie, FAR const char *buf, size_t size);
+off_t lib_fseek_cb(FAR void *cookie, FAR off_t *offset, int whence);
+int lib_fclose_cb(FAR void *cookie);
 #endif /* CONFIG_FILE_STREAM */
 
 /* Functions defined in lib_srand.c *****************************************/

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,9 @@ if(CONFIG_FILE_STREAM)
     lib_libgetstreams.c
     lib_fputwc.c
     lib_putwc.c
-    lib_fputws.c)
+    lib_fputws.c
+    lib_fopencookie.c
+    lib_stdio_cb.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 lib_stdio_cb.c
 endif
 
 # Add the stdio directory to the build

libs/libc/stdio/lib_fclose.c

@@ -115,32 +115,25 @@ int fclose(FAR FILE *stream)
 
       nxmutex_unlock(&slist->sl_lock);
 
-      /* Check that the underlying file descriptor corresponds to an an open
-       * file.
+      /* Close the file descriptor and save the return status. We have
+       * to check if close callback is not NULL as fopencookie allows
+       * it to be NULL.
        */
 
-      if (stream->fs_fd >= 0)
+      status = OK;
+      if (stream->fs_iofunc.close != NULL)
         {
-          /* Close the file descriptor and save the return status */
-
-#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);
-#else
-          status = close(stream->fs_fd);
-#endif
+          status = stream->fs_iofunc.close(stream->fs_cookie);
+        }
 
-          /* 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 internal callbacks. */
+
+  filep->fs_iofunc.read  = lib_fread_cb;
+  filep->fs_iofunc.write = lib_fwrite_cb;
+  filep->fs_iofunc.seek  = lib_fseek_cb;
+  filep->fs_iofunc.close = lib_fclose_cb;
+
   return filep;
 
 errout:

libs/libc/stdio/lib_fopencookie.c

@@ -0,0 +1,79 @@
+/****************************************************************************
+ * 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
+ ****************************************************************************/
+
+/****************************************************************************
+ * 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;
+
+  return filep;
+}

libs/libc/stdio/lib_fseeko.c

@@ -87,5 +87,6 @@ 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;
+  return stream->fs_iofunc.seek(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,7 @@ off_t ftello(FAR FILE *stream)
    * file pointer, but will return its current setting
    */
 
-  position = lseek(stream->fs_fd, 0, SEEK_CUR);
+  position = stream->fs_iofunc.seek(stream->fs_cookie, &offset, SEEK_CUR);
   if (position != (off_t)-1)
     {
       return position - lib_getoffset(stream);

libs/libc/stdio/lib_libfflush.c

@@ -59,13 +59,13 @@
 ssize_t lib_fflush_unlocked(FAR FILE *stream, bool bforce)
 {
 #ifndef CONFIG_STDIO_DISABLE_BUFFERING
-  FAR const unsigned char *src;
+  FAR const char *src;
   ssize_t bytes_written;
   ssize_t nbuffer;
 
   /* Return EBADF if the file is not opened for writing */
 
-  if (stream->fs_fd < 0 || (stream->fs_oflags & O_WROK) == 0)
+  if ((stream->fs_oflags & O_WROK) == 0)
     {
       return -EBADF;
     }
@@ -102,12 +102,13 @@ ssize_t lib_fflush_unlocked(FAR FILE *stream, bool bforce)
 
       /* Try to write that amount */
 
-      src = stream->fs_bufstart;
+      src = (FAR const char *)stream->fs_bufstart;
       do
         {
           /* Perform the write */
 
-          bytes_written = _NX_WRITE(stream->fs_fd, src, nbuffer);
+          bytes_written = stream->fs_iofunc.write(stream->fs_cookie, src,
+                                                  nbuffer);
           if (bytes_written < 0)
             {
               /* Write failed.  The cause of the failure is in 'errno'.

libs/libc/stdio/lib_libfgets.c

@@ -100,7 +100,7 @@ FAR char *lib_fgets_unlocked(FAR char *buf, size_t buflen, FILE *stream,
 
   /* Sanity checks */
 
-  if (!stream || !buf || stream->fs_fd < 0)
+  if (!stream || !buf)
     {
       return NULL;
     }

libs/libc/stdio/lib_libfread_unlocked.c

@@ -46,7 +46,7 @@
 
 ssize_t lib_fread_unlocked(FAR void *ptr, size_t count, FAR FILE *stream)
 {
-  FAR unsigned char *dest = (FAR unsigned char *)ptr;
+  FAR char *dest = (FAR char *)ptr;
   ssize_t bytes_read;
   size_t remaining = count;
 #ifndef CONFIG_STDIO_DISABLE_BUFFERING
@@ -170,7 +170,8 @@ ssize_t lib_fread_unlocked(FAR void *ptr, size_t count, FAR FILE *stream)
 
                   if (remaining > buffer_available)
                     {
-                      bytes_read = _NX_READ(stream->fs_fd, dest, remaining);
+                      bytes_read = stream->fs_iofunc.read(stream->fs_cookie,
+                                                          dest, remaining);
                       if (bytes_read < 0)
                         {
                           if (count - remaining > 0)
@@ -213,9 +214,9 @@ ssize_t lib_fread_unlocked(FAR void *ptr, size_t count, FAR FILE *stream)
                        * into the buffer.
                        */
 
-                      bytes_read = _NX_READ(stream->fs_fd,
-                                            stream->fs_bufread,
-                                            buffer_available);
+                      bytes_read = stream->fs_iofunc.read(stream->fs_cookie,
+                                              (FAR char *)stream->fs_bufread,
+                                               buffer_available);
                       if (bytes_read < 0)
                         {
                           if (count - remaining > 0)
@@ -258,7 +259,8 @@ ssize_t lib_fread_unlocked(FAR void *ptr, size_t count, FAR FILE *stream)
 
           while (remaining > 0)
             {
-              bytes_read = _NX_READ(stream->fs_fd, dest, remaining);
+              bytes_read = stream->fs_iofunc.read(stream->fs_cookie, dest,
+                                                  remaining);
               if (bytes_read < 0)
                 {
                   if (count - remaining > 0)

libs/libc/stdio/lib_libfwrite.c

@@ -47,8 +47,8 @@ ssize_t lib_fwrite_unlocked(FAR const void *ptr, size_t count,
                             FAR FILE *stream)
 #ifndef CONFIG_STDIO_DISABLE_BUFFERING
 {
-  FAR const unsigned char *start = ptr;
-  FAR const unsigned char *src   = ptr;
+  FAR const char *start = ptr;
+  FAR const char *src   = ptr;
   ssize_t ret = ERROR;
   size_t gulp_size;
 
@@ -72,7 +72,7 @@ ssize_t lib_fwrite_unlocked(FAR const void *ptr, size_t count,
 
   if (stream->fs_bufstart == NULL)
     {
-      ret = _NX_WRITE(stream->fs_fd, ptr, count);
+      ret = stream->fs_iofunc.write(stream->fs_cookie, ptr, count);
       if (ret < 0)
         {
           _NX_SETERRNO(ret);
@@ -132,7 +132,7 @@ ssize_t lib_fwrite_unlocked(FAR const void *ptr, size_t count,
 
   if (count >= CONFIG_STDIO_BUFFER_SIZE)
     {
-      ret = _NX_WRITE(stream->fs_fd, src, count);
+      ret = stream->fs_iofunc.write(stream->fs_cookie, src, count);
       if (ret < 0)
         {
           _NX_SETERRNO(ret);
@@ -163,7 +163,7 @@ ssize_t lib_fwrite_unlocked(FAR const void *ptr, size_t count,
 }
 #else
 {
-  ssize_t ret = _NX_WRITE(stream->fs_fd, ptr, count);
+  ssize_t ret = stream->fs_iofunc.write(stream->fs_cookie, ptr, count);
   if (ret < 0)
     {
       stream->fs_flags |= __FS_FLAG_ERROR;