1 | .. SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. Copyright (C) 1988, 2002 On-Line Applications Research Corporation (OAR) |
---|
4 | |
---|
5 | Input and Output Primitives Manager |
---|
6 | ################################### |
---|
7 | |
---|
8 | Introduction |
---|
9 | ============ |
---|
10 | |
---|
11 | The input and output primitives manager is ... |
---|
12 | |
---|
13 | The directives provided by the input and output primitives manager are: |
---|
14 | |
---|
15 | - pipe_ - Create an Inter-Process Channel |
---|
16 | |
---|
17 | - dup_ - Duplicates an open file descriptor |
---|
18 | |
---|
19 | - dup2_ - Duplicates an open file descriptor |
---|
20 | |
---|
21 | - close_ - Closes a file |
---|
22 | |
---|
23 | - read_ - Reads from a file |
---|
24 | |
---|
25 | - write_ - Writes to a file |
---|
26 | |
---|
27 | - fcntl_ - Manipulates an open file descriptor |
---|
28 | |
---|
29 | - lseek_ - Reposition read/write file offset |
---|
30 | |
---|
31 | - fsync_ - Synchronize file complete in-core state with that on disk |
---|
32 | |
---|
33 | - fdatasync_ - Synchronize file in-core data with that on disk |
---|
34 | |
---|
35 | - sync_ - Schedule file system updates |
---|
36 | |
---|
37 | - mount_ - Mount a file system |
---|
38 | |
---|
39 | - unmount_ - Unmount file systems |
---|
40 | |
---|
41 | - readv_ - Vectored read from a file |
---|
42 | |
---|
43 | - writev_ - Vectored write to a file |
---|
44 | |
---|
45 | - aio_read_ - Asynchronous Read |
---|
46 | |
---|
47 | - aio_write_ - Asynchronous Write |
---|
48 | |
---|
49 | - lio_listio_ - List Directed I/O |
---|
50 | |
---|
51 | - aio_error_ - Retrieve Error Status of Asynchronous I/O Operation |
---|
52 | |
---|
53 | - aio_return_ - Retrieve Return Status Asynchronous I/O Operation |
---|
54 | |
---|
55 | - aio_cancel_ - Cancel Asynchronous I/O Request |
---|
56 | |
---|
57 | - aio_suspend_ - Wait for Asynchronous I/O Request |
---|
58 | |
---|
59 | - aio_fsync_ - Asynchronous File Synchronization |
---|
60 | |
---|
61 | Background |
---|
62 | ========== |
---|
63 | |
---|
64 | There is currently no text in this section. |
---|
65 | |
---|
66 | Operations |
---|
67 | ========== |
---|
68 | |
---|
69 | There is currently no text in this section. |
---|
70 | |
---|
71 | Directives |
---|
72 | ========== |
---|
73 | |
---|
74 | This section details the input and output primitives manager's directives. A |
---|
75 | subsection is dedicated to each of this manager's directives and describes the |
---|
76 | calling sequence, related constants, usage, and status codes. |
---|
77 | |
---|
78 | .. _pipe: |
---|
79 | |
---|
80 | pipe - Create an Inter-Process Channel |
---|
81 | -------------------------------------- |
---|
82 | .. index:: pipe |
---|
83 | .. index:: create an inter |
---|
84 | |
---|
85 | **CALLING SEQUENCE:** |
---|
86 | |
---|
87 | .. code-block:: c |
---|
88 | |
---|
89 | #include <unistd.h> |
---|
90 | int pipe( |
---|
91 | int fildes[2] |
---|
92 | ); |
---|
93 | |
---|
94 | **STATUS CODES:** |
---|
95 | |
---|
96 | .. list-table:: |
---|
97 | :class: rtems-table |
---|
98 | |
---|
99 | * - ``E`` |
---|
100 | - The |
---|
101 | |
---|
102 | **DESCRIPTION:** |
---|
103 | |
---|
104 | **NOTES:** |
---|
105 | |
---|
106 | This routine is not currently supported by RTEMS but could be |
---|
107 | in a future version. |
---|
108 | |
---|
109 | .. _dup: |
---|
110 | |
---|
111 | dup - Duplicates an open file descriptor |
---|
112 | ---------------------------------------- |
---|
113 | .. index:: dup |
---|
114 | .. index:: duplicates an open file descriptor |
---|
115 | |
---|
116 | **CALLING SEQUENCE:** |
---|
117 | |
---|
118 | .. code-block:: c |
---|
119 | |
---|
120 | #include <unistd.h> |
---|
121 | int dup( |
---|
122 | int fildes |
---|
123 | ); |
---|
124 | |
---|
125 | **STATUS CODES:** |
---|
126 | |
---|
127 | .. list-table:: |
---|
128 | :class: rtems-table |
---|
129 | |
---|
130 | * - ``EBADF`` |
---|
131 | - Invalid file descriptor. |
---|
132 | * - ``EINTR`` |
---|
133 | - Function was interrupted by a signal. |
---|
134 | * - ``EMFILE`` |
---|
135 | - The process already has the maximum number of file descriptors open and |
---|
136 | tried to open a new one. |
---|
137 | |
---|
138 | **DESCRIPTION:** |
---|
139 | |
---|
140 | The ``dup`` function returns the lowest numbered available file |
---|
141 | descriptor. This new desciptor refers to the same open file as the original |
---|
142 | descriptor and shares any locks. |
---|
143 | |
---|
144 | **NOTES:** |
---|
145 | |
---|
146 | NONE |
---|
147 | |
---|
148 | .. _dup2: |
---|
149 | |
---|
150 | dup2 - Duplicates an open file descriptor |
---|
151 | ----------------------------------------- |
---|
152 | .. index:: dup2 |
---|
153 | .. index:: duplicates an open file descriptor |
---|
154 | |
---|
155 | **CALLING SEQUENCE:** |
---|
156 | |
---|
157 | .. code-block:: c |
---|
158 | |
---|
159 | #include <unistd.h> |
---|
160 | int dup2( |
---|
161 | int fildes, |
---|
162 | int fildes2 |
---|
163 | ); |
---|
164 | |
---|
165 | **STATUS CODES:** |
---|
166 | |
---|
167 | .. list-table:: |
---|
168 | :class: rtems-table |
---|
169 | |
---|
170 | * - ``EBADF`` |
---|
171 | - Invalid file descriptor. |
---|
172 | * - ``EINTR`` |
---|
173 | - Function was interrupted by a signal. |
---|
174 | * - ``EMFILE`` |
---|
175 | - The process already has the maximum number of file descriptors open and |
---|
176 | tried to open a new one. |
---|
177 | |
---|
178 | **DESCRIPTION:** |
---|
179 | |
---|
180 | ``dup2`` creates a copy of the file descriptor ``oldfd``. |
---|
181 | |
---|
182 | The old and new descriptors may be used interchangeably. They share locks, file |
---|
183 | position pointers and flags; for example, if the file position is modified by |
---|
184 | using ``lseek`` on one of the descriptors, the position is also changed for the |
---|
185 | other. |
---|
186 | |
---|
187 | **NOTES:** |
---|
188 | |
---|
189 | NONE |
---|
190 | |
---|
191 | .. _close: |
---|
192 | |
---|
193 | close - Closes a file |
---|
194 | --------------------- |
---|
195 | .. index:: close |
---|
196 | .. index:: closes a file. |
---|
197 | |
---|
198 | **CALLING SEQUENCE:** |
---|
199 | |
---|
200 | .. code-block:: c |
---|
201 | |
---|
202 | #include <unistd.h> |
---|
203 | int close( |
---|
204 | int fildes |
---|
205 | ); |
---|
206 | |
---|
207 | **STATUS CODES:** |
---|
208 | |
---|
209 | .. list-table:: |
---|
210 | :class: rtems-table |
---|
211 | |
---|
212 | * - ``EBADF`` |
---|
213 | - Invalid file descriptor |
---|
214 | * - ``EINTR`` |
---|
215 | - Function was interrupted by a signal. |
---|
216 | |
---|
217 | **DESCRIPTION:** |
---|
218 | |
---|
219 | The ``close()`` function deallocates the file descriptor named by ``fildes`` |
---|
220 | and makes it available for reuse. All outstanding record locks owned by this |
---|
221 | process for the file are unlocked. |
---|
222 | |
---|
223 | **NOTES:** |
---|
224 | |
---|
225 | A signal can interrupt the ``close()`` function. In that case, ``close()`` |
---|
226 | returns -1 with ``errno`` set to EINTR. The file may or may not be closed. |
---|
227 | |
---|
228 | .. _read: |
---|
229 | |
---|
230 | read - Reads from a file |
---|
231 | ------------------------ |
---|
232 | .. index:: read |
---|
233 | .. index:: reads from a file |
---|
234 | |
---|
235 | **CALLING SEQUENCE:** |
---|
236 | |
---|
237 | .. code-block:: c |
---|
238 | |
---|
239 | #include <unistd.h> |
---|
240 | ssize_t read( |
---|
241 | int fildes, |
---|
242 | void *buf, |
---|
243 | size_t nbyte |
---|
244 | ); |
---|
245 | |
---|
246 | **STATUS CODES:** |
---|
247 | |
---|
248 | On error, this routine returns -1 and sets ``errno`` to one of the following: |
---|
249 | |
---|
250 | .. list-table:: |
---|
251 | :class: rtems-table |
---|
252 | |
---|
253 | * - ``EAGAIN`` |
---|
254 | - The O_NONBLOCK flag is set for a file descriptor and the process would be |
---|
255 | delayed in the I/O operation. |
---|
256 | * - ``EBADF`` |
---|
257 | - Invalid file descriptor |
---|
258 | * - ``EINTR`` |
---|
259 | - Function was interrupted by a signal. |
---|
260 | * - ``EIO`` |
---|
261 | - Input or output error |
---|
262 | * - ``EINVAL`` |
---|
263 | - Bad buffer pointer |
---|
264 | |
---|
265 | **DESCRIPTION:** |
---|
266 | |
---|
267 | The ``read()`` function reads ``nbyte`` bytes from the file associated with |
---|
268 | ``fildes`` into the buffer pointed to by ``buf``. |
---|
269 | |
---|
270 | The ``read()`` function returns the number of bytes actually read and placed in |
---|
271 | the buffer. This will be less than ``nbyte`` if: |
---|
272 | |
---|
273 | - The number of bytes left in the file is less than ``nbyte``. |
---|
274 | |
---|
275 | - The ``read()`` request was interrupted by a signal. |
---|
276 | |
---|
277 | - The file is a pipe or FIFO or special file with less than ``nbytes`` |
---|
278 | immediately available for reading. |
---|
279 | |
---|
280 | When attempting to read from any empty pipe or FIFO: |
---|
281 | |
---|
282 | - If no process has the pipe open for writing, zero is returned to indicate |
---|
283 | end-of-file. |
---|
284 | |
---|
285 | - If some process has the pipe open for writing and O_NONBLOCK is set, |
---|
286 | -1 is returned and ``errno`` is set to EAGAIN. |
---|
287 | |
---|
288 | - If some process has the pipe open for writing and O_NONBLOCK is clear, |
---|
289 | ``read()`` waits for some data to be written or the pipe to be closed. |
---|
290 | |
---|
291 | When attempting to read from a file other than a pipe or FIFO and no data is |
---|
292 | available. |
---|
293 | |
---|
294 | - If O_NONBLOCK is set, -1 is returned and ``errno`` is set to EAGAIN. |
---|
295 | |
---|
296 | - If O_NONBLOCK is clear, ``read()`` waits for some data to become available. |
---|
297 | |
---|
298 | - The O_NONBLOCK flag is ignored if data is available. |
---|
299 | |
---|
300 | **NOTES:** |
---|
301 | |
---|
302 | NONE |
---|
303 | |
---|
304 | .. _write: |
---|
305 | |
---|
306 | write - Writes to a file |
---|
307 | ------------------------ |
---|
308 | .. index:: write |
---|
309 | .. index:: writes to a file |
---|
310 | |
---|
311 | **CALLING SEQUENCE:** |
---|
312 | |
---|
313 | .. code-block:: c |
---|
314 | |
---|
315 | #include <unistd.h> |
---|
316 | ssize_t write( |
---|
317 | int fildes, |
---|
318 | const void *buf, |
---|
319 | size_t nbyte |
---|
320 | ); |
---|
321 | |
---|
322 | **STATUS CODES:** |
---|
323 | |
---|
324 | .. list-table:: |
---|
325 | :class: rtems-table |
---|
326 | |
---|
327 | * - ``EAGAIN`` |
---|
328 | - The O_NONBLOCK flag is set for a file descriptor and the process would be |
---|
329 | delayed in the I/O operation. |
---|
330 | * - ``EBADF`` |
---|
331 | - Invalid file descriptor |
---|
332 | * - ``EFBIG`` |
---|
333 | - An attempt was made to write to a file that exceeds the maximum file size |
---|
334 | * - ``EINTR`` |
---|
335 | - The function was interrupted by a signal. |
---|
336 | * - ``EIO`` |
---|
337 | - Input or output error. |
---|
338 | * - ``ENOSPC`` |
---|
339 | - No space left on disk. |
---|
340 | * - ``EPIPE`` |
---|
341 | - Attempt to write to a pope or FIFO with no reader. |
---|
342 | * - ``EINVAL`` |
---|
343 | - Bad buffer pointer |
---|
344 | |
---|
345 | **DESCRIPTION:** |
---|
346 | |
---|
347 | The ``write()`` function writes ``nbyte`` from the array pointed to by ``buf`` |
---|
348 | into the file associated with ``fildes``. |
---|
349 | |
---|
350 | If ``nybte`` is zero and the file is a regular file, the ``write()`` function |
---|
351 | returns zero and has no other effect. If ``nbyte`` is zero and the file is a |
---|
352 | special file, te results are not portable. |
---|
353 | |
---|
354 | The ``write()`` function returns the number of bytes written. This number will |
---|
355 | be less than ``nbytes`` if there is an error. It will never be greater than |
---|
356 | ``nbytes``. |
---|
357 | |
---|
358 | **NOTES:** |
---|
359 | |
---|
360 | NONE |
---|
361 | |
---|
362 | .. _fcntl: |
---|
363 | |
---|
364 | fcntl - Manipulates an open file descriptor |
---|
365 | ------------------------------------------- |
---|
366 | .. index:: fcntl |
---|
367 | .. index:: manipulates an open file descriptor |
---|
368 | |
---|
369 | **CALLING SEQUENCE:** |
---|
370 | |
---|
371 | .. code-block:: c |
---|
372 | |
---|
373 | #include <fcntl.h> |
---|
374 | int fcntl( |
---|
375 | int fildes, |
---|
376 | int cmd, |
---|
377 | ... |
---|
378 | ); |
---|
379 | |
---|
380 | **STATUS CODES:** |
---|
381 | |
---|
382 | .. list-table:: |
---|
383 | :class: rtems-table |
---|
384 | |
---|
385 | * - ``EACCESS`` |
---|
386 | - Search permission is denied for a direcotry in a file's path prefix. |
---|
387 | * - ``EAGAIN`` |
---|
388 | - The O_NONBLOCK flag is set for a file descriptor and the process would be |
---|
389 | delayed in the I/O operation. |
---|
390 | * - ``EBADF`` |
---|
391 | - Invalid file descriptor |
---|
392 | * - ``EDEADLK`` |
---|
393 | - An ``fcntl`` with function ``F_SETLKW`` would cause a deadlock. |
---|
394 | * - ``EINTR`` |
---|
395 | - The functioin was interrupted by a signal. |
---|
396 | * - ``EINVAL`` |
---|
397 | - Invalid argument |
---|
398 | * - ``EMFILE`` |
---|
399 | - Too many file descriptor or in use by the process. |
---|
400 | * - ``ENOLCK`` |
---|
401 | - No locks available |
---|
402 | |
---|
403 | **DESCRIPTION:** |
---|
404 | |
---|
405 | ``fcntl()`` performs one of various miscellaneous operations on``fd``. The |
---|
406 | operation in question is determined by ``cmd``: |
---|
407 | |
---|
408 | .. list-table:: |
---|
409 | :class: rtems-table |
---|
410 | |
---|
411 | * - ``F_DUPFD`` |
---|
412 | - Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary. The |
---|
413 | same functionality can be more easily achieved by using ``dup2()``. The |
---|
414 | old and new descriptors may be used interchangeably. They share locks, |
---|
415 | file position pointers and flags; for example, if the file position is |
---|
416 | modified by using ``lseek()`` on one of the descriptors, the position is |
---|
417 | also changed for the other. The two descriptors do not share the |
---|
418 | close-on-exec flag, however. The close-on-exec flag of the copy is off, |
---|
419 | meaning that it will be closed on exec. On success, the new descriptor is |
---|
420 | returned. |
---|
421 | * - ``F_GETFD`` |
---|
422 | - Read the close-on-exec flag. If the low-order bit is 0, the file will |
---|
423 | remain open across exec, otherwise it will be closed. |
---|
424 | * - ``F_SETFD`` |
---|
425 | - Set the close-on-exec flag to the value specified by ``arg`` (only the |
---|
426 | least significant bit is used). |
---|
427 | * - ``F_GETFL`` |
---|
428 | - Read the descriptor's flags (all flags (as set by open()) are returned). |
---|
429 | * - ``F_SETFL`` |
---|
430 | - Set the descriptor's flags to the value specified by |
---|
431 | ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set. The flags are |
---|
432 | shared between copies (made with ``dup()`` etc.) of the same file |
---|
433 | descriptor. The flags and their semantics are described in ``open()``. |
---|
434 | * - ``F_GETLK``, ``F_SETLK`` and ``F_SETLKW`` |
---|
435 | - Manage discretionary file locks. The third argument ``arg`` is a pointer |
---|
436 | to a struct flock (that may be overwritten by this call). |
---|
437 | * - ``F_GETLK`` |
---|
438 | - Return the flock structure that prevents us from obtaining the lock, or |
---|
439 | set the``l_type`` field of the lock to ``F_UNLCK`` if there is no |
---|
440 | obstruction. |
---|
441 | * - ``F_SETLK`` |
---|
442 | - The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or cleared |
---|
443 | (when it is ``F_UNLCK``. If lock is held by someone else, this call |
---|
444 | returns -1 and sets ``errno`` to EACCES or EAGAIN. |
---|
445 | * - ``F_SETLKW`` |
---|
446 | - Like ``F_SETLK``, but instead of returning an error we wait for the lock |
---|
447 | to be released. |
---|
448 | * - ``F_GETOWN`` |
---|
449 | - Get the process ID (or process group) of the owner of a socket. Process |
---|
450 | groups are returned as negative values. |
---|
451 | * - ``F_SETOWN`` |
---|
452 | - Set the process or process group that owns a socket. For these commands, |
---|
453 | ownership means receiving ``SIGIO`` or ``SIGURG`` signals. Process groups |
---|
454 | are specified using negative values. |
---|
455 | |
---|
456 | **NOTES:** |
---|
457 | |
---|
458 | The errors returned by ``dup2`` are different from those returned by ``F_DUPFD``. |
---|
459 | |
---|
460 | .. _lseek: |
---|
461 | |
---|
462 | lseek - Reposition read/write file offset |
---|
463 | ----------------------------------------- |
---|
464 | .. index:: lseek |
---|
465 | .. index:: reposition read/write file offset |
---|
466 | |
---|
467 | **CALLING SEQUENCE:** |
---|
468 | |
---|
469 | .. code-block:: c |
---|
470 | |
---|
471 | #include <unistd.h> |
---|
472 | off_t lseek( |
---|
473 | int fildes, |
---|
474 | off_t offset, |
---|
475 | int whence |
---|
476 | ); |
---|
477 | |
---|
478 | **STATUS CODES:** |
---|
479 | |
---|
480 | .. list-table:: |
---|
481 | :class: rtems-table |
---|
482 | |
---|
483 | * - ``EBADF`` |
---|
484 | - ``fildes`` is not an open file descriptor. |
---|
485 | * - ``ESPIPE`` |
---|
486 | - ``fildes`` is associated with a pipe, socket or FIFO. |
---|
487 | * - ``EINVAL`` |
---|
488 | - ``whence`` is not a proper value. |
---|
489 | |
---|
490 | **DESCRIPTION:** |
---|
491 | |
---|
492 | The ``lseek`` function repositions the offset of the file descriptor ``fildes`` |
---|
493 | to the argument offset according to the directive whence. The argument |
---|
494 | ``fildes`` must be an open file descriptor. ``Lseek`` repositions the file |
---|
495 | pointer fildes as follows: |
---|
496 | |
---|
497 | - If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes. |
---|
498 | |
---|
499 | - If ``whence`` is SEEK_CUR, the offset is set to its current location |
---|
500 | plus offset bytes. |
---|
501 | |
---|
502 | - If ``whence`` is SEEK_END, the offset is set to the size of the |
---|
503 | file plus ``offset`` bytes. |
---|
504 | |
---|
505 | The ``lseek`` function allows the file offset to be set beyond the end of the |
---|
506 | existing end-of-file of the file. If data is later written at this point, |
---|
507 | subsequent reads of the data in the gap return bytes of zeros (until data is |
---|
508 | actually written into the gap). |
---|
509 | |
---|
510 | Some devices are incapable of seeking. The value of the pointer associated with |
---|
511 | such a device is undefined. |
---|
512 | |
---|
513 | **NOTES:** |
---|
514 | |
---|
515 | NONE |
---|
516 | |
---|
517 | .. _fsync: |
---|
518 | |
---|
519 | fsync - Synchronize file complete in-core state with that on disk |
---|
520 | ----------------------------------------------------------------- |
---|
521 | .. index:: fsync |
---|
522 | .. index:: synchronize file complete in |
---|
523 | |
---|
524 | **CALLING SEQUENCE:** |
---|
525 | |
---|
526 | .. code-block:: c |
---|
527 | |
---|
528 | #include <unistd.h> |
---|
529 | int fsync( |
---|
530 | int fildes |
---|
531 | ); |
---|
532 | |
---|
533 | **STATUS CODES:** |
---|
534 | |
---|
535 | On success, zero is returned. On error, -1 is returned, and ``errno`` is set |
---|
536 | appropriately. |
---|
537 | |
---|
538 | .. list-table:: |
---|
539 | :class: rtems-table |
---|
540 | |
---|
541 | * - ``EBADF`` |
---|
542 | - ``fd`` is not a valid descriptor open for writing |
---|
543 | * - ``EINVAL`` |
---|
544 | - ``fd`` is bound to a special file which does not support support |
---|
545 | synchronization |
---|
546 | * - ``EROFS`` |
---|
547 | - ``fd`` is bound to a special file which does not support support |
---|
548 | synchronization |
---|
549 | * - ``EIO`` |
---|
550 | - An error occurred during synchronization |
---|
551 | |
---|
552 | **DESCRIPTION:** |
---|
553 | |
---|
554 | ``fsync`` copies all in-core parts of a file to disk. |
---|
555 | |
---|
556 | **NOTES:** |
---|
557 | |
---|
558 | NONE |
---|
559 | |
---|
560 | .. _fdatasync: |
---|
561 | |
---|
562 | fdatasync - Synchronize file in-core data with that on disk |
---|
563 | ----------------------------------------------------------- |
---|
564 | .. index:: fdatasync |
---|
565 | .. index:: synchronize file in |
---|
566 | |
---|
567 | **CALLING SEQUENCE:** |
---|
568 | |
---|
569 | .. code-block:: c |
---|
570 | |
---|
571 | #include <unistd.h> |
---|
572 | int fdatasync( |
---|
573 | int fildes |
---|
574 | ); |
---|
575 | |
---|
576 | **STATUS CODES:** |
---|
577 | |
---|
578 | On success, zero is returned. On error, -1 is returned, and ``errno`` is set |
---|
579 | appropriately. |
---|
580 | |
---|
581 | .. list-table:: |
---|
582 | :class: rtems-table |
---|
583 | |
---|
584 | * - ``EBADF`` |
---|
585 | - ``fd`` is not a valid file descriptor open for writing. |
---|
586 | * - ``EINVAL`` |
---|
587 | - ``fd`` is bound to a special file which does not support synchronization. |
---|
588 | * - ``EIO`` |
---|
589 | - An error occurred during synchronization. |
---|
590 | * - ``EROFS`` |
---|
591 | - ``fd`` is bound to a special file which dows not support synchronization. |
---|
592 | |
---|
593 | **DESCRIPTION:** |
---|
594 | |
---|
595 | ``fdatasync`` flushes all data buffers of a file to disk (before the system |
---|
596 | call returns). It resembles ``fsync`` but is not required to update the |
---|
597 | metadata such as access time. |
---|
598 | |
---|
599 | Applications that access databases or log files often write a tiny data |
---|
600 | fragment (e.g., one line in a log file) and then call ``fsync`` immediately in |
---|
601 | order to ensure that the written data is physically stored on the |
---|
602 | harddisk. Unfortunately, fsync will always initiate two write operations: one |
---|
603 | for the newly written data and another one in order to update the modification |
---|
604 | time stored in the inode. If the modification time is not a part of the |
---|
605 | transaction concept ``fdatasync`` can be used to avoid unnecessary inode disk |
---|
606 | write operations. |
---|
607 | |
---|
608 | **NOTES:** |
---|
609 | |
---|
610 | NONE |
---|
611 | |
---|
612 | .. _sync: |
---|
613 | |
---|
614 | sync - Schedule file system updates |
---|
615 | ----------------------------------- |
---|
616 | .. index:: sync |
---|
617 | .. index:: synchronize file systems |
---|
618 | |
---|
619 | **CALLING SEQUENCE:** |
---|
620 | |
---|
621 | .. code-block:: c |
---|
622 | |
---|
623 | #include <unistd.h> |
---|
624 | void sync( |
---|
625 | void |
---|
626 | ); |
---|
627 | |
---|
628 | **STATUS CODES:** |
---|
629 | |
---|
630 | NONE |
---|
631 | |
---|
632 | **DESCRIPTION:** |
---|
633 | |
---|
634 | The ``sync`` service causes all information in memory that updates file systems |
---|
635 | to be scheduled for writing out to all file systems. |
---|
636 | |
---|
637 | **NOTES:** |
---|
638 | |
---|
639 | The writing of data to the file systems is only guaranteed to be scheduled upon |
---|
640 | return. It is not necessarily complete upon return from ``sync``. |
---|
641 | |
---|
642 | .. _mount: |
---|
643 | |
---|
644 | mount - Mount a file system |
---|
645 | --------------------------- |
---|
646 | .. index:: mount |
---|
647 | .. index:: mount a file system |
---|
648 | |
---|
649 | **CALLING SEQUENCE:** |
---|
650 | |
---|
651 | .. code-block:: c |
---|
652 | |
---|
653 | #include <libio.h> |
---|
654 | int mount( |
---|
655 | rtems_filesystem_mount_table_entry_t **mt_entry, |
---|
656 | rtems_filesystem_operations_table *fs_ops, |
---|
657 | rtems_filesystem_options_t fsoptions, |
---|
658 | char *device, |
---|
659 | char *mount_point |
---|
660 | ); |
---|
661 | |
---|
662 | **STATUS CODES:** |
---|
663 | |
---|
664 | * - ``ENOMEM`` |
---|
665 | - Unable to allocate memory needed. |
---|
666 | |
---|
667 | * - ``EINVAL`` |
---|
668 | - The filesystem does not support being mounted. |
---|
669 | |
---|
670 | * - ``EINVAL`` |
---|
671 | - Attempt to mount a read-only filesystem as writeable. |
---|
672 | |
---|
673 | **DESCRIPTION:** |
---|
674 | |
---|
675 | The ``mount`` routines mounts the filesystem class which uses the filesystem |
---|
676 | operations specified by ``fs_ops`` and ``fsoptions``. The filesystem is |
---|
677 | mounted at the directory ``mount_point`` and the mode of the mounted filesystem |
---|
678 | is specified by ``fsoptions``. If this filesystem class requires a device, |
---|
679 | then the name of the device must be specified by ``device``. |
---|
680 | |
---|
681 | If this operation succeeds, the mount table entry for the mounted filesystem is |
---|
682 | returned in ``mt_entry``. |
---|
683 | |
---|
684 | **NOTES:** |
---|
685 | |
---|
686 | This method is not defined in the POSIX standard. |
---|
687 | |
---|
688 | .. _unmount: |
---|
689 | |
---|
690 | unmount - Unmount file systems |
---|
691 | ------------------------------ |
---|
692 | .. index:: unmount |
---|
693 | .. index:: unmount file systems |
---|
694 | |
---|
695 | **CALLING SEQUENCE:** |
---|
696 | |
---|
697 | .. code-block:: c |
---|
698 | |
---|
699 | #include <libio.h> |
---|
700 | int unmount( |
---|
701 | const char *mount_path |
---|
702 | ); |
---|
703 | |
---|
704 | **STATUS CODES:** |
---|
705 | |
---|
706 | * - ``EBUSY`` |
---|
707 | - Filesystem is in use or the root filesystem. |
---|
708 | |
---|
709 | * - ``EACCESS`` |
---|
710 | - Unable to allocate memory needed. |
---|
711 | |
---|
712 | **DESCRIPTION:** |
---|
713 | |
---|
714 | The ``unmount`` routine removes the attachment of the filesystem specified by |
---|
715 | ``mount_path``. |
---|
716 | |
---|
717 | **NOTES:** |
---|
718 | |
---|
719 | This method is not defined in the POSIX standard. |
---|
720 | |
---|
721 | .. _readv: |
---|
722 | |
---|
723 | readv - Vectored read from a file |
---|
724 | --------------------------------- |
---|
725 | .. index:: readv |
---|
726 | .. index:: vectored read from a file |
---|
727 | |
---|
728 | **CALLING SEQUENCE:** |
---|
729 | |
---|
730 | .. code-block:: c |
---|
731 | |
---|
732 | #include <sys/uio.h> |
---|
733 | ssize_t readv( |
---|
734 | int fildes, |
---|
735 | const struct iovec *iov, |
---|
736 | int iovcnt |
---|
737 | ); |
---|
738 | |
---|
739 | **STATUS CODES:** |
---|
740 | |
---|
741 | In addition to the errors detected by *Input and Output Primitives Manager |
---|
742 | read - Reads from a file, read()*, this routine may return -1 and sets |
---|
743 | ``errno`` based upon the following errors: |
---|
744 | |
---|
745 | .. list-table:: |
---|
746 | :class: rtems-table |
---|
747 | |
---|
748 | * - ``EINVAL`` |
---|
749 | - The sum of the ``iov_len`` values in the iov array overflowed |
---|
750 | an ``ssize_t``. |
---|
751 | * - ``EINVAL`` |
---|
752 | - The ``iovcnt`` argument was less than or equal to 0, or greater than |
---|
753 | ``IOV_MAX``. |
---|
754 | |
---|
755 | **DESCRIPTION:** |
---|
756 | |
---|
757 | The ``readv()`` function is equivalent to ``read()`` except as described |
---|
758 | here. The ``readv()`` function shall place the input data into the ``iovcnt`` |
---|
759 | buffers specified by the members of the ``iov`` array: ``iov[0], iov[1], ..., |
---|
760 | iov[iovcnt-1]``. |
---|
761 | |
---|
762 | Each ``iovec`` entry specifies the base address and length of an area in memory |
---|
763 | where data should be placed. The ``readv()`` function always fills an area |
---|
764 | completely before proceeding to the next. |
---|
765 | |
---|
766 | **NOTES:** |
---|
767 | |
---|
768 | NONE |
---|
769 | |
---|
770 | .. _writev: |
---|
771 | |
---|
772 | writev - Vectored write to a file |
---|
773 | --------------------------------- |
---|
774 | .. index:: writev |
---|
775 | .. index:: vectored write to a file |
---|
776 | |
---|
777 | **CALLING SEQUENCE:** |
---|
778 | |
---|
779 | .. code-block:: c |
---|
780 | |
---|
781 | #include <sys/uio.h> |
---|
782 | ssize_t writev( |
---|
783 | int fildes, |
---|
784 | const struct iovec *iov, |
---|
785 | int iovcnt |
---|
786 | ); |
---|
787 | |
---|
788 | **STATUS CODES:** |
---|
789 | |
---|
790 | In addition to the errors detected by *Input and Output Primitives Manager |
---|
791 | write - Write to a file, write()*, this routine may return -1 and sets |
---|
792 | ``errno`` based upon the following errors: |
---|
793 | |
---|
794 | .. list-table:: |
---|
795 | :class: rtems-table |
---|
796 | |
---|
797 | * - ``EINVAL`` |
---|
798 | - The sum of the ``iov_len`` values in the iov array overflowed |
---|
799 | an ``ssize_t``. |
---|
800 | * - ``EINVAL`` |
---|
801 | - The ``iovcnt`` argument was less than or equal to 0, or greater than |
---|
802 | ``IOV_MAX``. |
---|
803 | |
---|
804 | **DESCRIPTION:** |
---|
805 | |
---|
806 | The ``writev()`` function is equivalent to ``write()``, except as noted |
---|
807 | here. The ``writev()`` function gathers output data from the ``iovcnt`` buffers |
---|
808 | specified by the members of the ``iov array``: ``iov[0], iov[1], ..., |
---|
809 | iov[iovcnt-1]``. The ``iovcnt`` argument is valid if greater than 0 and less |
---|
810 | than or equal to ``IOV_MAX``. |
---|
811 | |
---|
812 | Each ``iovec`` entry specifies the base address and length of an area in memory |
---|
813 | from which data should be written. The ``writev()`` function always writes a |
---|
814 | complete area before proceeding to the next. |
---|
815 | |
---|
816 | If ``fd`` refers to a regular file and all of the ``iov_len`` members in the |
---|
817 | array pointed to by ``iov`` are 0, ``writev()`` returns 0 and has no other |
---|
818 | effect. For other file types, the behavior is unspecified by POSIX. |
---|
819 | |
---|
820 | **NOTES:** |
---|
821 | |
---|
822 | NONE |
---|
823 | |
---|
824 | .. _aio_read: |
---|
825 | |
---|
826 | aio_read - Asynchronous Read |
---|
827 | ---------------------------- |
---|
828 | .. index:: aio_read |
---|
829 | .. index:: asynchronous read |
---|
830 | |
---|
831 | **CALLING SEQUENCE:** |
---|
832 | |
---|
833 | .. code-block:: c |
---|
834 | |
---|
835 | #include <aio.h> |
---|
836 | int aio_read( |
---|
837 | struct aiocb *aiocbp |
---|
838 | ); |
---|
839 | |
---|
840 | **STATUS CODES:** |
---|
841 | |
---|
842 | .. list-table:: |
---|
843 | :class: rtems-table |
---|
844 | |
---|
845 | * - ``E`` |
---|
846 | - The |
---|
847 | |
---|
848 | **DESCRIPTION:** |
---|
849 | |
---|
850 | **NOTES:** |
---|
851 | |
---|
852 | This routine is not currently supported by RTEMS but could be in a future |
---|
853 | version. |
---|
854 | |
---|
855 | .. _aio_write: |
---|
856 | |
---|
857 | aio_write - Asynchronous Write |
---|
858 | ------------------------------ |
---|
859 | .. index:: aio_write |
---|
860 | .. index:: asynchronous write |
---|
861 | |
---|
862 | **CALLING SEQUENCE:** |
---|
863 | |
---|
864 | .. code-block:: c |
---|
865 | |
---|
866 | #include <aio.h> |
---|
867 | int aio_write( |
---|
868 | struct aiocb *aiocbp |
---|
869 | ); |
---|
870 | |
---|
871 | **STATUS CODES:** |
---|
872 | |
---|
873 | .. list-table:: |
---|
874 | :class: rtems-table |
---|
875 | |
---|
876 | * - ``E`` |
---|
877 | - The |
---|
878 | |
---|
879 | **DESCRIPTION:** |
---|
880 | |
---|
881 | **NOTES:** |
---|
882 | |
---|
883 | This routine is not currently supported by RTEMS but could be in a future |
---|
884 | version. |
---|
885 | |
---|
886 | .. _lio_listio: |
---|
887 | |
---|
888 | lio_listio - List Directed I/O |
---|
889 | ------------------------------ |
---|
890 | .. index:: lio_listio |
---|
891 | .. index:: list directed i/o |
---|
892 | |
---|
893 | **CALLING SEQUENCE:** |
---|
894 | |
---|
895 | .. code-block:: c |
---|
896 | |
---|
897 | #include <aio.h> |
---|
898 | int lio_listio( |
---|
899 | int mode, |
---|
900 | struct aiocb *restrict const list[restrict], |
---|
901 | int nent, |
---|
902 | struct sigevent *restrict sig |
---|
903 | ); |
---|
904 | |
---|
905 | **STATUS CODES:** |
---|
906 | |
---|
907 | .. list-table:: |
---|
908 | :class: rtems-table |
---|
909 | |
---|
910 | * - ``E`` |
---|
911 | - The |
---|
912 | |
---|
913 | **DESCRIPTION:** |
---|
914 | |
---|
915 | **NOTES:** |
---|
916 | |
---|
917 | This routine is not currently supported by RTEMS but could be in a future |
---|
918 | version. |
---|
919 | |
---|
920 | .. _aio_error: |
---|
921 | |
---|
922 | aio_error - Retrieve Error Status of Asynchronous I/O Operation |
---|
923 | --------------------------------------------------------------- |
---|
924 | .. index:: aio_error |
---|
925 | .. index:: retrieve error status of asynchronous i/o operation |
---|
926 | |
---|
927 | **CALLING SEQUENCE:** |
---|
928 | |
---|
929 | .. code-block:: c |
---|
930 | |
---|
931 | #include <aio.h> |
---|
932 | int aio_error( |
---|
933 | const struct aiocb *aiocbp |
---|
934 | ); |
---|
935 | |
---|
936 | **STATUS CODES:** |
---|
937 | |
---|
938 | .. list-table:: |
---|
939 | :class: rtems-table |
---|
940 | |
---|
941 | * - ``E`` |
---|
942 | - The |
---|
943 | |
---|
944 | **DESCRIPTION:** |
---|
945 | |
---|
946 | **NOTES:** |
---|
947 | |
---|
948 | This routine is not currently supported by RTEMS but could be in a future |
---|
949 | version. |
---|
950 | |
---|
951 | .. _aio_return: |
---|
952 | |
---|
953 | aio_return - Retrieve Return Status Asynchronous I/O Operation |
---|
954 | -------------------------------------------------------------- |
---|
955 | .. index:: aio_return |
---|
956 | .. index:: retrieve return status asynchronous i/o operation |
---|
957 | |
---|
958 | **CALLING SEQUENCE:** |
---|
959 | |
---|
960 | .. code-block:: c |
---|
961 | |
---|
962 | #include <aio.h> |
---|
963 | ssize_t aio_return( |
---|
964 | struct aiocb *aiocbp |
---|
965 | ); |
---|
966 | |
---|
967 | **STATUS CODES:** |
---|
968 | |
---|
969 | .. list-table:: |
---|
970 | :class: rtems-table |
---|
971 | |
---|
972 | * - ``E`` |
---|
973 | - The |
---|
974 | |
---|
975 | **DESCRIPTION:** |
---|
976 | |
---|
977 | **NOTES:** |
---|
978 | |
---|
979 | This routine is not currently supported by RTEMS but could be in a future |
---|
980 | version. |
---|
981 | |
---|
982 | .. _aio_cancel: |
---|
983 | |
---|
984 | aio_cancel - Cancel Asynchronous I/O Request |
---|
985 | -------------------------------------------- |
---|
986 | .. index:: aio_cancel |
---|
987 | .. index:: cancel asynchronous i/o request |
---|
988 | |
---|
989 | **CALLING SEQUENCE:** |
---|
990 | |
---|
991 | .. code-block:: c |
---|
992 | |
---|
993 | #include <aio.h> |
---|
994 | int aio_cancel( |
---|
995 | int fildes, |
---|
996 | struct aiocb *aiocbp |
---|
997 | ); |
---|
998 | |
---|
999 | **STATUS CODES:** |
---|
1000 | |
---|
1001 | .. list-table:: |
---|
1002 | :class: rtems-table |
---|
1003 | |
---|
1004 | * - ``E`` |
---|
1005 | - The |
---|
1006 | |
---|
1007 | **DESCRIPTION:** |
---|
1008 | |
---|
1009 | **NOTES:** |
---|
1010 | |
---|
1011 | This routine is not currently supported by RTEMS but could be in a future |
---|
1012 | version. |
---|
1013 | |
---|
1014 | .. _aio_suspend: |
---|
1015 | |
---|
1016 | aio_suspend - Wait for Asynchronous I/O Request |
---|
1017 | ----------------------------------------------- |
---|
1018 | .. index:: aio_suspend |
---|
1019 | .. index:: wait for asynchronous i/o request |
---|
1020 | |
---|
1021 | **CALLING SEQUENCE:** |
---|
1022 | |
---|
1023 | .. code-block:: c |
---|
1024 | |
---|
1025 | #include <aio.h> |
---|
1026 | int aio_suspend( |
---|
1027 | const struct aiocb *const list[], |
---|
1028 | int nent, |
---|
1029 | const struct timespec *timeout |
---|
1030 | ); |
---|
1031 | |
---|
1032 | **STATUS CODES:** |
---|
1033 | |
---|
1034 | .. list-table:: |
---|
1035 | :class: rtems-table |
---|
1036 | |
---|
1037 | * - ``E`` |
---|
1038 | - The |
---|
1039 | |
---|
1040 | **DESCRIPTION:** |
---|
1041 | |
---|
1042 | **NOTES:** |
---|
1043 | |
---|
1044 | This routine is not currently supported by RTEMS but could be in a future |
---|
1045 | version. |
---|
1046 | |
---|
1047 | .. _aio_fsync: |
---|
1048 | |
---|
1049 | aio_fsync - Asynchronous File Synchronization |
---|
1050 | --------------------------------------------- |
---|
1051 | .. index:: aio_fsync |
---|
1052 | .. index:: asynchronous file synchronization |
---|
1053 | |
---|
1054 | **CALLING SEQUENCE:** |
---|
1055 | |
---|
1056 | .. code-block:: c |
---|
1057 | |
---|
1058 | #include <aio.h> |
---|
1059 | int aio_fsync( |
---|
1060 | int op, |
---|
1061 | struct aiocb *aiocbp |
---|
1062 | ); |
---|
1063 | |
---|
1064 | **STATUS CODES:** |
---|
1065 | |
---|
1066 | .. list-table:: |
---|
1067 | :class: rtems-table |
---|
1068 | |
---|
1069 | * - ``E`` |
---|
1070 | - The |
---|
1071 | |
---|
1072 | **DESCRIPTION:** |
---|
1073 | |
---|
1074 | **NOTES:** |
---|
1075 | |
---|
1076 | This routine is not currently supported by RTEMS but could be in a future |
---|
1077 | version. |
---|