source: rtems/doc/posix_users/io.t @ 421fae4

4.104.114.84.95
Last change on this file since 421fae4 was 421fae4, checked in by Joel Sherrill <joel.sherrill@…>, on Nov 29, 1999 at 3:11:15 PM

Removed bad descriptions of mount() and umount(). Added shell of an
accurate description.

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