le_fd.h

    1 /**
    2  * @page c_fd File Descriptor API
    3  *
    4  * @subpage le_fd.h "API Reference"
    5  *
    6  * <HR>
    7  *
    8  * The File Descriptor (FD) service is intended as a helper to access file system resources.
    9  *
   10  * @section fd_dtr_api Available API
   11  *
   12  * It offers the following file operations:
   13  * - create or open a resource with @c le_fd_Open(),
   14  * - close a resource with @c le_fd_Close(),
   15  * - read from a resource with @c le_fd_Read(),
   16  * - write to a resource with @c le_fd_Write(),
   17  * - manage I/O with @c le_fd_Ioctl(),
   18  * - duplicate a file descriptor with @c le_fd_Dup(),
   19  * - create a FIFO with @c le_fd_MkFifo(),
   20  * - manipulate a file descriptor with @c le_fd_Fcntl().
   21  *
   22  * <HR>
   23  *
   24  * Copyright (C) Sierra Wireless Inc.
   25  */
   26 
   27 /** @file le_fd.h
   28  *
   29  * Legato @ref c_fd include file.
   30  *
   31  * Copyright (C) Sierra Wireless Inc.
   32  */
   33 
   34 #ifndef LEGATO_FD_H_INCLUDE_GUARD
   35 #define LEGATO_FD_H_INCLUDE_GUARD
   36 
   37 #if !defined(le_fd_Close)       && \
   38     !defined(le_fd_Dup)         && \
   39     !defined(le_fd_Fcntl)       && \
   40     !defined(le_fd_Ioctl)       && \
   41     !defined(le_fd_Fstat)       && \
   42     !defined(le_fd_MkFifo)      && \
   43     !defined(le_fd_MkPipe)      && \
   44     !defined(le_fd_Open)        && \
   45     !defined(le_fd_Read)        && \
   46     !defined(le_fd_Write)
   47 
   48 
   49 //--------------------------------------------------------------------------------------------------
   50 /**
   51  * Create or open an existing resource.
   52  *
   53  * @return
   54  *  The new file descriptor, or -1 if an error occurred.
   55  */
   56 //--------------------------------------------------------------------------------------------------
   57 int le_fd_Open
   58 (
   59     const char  *pathName,  ///< [IN] Pathname to the resource.
   60     int         flags,      ///< [IN] Resource access flags.
   61     ...                     ///< [IN] Mode (single mode_t parameter) if creating file (O_CREAT flag
   62                             ///<      specified).
   63 );
   64 
   65 //--------------------------------------------------------------------------------------------------
   66 /**
   67  * Close a resource referred to by the file descriptor.
   68  *
   69  * @return
   70  *  Zero on success, or -1 if an error occurred.
   71  */
   72 //--------------------------------------------------------------------------------------------------
   73 int le_fd_Close
   74 (
   75     int fd                            ///< [IN] File descriptor
   76 );
   77 
   78 //--------------------------------------------------------------------------------------------------
   79 /**
   80  * Attempts to read up to count bytes from the resource referred to by the file descriptor.
   81  *
   82  * The data is read at the current offset.
   83  *
   84  * @return
   85  *  On success, the number of bytes read is returned, otherwise -1 is returned.
   86  */
   87 //--------------------------------------------------------------------------------------------------
   88 ssize_t le_fd_Read
   89 (
   90     int fd,                           ///< [IN] File descriptor
   91     void* bufPtr,                     ///< [OUT] Buffer to store read data into
   92     size_t count                      ///< [IN] Number of bytes to read
   93 );
   94 
   95 //--------------------------------------------------------------------------------------------------
   96 /**
   97  * Write up to count bytes to the resource referred to by the file descriptor.
   98  *
   99  * The data is written at the current offset.
  100  *
  101  * @return
  102  *  On success, the number of bytes written is returned, otherwise -1 is returned.
  103  */
  104 //--------------------------------------------------------------------------------------------------
  105 ssize_t le_fd_Write
  106 (
  107     int fd,                           ///< [IN] File descriptor
  108     const void* bufPtr,               ///< [IN] Buffer containing data to be written
  109     size_t count                      ///< [IN] Number of bytes to write
  110 );
  111 
  112 //--------------------------------------------------------------------------------------------------
  113 /**
  114  * Send a request to the resource referred to by the file descriptor.
  115  *
  116  * @return
  117  *  Zero on success, or -1 if an error occurred.
  118  */
  119 //--------------------------------------------------------------------------------------------------
  120 int le_fd_Ioctl
  121 (
  122     int fd,                           ///< [IN] File descriptor
  123     int request,                      ///< [IN] Device dependent request code
  124     void* bufPtr                      ///< [INOUT] Pointer to request dependent data buffer
  125 );
  126 
  127 //--------------------------------------------------------------------------------------------------
  128 /**
  129  * Return information about a file, specified by the file descriptor fd.
  130  *
  131  * @return
  132  *  Zero on success, or -1 if an error occurred.
  133  */
  134 //--------------------------------------------------------------------------------------------------
  135 int le_fd_Fstat
  136 (
  137     int fd,                           ///< [IN]    File descriptor
  138     struct stat *bufPtr              ///< [OUT]   Stat structure
  139 );
  140 
  141 //--------------------------------------------------------------------------------------------------
  142 /**
  143  * Make a FIFO.
  144  *
  145  * @return
  146  *  Zero on success, or -1 if an error occurred and errno is set.
  147  */
  148 //--------------------------------------------------------------------------------------------------
  149 int le_fd_MkFifo
  150 (
  151     const char *pathname,       ///< [IN] pathname of the fifo
  152     mode_t mode                 ///< [IN] permissions of the file
  153 );
  154 
  155 //--------------------------------------------------------------------------------------------------
  156 /**
  157  * Make a Pipe for bi-direction communication.
  158  *
  159  * @return
  160  *  The new file descriptor, or -1 if an error occurred.
  161  */
  162 //--------------------------------------------------------------------------------------------------
  163 int le_fd_MkPipe
  164 (
  165     const char *pathname,       ///< [IN] pathname of the fifo
  166     mode_t mode                 ///< [IN] permissions of the file
  167 );
  168 
  169 //--------------------------------------------------------------------------------------------------
  170 /**
  171  * Create a copy of the file descriptor.
  172  *
  173  * @return
  174  *  On success return the new descriptor, or -1 if an error occurred and errno is set.
  175  */
  176 //--------------------------------------------------------------------------------------------------
  177 int le_fd_Dup
  178 (
  179     int oldfd                         ///< [IN] File descriptor
  180 );
  181 
  182 //--------------------------------------------------------------------------------------------------
  183 /**
  184  * Manipulate a file descriptor.
  185  *
  186  * Implements a subset of the commands supported by fcntl(2).
  187  *
  188  * The following subcommands are guaranteed to be implemented on all platforms:
  189  *    - F_GETFL
  190  *    - F_SETFL
  191  */
  192 //--------------------------------------------------------------------------------------------------
  193 int le_fd_Fcntl
  194 (
  195     int fd,                       ///< [IN] File descriptor
  196     int cmd,                      ///< [IN] Command
  197     ... /* arg */                 ///< [IN] Argument (optional)
  198 );
  199 
  200 #else /* le_fd macros defined */
  201 
  202 // If any le_fd macro is overridden, all le_fd macros must be overridden.
  203 
  204 #if !defined(le_fd_Open)
  205 #  error "File descriptor macros are overridden, but le_fd_Open not defined.  Please define it."
  206 #endif
  207 #if !defined(le_fd_Close)
  208 #  error "File descriptor macros are overridden, but le_fd_Close not defined.  Please define it."
  209 #endif
  210 #if !defined(le_fd_Read)
  211 #  error "File descriptor macros are overridden, but le_fd_Read not defined.  Please define it."
  212 #endif
  213 #if !defined(le_fd_Write)
  214 #  error "File descriptor macros are overridden, but le_fd_Write not defined.  Please define it."
  215 #endif
  216 #if !defined(le_fd_Ioctl)
  217 #  error "File descriptor macros are overridden, but le_fd_Ioctl not defined.  Please define it."
  218 #endif
  219 #if !defined(le_fd_Fstat)
  220 #  error "File descriptor macros are overridden, but le_fd_Fstat not defined.  Please define it."
  221 #endif
  222 #if !defined(le_fd_MkFifo)
  223 #  error "File descriptor macros are overridden, but le_fd_MkFifo not defined.  Please define it."
  224 #endif
  225 #if !defined(le_fd_MkPipe)
  226 #  error "File descriptor macros are overridden, but le_fd_MkPipe not defined.  Please define it."
  227 #endif
  228 #if !defined(le_fd_Fcntl)
  229 #  error "File descriptor macros are overridden, but le_fd_Fcntl not defined.  Please define it."
  230 #endif
  231 #if !defined(le_fd_Dup)
  232 #  error "File descriptor macros are overridden, but le_fd_Dup not defined.  Please define it."
  233 #endif
  234 
  235 #endif /* end le_fd macros defined */
  236 
  237 #endif /* end LEGATO_FD_H_INCLUDE_GUARD */
le_fd_Fstat
int le_fd_Fstat(int fd, struct stat *bufPtr)
le_fd_Ioctl
int le_fd_Ioctl(int fd, int request, void *bufPtr)
le_fd_MkFifo
int le_fd_MkFifo(const char *pathname, mode_t mode)
le_fd_Write
ssize_t le_fd_Write(int fd, const void *bufPtr, size_t count)
le_fd_Dup
int le_fd_Dup(int oldfd)
le_fd_MkPipe
int le_fd_MkPipe(const char *pathname, mode_t mode)
le_fd_Close
int le_fd_Close(int fd)
le_fd_Open
int le_fd_Open(const char *pathName, int flags,...)
le_fd_Read
ssize_t le_fd_Read(int fd, void *bufPtr, size_t count)
le_fd_Fcntl
int le_fd_Fcntl(int fd, int cmd,...)