le_fd.h

Go to the documentation of this file.
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 */
int le_fd_Fstat(int fd, struct stat *bufPtr)
int le_fd_Ioctl(int fd, int request, void *bufPtr)
int le_fd_MkFifo(const char *pathname, mode_t mode)
ssize_t le_fd_Write(int fd, const void *bufPtr, size_t count)
int le_fd_Dup(int oldfd)
int le_fd_MkPipe(const char *pathname, mode_t mode)
int le_fd_Close(int fd)
int le_fd_Open(const char *pathName, int flags,...)
ssize_t le_fd_Read(int fd, void *bufPtr, size_t count)
int le_fd_Fcntl(int fd, int cmd,...)