1 | .. comment SPDX-License-Identifier: CC-BY-SA-4.0 |
---|
2 | |
---|
3 | .. COMMENT: COPYRIGHT (c) 1988-2002. |
---|
4 | .. COMMENT: On-Line Applications Research Corporation (OAR). |
---|
5 | .. COMMENT: All rights reserved. |
---|
6 | |
---|
7 | Input and Output Primitives Manager |
---|
8 | ################################### |
---|
9 | |
---|
10 | Introduction |
---|
11 | ============ |
---|
12 | |
---|
13 | The input and output primitives manager is ... |
---|
14 | |
---|
15 | The directives provided by the input and output primitives manager are: |
---|
16 | |
---|
17 | - pipe_ - Create an Inter-Process Channel |
---|
18 | |
---|
19 | - dup_ - Duplicates an open file descriptor |
---|
20 | |
---|
21 | - dup2_ - Duplicates an open file descriptor |
---|
22 | |
---|
23 | - close_ - Closes a file |
---|
24 | |
---|
25 | - read_ - Reads from a file |
---|
26 | |
---|
27 | - write_ - Writes to a file |
---|
28 | |
---|
29 | - fcntl_ - Manipulates an open file descriptor |
---|
30 | |
---|
31 | - lseek_ - Reposition read/write file offset |
---|
32 | |
---|
33 | - fsync_ - Synchronize file complete in-core state with that on disk |
---|
34 | |
---|
35 | - fdatasync_ - Synchronize file in-core data with that on disk |
---|
36 | |
---|
37 | - sync_ - Schedule file system updates |
---|
38 | |
---|
39 | - mount_ - Mount a file system |
---|
40 | |
---|
41 | - unmount_ - Unmount file systems |
---|
42 | |
---|
43 | - readv_ - Vectored read from a file |
---|
44 | |
---|
45 | - writev_ - Vectored write to a file |
---|
46 | |
---|
47 | - aio_read_ - Asynchronous Read |
---|
48 | |
---|
49 | - aio_write_ - Asynchronous Write |
---|
50 | |
---|
51 | - lio_listio_ - List Directed I/O |
---|
52 | |
---|
53 | - aio_error_ - Retrieve Error Status of Asynchronous I/O Operation |
---|
54 | |
---|
55 | - aio_return_ - Retrieve Return Status Asynchronous I/O Operation |
---|
56 | |
---|
57 | - aio_cancel_ - Cancel Asynchronous I/O Request |
---|
58 | |
---|
59 | - aio_suspend_ - Wait for Asynchronous I/O Request |
---|
60 | |
---|
61 | - aio_fsync_ - Asynchronous File Synchronization |
---|
62 | |
---|
63 | Background |
---|
64 | ========== |
---|
65 | |
---|
66 | There is currently no text in this section. |
---|
67 | |
---|
68 | Operations |
---|
69 | ========== |
---|
70 | |
---|
71 | There is currently no text in this section. |
---|
72 | |
---|
73 | Directives |
---|
74 | ========== |
---|
75 | |
---|
76 | This section details the input and output primitives manager's directives. A |
---|
77 | subsection is dedicated to each of this manager's directives and describes the |
---|
78 | calling sequence, related constants, usage, and status codes. |
---|
79 | |
---|
80 | .. _pipe: |
---|
81 | |
---|
82 | pipe - Create an Inter-Process Channel |
---|
83 | -------------------------------------- |
---|
84 | .. index:: pipe |
---|
85 | .. index:: create an inter |
---|
86 | |
---|
87 | **CALLING SEQUENCE:** |
---|
88 | |
---|
89 | .. code-block:: c |
---|
90 | |
---|
91 | int pipe( |
---|
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 | int read( |
---|
241 | int fildes, |
---|
242 | void *buf, |
---|
243 | unsigned int 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 | int write( |
---|
317 | int fildes, |
---|
318 | const void *buf, |
---|
319 | unsigned int nbytes |
---|
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 <sys/types.h> |
---|
374 | #include <fcntl.h> |
---|
375 | #include <unistd.h> |
---|
376 | int fcntl( |
---|
377 | int fildes, |
---|
378 | int cmd |
---|
379 | ); |
---|
380 | |
---|
381 | **STATUS CODES:** |
---|
382 | |
---|
383 | .. list-table:: |
---|
384 | :class: rtems-table |
---|
385 | |
---|
386 | * - ``EACCESS`` |
---|
387 | - Search permission is denied for a direcotry in a file's path prefix. |
---|
388 | * - ``EAGAIN`` |
---|
389 | - The O_NONBLOCK flag is set for a file descriptor and the process would be |
---|
390 | delayed in the I/O operation. |
---|
391 | * - ``EBADF`` |
---|
392 | - Invalid file descriptor |
---|
393 | * - ``EDEADLK`` |
---|
394 | - An ``fcntl`` with function ``F_SETLKW`` would cause a deadlock. |
---|
395 | * - ``EINTR`` |
---|
396 | - The functioin was interrupted by a signal. |
---|
397 | * - ``EINVAL`` |
---|
398 | - Invalid argument |
---|
399 | * - ``EMFILE`` |
---|
400 | - Too many file descriptor or in use by the process. |
---|
401 | * - ``ENOLCK`` |
---|
402 | - No locks available |
---|
403 | |
---|
404 | **DESCRIPTION:** |
---|
405 | |
---|
406 | ``fcntl()`` performs one of various miscellaneous operations on``fd``. The |
---|
407 | operation in question is determined by ``cmd``: |
---|
408 | |
---|
409 | .. list-table:: |
---|
410 | :class: rtems-table |
---|
411 | |
---|
412 | * - ``F_DUPFD`` |
---|
413 | - Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary. The |
---|
414 | same functionality can be more easily achieved by using ``dup2()``. The |
---|
415 | old and new descriptors may be used interchangeably. They share locks, |
---|
416 | file position pointers and flags; for example, if the file position is |
---|
417 | modified by using ``lseek()`` on one of the descriptors, the position is |
---|
418 | also changed for the other. The two descriptors do not share the |
---|
419 | close-on-exec flag, however. The close-on-exec flag of the copy is off, |
---|
420 | meaning that it will be closed on exec. On success, the new descriptor is |
---|
421 | returned. |
---|
422 | * - ``F_GETFD`` |
---|
423 | - Read the close-on-exec flag. If the low-order bit is 0, the file will |
---|
424 | remain open across exec, otherwise it will be closed. |
---|
425 | * - ``F_SETFD`` |
---|
426 | - Set the close-on-exec flag to the value specified by ``arg`` (only the |
---|
427 | least significant bit is used). |
---|
428 | * - ``F_GETFL`` |
---|
429 | - Read the descriptor's flags (all flags (as set by open()) are returned). |
---|
430 | * - ``F_SETFL`` |
---|
431 | - Set the descriptor's flags to the value specified by |
---|
432 | ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set. The flags are |
---|
433 | shared between copies (made with ``dup()`` etc.) of the same file |
---|
434 | descriptor. The flags and their semantics are described in ``open()``. |
---|
435 | * - ``F_GETLK``, ``F_SETLK`` and ``F_SETLKW`` |
---|
436 | - Manage discretionary file locks. The third argument ``arg`` is a pointer |
---|
437 | to a struct flock (that may be overwritten by this call). |
---|
438 | * - ``F_GETLK`` |
---|
439 | - Return the flock structure that prevents us from obtaining the lock, or |
---|
440 | set the``l_type`` field of the lock to ``F_UNLCK`` if there is no |
---|
441 | obstruction. |
---|
442 | * - ``F_SETLK`` |
---|
443 | - The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or cleared |
---|
444 | (when it is ``F_UNLCK``. If lock is held by someone else, this call |
---|
445 | returns -1 and sets ``errno`` to EACCES or EAGAIN. |
---|
446 | * - ``F_SETLKW`` |
---|
447 | - Like ``F_SETLK``, but instead of returning an error we wait for the lock |
---|
448 | to be released. |
---|
449 | * - ``F_GETOWN`` |
---|
450 | - Get the process ID (or process group) of the owner of a socket. Process |
---|
451 | groups are returned as negative values. |
---|
452 | * - ``F_SETOWN`` |
---|
453 | - Set the process or process group that owns a socket. For these commands, |
---|
454 | ownership means receiving ``SIGIO`` or ``SIGURG`` signals. Process groups |
---|
455 | are specified using negative values. |
---|
456 | |
---|
457 | **NOTES:** |
---|
458 | |
---|
459 | The errors returned by ``dup2`` are different from those returned by ``F_DUPFD``. |
---|
460 | |
---|
461 | .. _lseek: |
---|
462 | |
---|
463 | lseek - Reposition read/write file offset |
---|
464 | ----------------------------------------- |
---|
465 | .. index:: lseek |
---|
466 | .. index:: reposition read/write file offset |
---|
467 | |
---|
468 | **CALLING SEQUENCE:** |
---|
469 | |
---|
470 | .. code-block:: c |
---|
471 | |
---|
472 | #include <sys/types.h> |
---|
473 | #include <unistd.h> |
---|
474 | int lseek( |
---|
475 | int fildes, |
---|
476 | off_t offset, |
---|
477 | int whence |
---|
478 | ); |
---|
479 | |
---|
480 | **STATUS CODES:** |
---|
481 | |
---|
482 | .. list-table:: |
---|
483 | :class: rtems-table |
---|
484 | |
---|
485 | * - ``EBADF`` |
---|
486 | - ``fildes`` is not an open file descriptor. |
---|
487 | * - ``ESPIPE`` |
---|
488 | - ``fildes`` is associated with a pipe, socket or FIFO. |
---|
489 | * - ``EINVAL`` |
---|
490 | - ``whence`` is not a proper value. |
---|
491 | |
---|
492 | **DESCRIPTION:** |
---|
493 | |
---|
494 | The ``lseek`` function repositions the offset of the file descriptor ``fildes`` |
---|
495 | to the argument offset according to the directive whence. The argument |
---|
496 | ``fildes`` must be an open file descriptor. ``Lseek`` repositions the file |
---|
497 | pointer fildes as follows: |
---|
498 | |
---|
499 | - If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes. |
---|
500 | |
---|
501 | - If ``whence`` is SEEK_CUR, the offset is set to its current location |
---|
502 | plus offset bytes. |
---|
503 | |
---|
504 | - If ``whence`` is SEEK_END, the offset is set to the size of the |
---|
505 | file plus ``offset`` bytes. |
---|
506 | |
---|
507 | The ``lseek`` function allows the file offset to be set beyond the end of the |
---|
508 | existing end-of-file of the file. If data is later written at this point, |
---|
509 | subsequent reads of the data in the gap return bytes of zeros (until data is |
---|
510 | actually written into the gap). |
---|
511 | |
---|
512 | Some devices are incapable of seeking. The value of the pointer associated with |
---|
513 | such a device is undefined. |
---|
514 | |
---|
515 | **NOTES:** |
---|
516 | |
---|
517 | NONE |
---|
518 | |
---|
519 | .. _fsync: |
---|
520 | |
---|
521 | fsync - Synchronize file complete in-core state with that on disk |
---|
522 | ----------------------------------------------------------------- |
---|
523 | .. index:: fsync |
---|
524 | .. index:: synchronize file complete in |
---|
525 | |
---|
526 | **CALLING SEQUENCE:** |
---|
527 | |
---|
528 | .. code-block:: c |
---|
529 | |
---|
530 | int fsync( |
---|
531 | int fd |
---|
532 | ); |
---|
533 | |
---|
534 | **STATUS CODES:** |
---|
535 | |
---|
536 | On success, zero is returned. On error, -1 is returned, and ``errno`` is set |
---|
537 | appropriately. |
---|
538 | |
---|
539 | .. list-table:: |
---|
540 | :class: rtems-table |
---|
541 | |
---|
542 | * - ``EBADF`` |
---|
543 | - ``fd`` is not a valid descriptor open for writing |
---|
544 | * - ``EINVAL`` |
---|
545 | - ``fd`` is bound to a special file which does not support support |
---|
546 | synchronization |
---|
547 | * - ``EROFS`` |
---|
548 | - ``fd`` is bound to a special file which does not support support |
---|
549 | synchronization |
---|
550 | * - ``EIO`` |
---|
551 | - An error occurred during synchronization |
---|
552 | |
---|
553 | **DESCRIPTION:** |
---|
554 | |
---|
555 | ``fsync`` copies all in-core parts of a file to disk. |
---|
556 | |
---|
557 | **NOTES:** |
---|
558 | |
---|
559 | NONE |
---|
560 | |
---|
561 | .. _fdatasync: |
---|
562 | |
---|
563 | fdatasync - Synchronize file in-core data with that on disk |
---|
564 | ----------------------------------------------------------- |
---|
565 | .. index:: fdatasync |
---|
566 | .. index:: synchronize file in |
---|
567 | |
---|
568 | **CALLING SEQUENCE:** |
---|
569 | |
---|
570 | .. code-block:: c |
---|
571 | |
---|
572 | int fdatasync( |
---|
573 | int fd |
---|
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 | void sync(void); |
---|
624 | |
---|
625 | **STATUS CODES:** |
---|
626 | |
---|
627 | NONE |
---|
628 | |
---|
629 | **DESCRIPTION:** |
---|
630 | |
---|
631 | The ``sync`` service causes all information in memory that updates file systems |
---|
632 | to be scheduled for writing out to all file systems. |
---|
633 | |
---|
634 | **NOTES:** |
---|
635 | |
---|
636 | The writing of data to the file systems is only guaranteed to be scheduled upon |
---|
637 | return. It is not necessarily complete upon return from ``sync``. |
---|
638 | |
---|
639 | .. _mount: |
---|
640 | |
---|
641 | mount - Mount a file system |
---|
642 | --------------------------- |
---|
643 | .. index:: mount |
---|
644 | .. index:: mount a file system |
---|
645 | |
---|
646 | **CALLING SEQUENCE:** |
---|
647 | |
---|
648 | .. code-block:: c |
---|
649 | |
---|
650 | #include <libio.h> |
---|
651 | int mount( |
---|
652 | rtems_filesystem_mount_table_entry_t **mt_entry, |
---|
653 | rtems_filesystem_operations_table *fs_ops, |
---|
654 | rtems_filesystem_options_t fsoptions, |
---|
655 | char *device, |
---|
656 | char *mount_point |
---|
657 | ); |
---|
658 | |
---|
659 | **STATUS CODES:** |
---|
660 | |
---|
661 | *EXXX* |
---|
662 | |
---|
663 | **DESCRIPTION:** |
---|
664 | |
---|
665 | The ``mount`` routines mounts the filesystem class which uses the filesystem |
---|
666 | operations specified by ``fs_ops`` and ``fsoptions``. The filesystem is |
---|
667 | mounted at the directory ``mount_point`` and the mode of the mounted filesystem |
---|
668 | is specified by ``fsoptions``. If this filesystem class requires a device, |
---|
669 | then the name of the device must be specified by ``device``. |
---|
670 | |
---|
671 | If this operation succeeds, the mount table entry for the mounted filesystem is |
---|
672 | returned in ``mt_entry``. |
---|
673 | |
---|
674 | **NOTES:** |
---|
675 | |
---|
676 | NONE |
---|
677 | |
---|
678 | .. _unmount: |
---|
679 | |
---|
680 | unmount - Unmount file systems |
---|
681 | ------------------------------ |
---|
682 | .. index:: unmount |
---|
683 | .. index:: unmount file systems |
---|
684 | |
---|
685 | **CALLING SEQUENCE:** |
---|
686 | |
---|
687 | .. code-block:: c |
---|
688 | |
---|
689 | #include <libio.h> |
---|
690 | int unmount( |
---|
691 | const char *mount_path |
---|
692 | ); |
---|
693 | |
---|
694 | **STATUS CODES:** |
---|
695 | |
---|
696 | *EXXX* |
---|
697 | |
---|
698 | **DESCRIPTION:** |
---|
699 | |
---|
700 | The ``unmount`` routine removes the attachment of the filesystem specified by |
---|
701 | ``mount_path``. |
---|
702 | |
---|
703 | **NOTES:** |
---|
704 | |
---|
705 | NONE |
---|
706 | |
---|
707 | .. _readv: |
---|
708 | |
---|
709 | readv - Vectored read from a file |
---|
710 | --------------------------------- |
---|
711 | .. index:: readv |
---|
712 | .. index:: vectored read from a file |
---|
713 | |
---|
714 | **CALLING SEQUENCE:** |
---|
715 | |
---|
716 | .. code-block:: c |
---|
717 | |
---|
718 | #include <sys/uio.h> |
---|
719 | ssize_t readv( |
---|
720 | int fd, |
---|
721 | const struct iovec *iov, |
---|
722 | int iovcnt |
---|
723 | ); |
---|
724 | |
---|
725 | **STATUS CODES:** |
---|
726 | |
---|
727 | In addition to the errors detected by *Input and Output Primitives Manager |
---|
728 | read - Reads from a file, read()*, this routine may return -1 and sets |
---|
729 | ``errno`` based upon the following errors: |
---|
730 | |
---|
731 | .. list-table:: |
---|
732 | :class: rtems-table |
---|
733 | |
---|
734 | * - ``EINVAL`` |
---|
735 | - The sum of the ``iov_len`` values in the iov array overflowed |
---|
736 | an ``ssize_t``. |
---|
737 | * - ``EINVAL`` |
---|
738 | - The ``iovcnt`` argument was less than or equal to 0, or greater than |
---|
739 | ``IOV_MAX``. |
---|
740 | |
---|
741 | **DESCRIPTION:** |
---|
742 | |
---|
743 | The ``readv()`` function is equivalent to ``read()`` except as described |
---|
744 | here. The ``readv()`` function shall place the input data into the ``iovcnt`` |
---|
745 | buffers specified by the members of the ``iov`` array: ``iov[0], iov[1], ..., |
---|
746 | iov[iovcnt-1]``. |
---|
747 | |
---|
748 | Each ``iovec`` entry specifies the base address and length of an area in memory |
---|
749 | where data should be placed. The ``readv()`` function always fills an area |
---|
750 | completely before proceeding to the next. |
---|
751 | |
---|
752 | **NOTES:** |
---|
753 | |
---|
754 | NONE |
---|
755 | |
---|
756 | .. _writev: |
---|
757 | |
---|
758 | writev - Vectored write to a file |
---|
759 | --------------------------------- |
---|
760 | .. index:: writev |
---|
761 | .. index:: vectored write to a file |
---|
762 | |
---|
763 | **CALLING SEQUENCE:** |
---|
764 | |
---|
765 | .. code-block:: c |
---|
766 | |
---|
767 | #include <sys/uio.h> |
---|
768 | ssize_t writev( |
---|
769 | int fd, |
---|
770 | const struct iovec *iov, |
---|
771 | int iovcnt |
---|
772 | ); |
---|
773 | |
---|
774 | **STATUS CODES:** |
---|
775 | |
---|
776 | In addition to the errors detected by *Input and Output Primitives Manager |
---|
777 | write - Write to a file, write()*, this routine may return -1 and sets |
---|
778 | ``errno`` based upon the following errors: |
---|
779 | |
---|
780 | .. list-table:: |
---|
781 | :class: rtems-table |
---|
782 | |
---|
783 | * - ``EINVAL`` |
---|
784 | - The sum of the ``iov_len`` values in the iov array overflowed |
---|
785 | an ``ssize_t``. |
---|
786 | * - ``EINVAL`` |
---|
787 | - The ``iovcnt`` argument was less than or equal to 0, or greater than |
---|
788 | ``IOV_MAX``. |
---|
789 | |
---|
790 | **DESCRIPTION:** |
---|
791 | |
---|
792 | The ``writev()`` function is equivalent to ``write()``, except as noted |
---|
793 | here. The ``writev()`` function gathers output data from the ``iovcnt`` buffers |
---|
794 | specified by the members of the ``iov array``: ``iov[0], iov[1], ..., |
---|
795 | iov[iovcnt-1]``. The ``iovcnt`` argument is valid if greater than 0 and less |
---|
796 | than or equal to ``IOV_MAX``. |
---|
797 | |
---|
798 | Each ``iovec`` entry specifies the base address and length of an area in memory |
---|
799 | from which data should be written. The ``writev()`` function always writes a |
---|
800 | complete area before proceeding to the next. |
---|
801 | |
---|
802 | If ``fd`` refers to a regular file and all of the ``iov_len`` members in the |
---|
803 | array pointed to by ``iov`` are 0, ``writev()`` returns 0 and has no other |
---|
804 | effect. For other file types, the behavior is unspecified by POSIX. |
---|
805 | |
---|
806 | **NOTES:** |
---|
807 | |
---|
808 | NONE |
---|
809 | |
---|
810 | .. _aio_read: |
---|
811 | |
---|
812 | aio_read - Asynchronous Read |
---|
813 | ---------------------------- |
---|
814 | .. index:: aio_read |
---|
815 | .. index:: asynchronous read |
---|
816 | |
---|
817 | **CALLING SEQUENCE:** |
---|
818 | |
---|
819 | .. code-block:: c |
---|
820 | |
---|
821 | int aio_read( |
---|
822 | ); |
---|
823 | |
---|
824 | **STATUS CODES:** |
---|
825 | |
---|
826 | .. list-table:: |
---|
827 | :class: rtems-table |
---|
828 | |
---|
829 | * - ``E`` |
---|
830 | - The |
---|
831 | |
---|
832 | **DESCRIPTION:** |
---|
833 | |
---|
834 | **NOTES:** |
---|
835 | |
---|
836 | This routine is not currently supported by RTEMS but could be in a future |
---|
837 | version. |
---|
838 | |
---|
839 | .. _aio_write: |
---|
840 | |
---|
841 | aio_write - Asynchronous Write |
---|
842 | ------------------------------ |
---|
843 | .. index:: aio_write |
---|
844 | .. index:: asynchronous write |
---|
845 | |
---|
846 | **CALLING SEQUENCE:** |
---|
847 | |
---|
848 | .. code-block:: c |
---|
849 | |
---|
850 | int aio_write( |
---|
851 | ); |
---|
852 | |
---|
853 | **STATUS CODES:** |
---|
854 | |
---|
855 | .. list-table:: |
---|
856 | :class: rtems-table |
---|
857 | |
---|
858 | * - ``E`` |
---|
859 | - The |
---|
860 | |
---|
861 | **DESCRIPTION:** |
---|
862 | |
---|
863 | **NOTES:** |
---|
864 | |
---|
865 | This routine is not currently supported by RTEMS but could be in a future |
---|
866 | version. |
---|
867 | |
---|
868 | .. _lio_listio: |
---|
869 | |
---|
870 | lio_listio - List Directed I/O |
---|
871 | ------------------------------ |
---|
872 | .. index:: lio_listio |
---|
873 | .. index:: list directed i/o |
---|
874 | |
---|
875 | **CALLING SEQUENCE:** |
---|
876 | |
---|
877 | .. code-block:: c |
---|
878 | |
---|
879 | int lio_listio( |
---|
880 | ); |
---|
881 | |
---|
882 | **STATUS CODES:** |
---|
883 | |
---|
884 | .. list-table:: |
---|
885 | :class: rtems-table |
---|
886 | |
---|
887 | * - ``E`` |
---|
888 | - The |
---|
889 | |
---|
890 | **DESCRIPTION:** |
---|
891 | |
---|
892 | **NOTES:** |
---|
893 | |
---|
894 | This routine is not currently supported by RTEMS but could be in a future |
---|
895 | version. |
---|
896 | |
---|
897 | .. _aio_error: |
---|
898 | |
---|
899 | aio_error - Retrieve Error Status of Asynchronous I/O Operation |
---|
900 | --------------------------------------------------------------- |
---|
901 | .. index:: aio_error |
---|
902 | .. index:: retrieve error status of asynchronous i/o operation |
---|
903 | |
---|
904 | **CALLING SEQUENCE:** |
---|
905 | |
---|
906 | .. code-block:: c |
---|
907 | |
---|
908 | int aio_error( |
---|
909 | ); |
---|
910 | |
---|
911 | **STATUS CODES:** |
---|
912 | |
---|
913 | .. list-table:: |
---|
914 | :class: rtems-table |
---|
915 | |
---|
916 | * - ``E`` |
---|
917 | - The |
---|
918 | |
---|
919 | **DESCRIPTION:** |
---|
920 | |
---|
921 | **NOTES:** |
---|
922 | |
---|
923 | This routine is not currently supported by RTEMS but could be in a future |
---|
924 | version. |
---|
925 | |
---|
926 | .. _aio_return: |
---|
927 | |
---|
928 | aio_return - Retrieve Return Status Asynchronous I/O Operation |
---|
929 | -------------------------------------------------------------- |
---|
930 | .. index:: aio_return |
---|
931 | .. index:: retrieve return status asynchronous i/o operation |
---|
932 | |
---|
933 | **CALLING SEQUENCE:** |
---|
934 | |
---|
935 | .. code-block:: c |
---|
936 | |
---|
937 | int aio_return( |
---|
938 | ); |
---|
939 | |
---|
940 | **STATUS CODES:** |
---|
941 | |
---|
942 | .. list-table:: |
---|
943 | :class: rtems-table |
---|
944 | |
---|
945 | * - ``E`` |
---|
946 | - The |
---|
947 | |
---|
948 | **DESCRIPTION:** |
---|
949 | |
---|
950 | **NOTES:** |
---|
951 | |
---|
952 | This routine is not currently supported by RTEMS but could be in a future |
---|
953 | version. |
---|
954 | |
---|
955 | .. _aio_cancel: |
---|
956 | |
---|
957 | aio_cancel - Cancel Asynchronous I/O Request |
---|
958 | -------------------------------------------- |
---|
959 | .. index:: aio_cancel |
---|
960 | .. index:: cancel asynchronous i/o request |
---|
961 | |
---|
962 | **CALLING SEQUENCE:** |
---|
963 | |
---|
964 | .. code-block:: c |
---|
965 | |
---|
966 | int aio_cancel( |
---|
967 | ); |
---|
968 | |
---|
969 | **STATUS CODES:** |
---|
970 | |
---|
971 | .. list-table:: |
---|
972 | :class: rtems-table |
---|
973 | |
---|
974 | * - ``E`` |
---|
975 | - The |
---|
976 | |
---|
977 | **DESCRIPTION:** |
---|
978 | |
---|
979 | **NOTES:** |
---|
980 | |
---|
981 | This routine is not currently supported by RTEMS but could be in a future |
---|
982 | version. |
---|
983 | |
---|
984 | .. _aio_suspend: |
---|
985 | |
---|
986 | aio_suspend - Wait for Asynchronous I/O Request |
---|
987 | ----------------------------------------------- |
---|
988 | .. index:: aio_suspend |
---|
989 | .. index:: wait for asynchronous i/o request |
---|
990 | |
---|
991 | **CALLING SEQUENCE:** |
---|
992 | |
---|
993 | .. code-block:: c |
---|
994 | |
---|
995 | int aio_suspend( |
---|
996 | ); |
---|
997 | |
---|
998 | **STATUS CODES:** |
---|
999 | |
---|
1000 | .. list-table:: |
---|
1001 | :class: rtems-table |
---|
1002 | |
---|
1003 | * - ``E`` |
---|
1004 | - The |
---|
1005 | |
---|
1006 | **DESCRIPTION:** |
---|
1007 | |
---|
1008 | **NOTES:** |
---|
1009 | |
---|
1010 | This routine is not currently supported by RTEMS but could be in a future |
---|
1011 | version. |
---|
1012 | |
---|
1013 | .. _aio_fsync: |
---|
1014 | |
---|
1015 | aio_fsync - Asynchronous File Synchronization |
---|
1016 | --------------------------------------------- |
---|
1017 | .. index:: aio_fsync |
---|
1018 | .. index:: asynchronous file synchronization |
---|
1019 | |
---|
1020 | **CALLING SEQUENCE:** |
---|
1021 | |
---|
1022 | .. code-block:: c |
---|
1023 | |
---|
1024 | int aio_fsync( |
---|
1025 | ); |
---|
1026 | |
---|
1027 | **STATUS CODES:** |
---|
1028 | |
---|
1029 | .. list-table:: |
---|
1030 | :class: rtems-table |
---|
1031 | |
---|
1032 | * - ``E`` |
---|
1033 | - The |
---|
1034 | |
---|
1035 | **DESCRIPTION:** |
---|
1036 | |
---|
1037 | **NOTES:** |
---|
1038 | |
---|
1039 | This routine is not currently supported by RTEMS but could be in a future |
---|
1040 | version. |
---|