source: rtems/doc/new_chapters/io.t @ 80189ac2

4.104.114.84.95
Last change on this file since 80189ac2 was 80189ac2, checked in by Wade A Smith <warm38@…>, on Sep 29, 1998 at 9:51:52 PM

Made cosmetic changes, and document routines in the file.

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