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_MkFifo)      && \
   42     !defined(le_fd_MkPipe)      && \
   43     !defined(le_fd_Open)        && \
   44     !defined(le_fd_Read)        && \
   45     !defined(le_fd_Write)
   46 
   47 
   48 //--------------------------------------------------------------------------------------------------
   49 /**
   50  * Create or open an existing resource.
   51  *
   52  * @return
   53  *  The new file descriptor, or -1 if an error occurred.
   54  */
   55 //--------------------------------------------------------------------------------------------------
   56 int le_fd_Open
   57 (
   58     const char  *pathName,  ///< [IN] Pathname to the resource.
   59     int         flags,      ///< [IN] Resource access flags.
   60     ...                     ///< [IN] Mode (single mode_t parameter) if creating file (O_CREAT flag
   61                             ///<      specified).
   62 );
   63 
   64 //--------------------------------------------------------------------------------------------------
   65 /**
   66  * Close a resource referred to by the file descriptor.
   67  *
   68  * @return
   69  *  Zero on success, or -1 if an error occurred.
   70  */
   71 //--------------------------------------------------------------------------------------------------
   72 int le_fd_Close
   73 (
   74     int fd                            ///< [IN] File descriptor
   75 );
   76 
   77 //--------------------------------------------------------------------------------------------------
   78 /**
   79  * Attempts to read up to count bytes from the resource referred to by the file descriptor.
   80  *
   81  * The data is read at the current offset.
   82  *
   83  * @return
   84  *  On success, the number of bytes read is returned, otherwise -1 is returned.
   85  */
   86 //--------------------------------------------------------------------------------------------------
   87 ssize_t le_fd_Read
   88 (
   89     int fd,                           ///< [IN] File descriptor
   90     void* bufPtr,                     ///< [OUT] Buffer to store read data into
   91     size_t count                      ///< [IN] Number of bytes to read
   92 );
   93 
   94 //--------------------------------------------------------------------------------------------------
   95 /**
   96  * Write up to count bytes to the resource referred to by the file descriptor.
   97  *
   98  * The data is written at the current offset.
   99  *
  100  * @return
  101  *  On success, the number of bytes written is returned, otherwise -1 is returned.
  102  */
  103 //--------------------------------------------------------------------------------------------------
  104 ssize_t le_fd_Write
  105 (
  106     int fd,                           ///< [IN] File descriptor
  107     const void* bufPtr,               ///< [IN] Buffer containing data to be written
  108     size_t count                      ///< [IN] Number of bytes to write
  109 );
  110 
  111 //--------------------------------------------------------------------------------------------------
  112 /**
  113  * Send a request to the resource referred to by the file descriptor.
  114  *
  115  * @return
  116  *  Zero on success, or -1 if an error occurred.
  117  */
  118 //--------------------------------------------------------------------------------------------------
  119 int le_fd_Ioctl
  120 (
  121     int fd,                           ///< [IN] File descriptor
  122     int request,                      ///< [IN] Device dependent request code
  123     void* bufPtr                      ///< [INOUT] Pointer to request dependent data buffer
  124 );
  125 
  126 //--------------------------------------------------------------------------------------------------
  127 /**
  128  * Make a FIFO.
  129  *
  130  * @return
  131  *  Zero on success, or -1 if an error occurred and errno is set.
  132  */
  133 //--------------------------------------------------------------------------------------------------
  134 int le_fd_MkFifo
  135 (
  136     const char *pathname,       ///< [IN] pathname of the fifo
  137     mode_t mode                 ///< [IN] permissions of the file
  138 );
  139 
  140 //--------------------------------------------------------------------------------------------------
  141 /**
  142  * Make a Pipe for bi-direction communication.
  143  *
  144  * @return
  145  *  The new file descriptor, or -1 if an error occurred.
  146  */
  147 //--------------------------------------------------------------------------------------------------
  148 int le_fd_MkPipe
  149 (
  150     const char *pathname,       ///< [IN] pathname of the fifo
  151     mode_t mode                 ///< [IN] permissions of the file
  152 );
  153 
  154 //--------------------------------------------------------------------------------------------------
  155 /**
  156  * Create a copy of the file descriptor.
  157  *
  158  * @return
  159  *  On success return the new descriptor, or -1 if an error occurred and errno is set.
  160  */
  161 //--------------------------------------------------------------------------------------------------
  162 int le_fd_Dup
  163 (
  164     int oldfd                         ///< [IN] File descriptor
  165 );
  166 
  167 //--------------------------------------------------------------------------------------------------
  168 /**
  169  * Manipulate a file descriptor.
  170  *
  171  * Implements a subset of the commands supported by fcntl(2).
  172  *
  173  * The following subcommands are guaranteed to be implemented on all platforms:
  174  *    - F_GETFL
  175  *    - F_SETFL
  176  */
  177 //--------------------------------------------------------------------------------------------------
  178 int le_fd_Fcntl
  179 (
  180     int fd,                       ///< [IN] File descriptor
  181     int cmd,                      ///< [IN] Command
  182     ... /* arg */                 ///< [IN] Argument (optional)
  183 );
  184 
  185 #else /* le_fd macros defined */
  186 
  187 // If any le_fd macro is overridden, all le_fd macros must be overridden.
  188 
  189 #if !defined(le_fd_Open)
  190 #  error "File descriptor macros are overridden, but le_fd_Open not defined.  Please define it."
  191 #endif
  192 #if !defined(le_fd_Close)
  193 #  error "File descriptor macros are overridden, but le_fd_Close not defined.  Please define it."
  194 #endif
  195 #if !defined(le_fd_Read)
  196 #  error "File descriptor macros are overridden, but le_fd_Read not defined.  Please define it."
  197 #endif
  198 #if !defined(le_fd_Write)
  199 #  error "File descriptor macros are overridden, but le_fd_Write not defined.  Please define it."
  200 #endif
  201 #if !defined(le_fd_Ioctl)
  202 #  error "File descriptor macros are overridden, but le_fd_Ioctl not defined.  Please define it."
  203 #endif
  204 #if !defined(le_fd_MkFifo)
  205 #  error "File descriptor macros are overridden, but le_fd_MkFifo not defined.  Please define it."
  206 #endif
  207 #if !defined(le_fd_MkPipe)
  208 #  error "File descriptor macros are overridden, but le_fd_MkPipe not defined.  Please define it."
  209 #endif
  210 #if !defined(le_fd_Fcntl)
  211 #  error "File descriptor macros are overridden, but le_fd_Fcntl not defined.  Please define it."
  212 #endif
  213 #if !defined(le_fd_Dup)
  214 #  error "File descriptor macros are overridden, but le_fd_Dup not defined.  Please define it."
  215 #endif
  216 
  217 #endif /* end le_fd macros defined */
  218 
  219 #endif /* end LEGATO_FD_H_INCLUDE_GUARD */
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,...)