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