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 */