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