source: rtems/doc/new_chapters/io.t @ 0f58ab42

4.104.114.84.95
Last change on this file since 0f58ab42 was 0f58ab42, checked in by Wade A Smith <warm38@…>, on Sep 28, 1998 at 10:09:12 PM

Documented the mount and umount routines.

  • Property mode set to 100644
File size: 16.6 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{fsynch} - XXX
27@item @code{fdatasynch} - 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
42@section Operations
43
44@section Directives
45
46This section details the input and output primitives manager's directives.
47A subsection is dedicated to each of this manager's directives
48and describes the calling sequence, related constants, usage,
49and status codes.
50
51@page
52@subsection pipe -
53
54@subheading CALLING SEQUENCE:
55
56@ifset is-C
57@example
58int pipe(
59);
60@end example
61@end ifset
62
63@ifset is-Ada
64@end ifset
65
66@subheading STATUS CODES:
67
68@table @b
69@item E
70The
71
72@end table
73
74@subheading DESCRIPTION:
75
76@subheading NOTES:
77
78This routine is not currently supported by RTEMS but could be
79in a future version.
80
81@page
82@subsection dup - Duplicates an open file descriptor
83
84@subheading CALLING SEQUENCE:
85
86@ifset is-C
87@example
88#include <unistd.h>
89
90int dup(int fildes
91);
92@end example
93@end ifset
94
95@ifset is-Ada
96@end ifset
97
98@subheading STATUS CODES:
99
100@table @b
101@item EBADF
102Invalid file descriptor.
103@item EINTR
104Function was interrupted by a signal.
105@item EMFILE
106The process already has the maximum number of file descriptors open
107and tried to open a new one.
108@end table
109
110@subheading DESCRIPTION:
111
112The @code{dup} function returns the lowest numbered available file
113descriptor.  This new desciptor refers to the same open file as the
114original descriptor and shares any locks.
115
116@subheading NOTES: None
117
118@page
119@subsection dup2 - Duplicates an open file descriptor
120
121@subheading CALLING SEQUENCE:
122
123@ifset is-C
124@example
125#include <unistd.h>
126
127int dup2(int fildes,
128         int fildes2
129);
130@end example
131@end ifset
132
133@ifset is-Ada
134@end ifset
135
136@subheading STATUS CODES:
137
138@table @b
139@item EBADF
140Invalid file descriptor.
141@item EINTR
142Function was interrupted by a signal.
143@item EMFILE
144The process already has the maximum number of file descriptors open
145and tried to open a new one.
146@end table
147
148@subheading DESCRIPTION:
149
150@code{Dup2} creates a copy of the file descriptor @code{oldfd}.
151
152The old and new descriptors may be used interchangeably.  They share locks, file
153position pointers and flags; for example, if the file position is modified by using
154@code{lseek} on one of the descriptors, the position is also changed for the other.
155
156@subheading NOTES: None
157
158@page
159@subsection close - Closes a file.
160
161@subheading CALLING SEQUENCE:
162
163@ifset is-C
164@example
165#include <unistd.h>
166
167int close(int fildes
168);
169@end example
170@end ifset
171
172@ifset is-Ada
173@end ifset
174
175@subheading STATUS CODES:
176
177@table @b
178@item EBADF
179Invalid file descriptor
180@item EINTR
181Function was interrupted by a signal.
182@end table
183
184@subheading DESCRIPTION:
185
186The @code{close()} function deallocates the file descriptor named by
187@code{fildes} and makes it available for reuse.  All outstanding
188record locks owned by this process for the file are unlocked.
189
190@subheading NOTES:
191
192A signal can interrupt the @code{close()} function.  In that case,
193@code{close()} returns -1 with @code{errno} set to EINTR.  The file
194may or may not be closed.
195
196@page
197@subsection read - Reads from a file.
198
199@subheading CALLING SEQUENCE:
200
201@ifset is-C
202@example
203#include <unistd.h>
204
205int read(int f         ildes,
206         void         *buf,
207         unsigned int  nbyte
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 EAGAIN
219The
220@item EBADF
221Invalid file descriptor
222@item EINTR
223Function was interrupted by a signal.
224@item EIO
225Input or output error
226
227@end table
228
229@subheading DESCRIPTION:
230
231The @code{read()} function reads @code{nbyte} bytes from the file
232associated with @code{fildes} into the buffer pointed to by @code{buf}.
233
234The @code{read()} function returns the number of bytes actually read
235and placed in the buffer. This will be less than @code{nbyte} if:
236  - The number of bytes left in the file is less than @code{nbyte}
237  - The @code{read()} request was interrupted by a signal
238  - The file is a pipe or FIFO or special file with less than @code{nbytes}
239    immediately available for reading.
240
241When attempting to read from any empty pipe or FIFO:
242  - If no process has the pipe open for writing, zero is returned to
243    indicate end-of-file.
244  - If some process has the pipe open for writing and O_NONBLOCK is set,
245    -1 is returned and @code{errno} is set to EAGAIN.
246  - If some process has the pipe open for writing and O_NONBLOCK is clear,
247    @code{read()} waits for some data to be written or the pipe to be closed.
248
249When attempting to read from a file other than a pipe or FIFO and no data
250is available
251  - If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN.
252  - If O_NONBLOCK is clear, @code{read()} waits for some data to become
253    available.
254  - The O_NONBLOCK flag is ignored if data is available.
255
256@subheading NOTES: None
257
258@page
259@subsection write - Writes to a file
260
261@subheading CALLING SEQUENCE:
262
263@ifset is-C
264@example
265#include <unistd.h>
266
267int write(int         fildes,
268          const void *buf,
269          unsigned int nbytes
270);
271@end example
272@end ifset
273
274@ifset is-Ada
275@end ifset
276
277@subheading STATUS CODES:
278
279@table @b
280@item EAGAIN
281The O_NONBLOCK flag is set for a file descriptor and the process
282would be delayed in the I/O operation.
283@item EBADF
284Invalid file descriptor
285@item EFBIG
286The
287@item EINTR
288The function was interrupted by a signal.
289@item EIO
290Input or output error.
291@item ENOSPC
292No space left on disk.
293@item EPIPE
294Attempt to write to a pope or FIFO with no reader.
295
296@end table
297
298@subheading DESCRIPTION:
299
300The @code{write()} function writes @code{nbyte} from the array pointed
301to by @code{buf} into the file associated with @code{fildes}.
302
303If @code{nybte} is zero and the file is a regular file, the @code{write()}
304function returns zero and has no other effect.  If @code{nbyte} is zero
305and the file is a special file, te results are not portable.
306
307The @code{write()} function returns the number of bytes written.  This
308number will be less than @code{nbytes} if there is an error.  It will never
309be greater than @code{nbytes}.
310
311@subheading NOTES: None
312
313@page
314@subsection fcntl - Manipulates an open file descriptor
315
316@subheading CALLING SEQUENCE:
317
318@ifset is-C
319@example
320#include <sys/types.h>
321#include <fcntl.h>
322#include <unistd.h>
323
324int fcntl(int fildes,
325          int    cmd
326);
327@end example
328@end ifset
329
330@ifset is-Ada
331@end ifset
332
333@subheading STATUS CODES:
334
335@table @b
336@item EACCESS
337Search permission is denied for a direcotry in a file's path
338prefix.
339@item EAGAIN
340The O_NONBLOCK flag is set for a file descriptor and the process
341would be delayed in the I/O operation.
342@item EBADF
343Invalid file descriptor
344@item EDEADLK
345An @code{fcntl} with function F_SETLKW would cause a deadlock.
346@item EINTR
347The functioin was interrupted by a signal.
348@item EINVAL
349Invalid argument
350@item EMFILE
351Too many file descriptor or in use by the process.
352@item ENOLCK
353No locks available
354
355@end table
356
357@subheading DESCRIPTION:
358
359@subheading NOTES:
360
361@page
362@subsection lseek - Reposition read/write file offset
363
364@subheading CALLING SEQUENCE:
365
366@ifset is-C
367@example
368int lseek(
369  int   fildes,
370  off_t offset,
371  int whence
372);
373@end example
374@end ifset
375
376@ifset is-Ada
377@end ifset
378
379@subheading STATUS CODES:
380
381@table @b
382@item EBADF
383@code{Fildes} is not an open file descriptor.
384
385@item ESPIPE
386@code{Fildes} is associated with a pipe, socket or FIFO.
387
388@item EINVAL
389@code{Whence} is not a proper value.
390
391@end table
392
393@subheading DESCRIPTION:
394
395The @code{lseek} function repositions the offset of the file descriptor
396@code{fildes} to the argument offset according to the directive whence.   
397The argument @code{fildes} must be an open file descriptor. @code{Lseek}
398repositions the file pointer fildes as follows:
399
400  If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.
401
402  If @code{whence} is SEEK_CUR, the offset is set to its current location
403  plus offset bytes.
404
405  If @cdoe{whence} is SEEK_END, the offset is set to the size of the
406  file plus @cdoe{offset} bytes.
407
408The @cdoe{lseek} function allows the file offset to be set beyond the end
409of the existing end-of-file of the file. If data is later written at this
410point, subsequent reads of the data in the gap return bytes of zeros
411(until data is actually written into the gap).
412
413Some devices are incapable of seeking.  The value of the pointer asso-
414ciated with such a device is undefined.
415
416@subheading NOTES: None
417
418@page
419@subsection fsynch -
420
421@subheading CALLING SEQUENCE:
422
423@ifset is-C
424@example
425int fsynch(
426);
427@end example
428@end ifset
429
430@ifset is-Ada
431@end ifset
432
433@subheading STATUS CODES:
434
435@table @b
436@item E
437The
438
439@end table
440
441@subheading DESCRIPTION:
442
443@subheading NOTES:
444
445@page
446@subsection fdatasynch -
447
448@subheading CALLING SEQUENCE:
449
450@ifset is-C
451@example
452int fdatasynch(
453);
454@end example
455@end ifset
456
457@ifset is-Ada
458@end ifset
459
460@subheading STATUS CODES:
461
462@table @b
463@item E
464The
465
466@end table
467
468@subheading DESCRIPTION:
469
470@subheading NOTES:
471
472@page
473@subsection mount - Mount a file system
474
475@subheading CALLING SEQUENCE:
476
477@ifset is-C
478@example
479#include <sys/mount.h>
480#include <linux/fs.h>
481
482int mount(
483  const char *specialfile,
484  const char * dir,
485  const char * filesystemtype,
486  unsigned long rwflag,
487  const void * data
488);
489@end example
490@end ifset
491
492@ifset is-Ada
493@end ifset
494
495@subheading STATUS CODES:
496
497@table @b
498@item EPERM
499The user is not the super-user.
500
501@item ENODEV
502@code{Filesystemtype} not configured in the kernel.
503
504@item ENOTBLK
505@code{Specialfile} is not a block device (if a device was required).
506
507@item EBUSY
508@code{Specialfile} is already mounted.  Or, it cannot be remounted
509read-only, because it still holds files open for writing.  Or, it
510cannot be mounted on @code{dir} because @code{dir} is still busy
511(it is the working directory of some task, the mount point of another
512device, has open files, etc.).
513
514@item EINVAL
515@code{Specialfile had an invalid superblock.  Or, a remount was
516attempted, while @code{specialfile} was not already mounted on @code{dir}.
517Or, an umount was attempted, while @code{dir} was not a mount point.
518
519@item EFAULT
520One of the pointer arguments points outside the user address space.
521
522@item ENOMEM
523The kernel could not allocate a free page to copy filenames or data into.
524
525@item ENAMETOOLONG
526A pathname was longer than MAXPATHLEN.
527
528@item ENOTDIR
529A pathname was empty or had a nonexistent component.
530
531@item EACCES
532A component of a path was not searchable.  Or, mounting a read-only
533filesystem was attempted without giving the MS_RDONLY flag.  Or, the
534block device Specialfile is located on a filesystem mounted with
535the MS_NODEV option.
536
537@item ENXIO
538The major number of the block device @code{specialfile} is out of
539range.
540
541@item EMFILE
542(In case no block device is required:) Table of dummy devices is full.
543             
544@end table
545
546@subheading DESCRIPTION:
547
548@code{Mount} attaches the filesystem specified by @code{specialfile}
549(which is often a device name) to the directory specified by @code{dir}.
550
551Only the super-user may mount filesystems.
552
553The @code{filesystemtype} argument may take one of the values listed in
554/proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs",
555"iso9660" etc.).
556
557The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,
558and various mount flags in the low order 16 bits.  If the magic number is
559absent, then the last two arguments are not used.
560
561The @code{data} argument is interpreted by the different file systems.
562
563@subheading NOTES: None
564
565@page
566@subsection umount - Umount file systems
567
568@subheading CALLING SEQUENCE:
569
570@ifset is-C
571@example
572#include <sys/mount.h>
573#include <linux/fs.h>
574
575int umount(
576  const char *specialfile
577);
578@end example
579@end ifset
580
581@ifset is-Ada
582@end ifset
583
584@subheading STATUS CODES:
585
586@table @b
587@item EPERM
588The user is not the super-user.
589
590@item ENODEV
591@code{Filesystemtype} not configured in the kernel.
592
593@item ENOTBLK
594@code{Specialfile} is not a block device (if a device was required).
595
596@item EBUSY
597@code{Specialfile} is already mounted.  Or, it cannot be remounted
598read-only, because it still holds files open for writing.  Or, it
599cannot be mounted on @code{dir} because @code{dir} is still busy
600(it is the working directory of some task, the mount point of another
601device, has open files, etc.).
602
603@item EINVAL
604@code{Specialfile had an invalid superblock.  Or, a remount was
605attempted, while @code{specialfile} was not already mounted on @code{dir}.
606Or, an umount was attempted, while @code{dir} was not a mount point.
607
608@item EFAULT
609One of the pointer arguments points outside the user address space.
610
611@item ENOMEM
612The kernel could not allocate a free page to copy filenames or data into.
613
614@item ENAMETOOLONG
615A pathname was longer than MAXPATHLEN.
616
617@item ENOTDIR
618A pathname was empty or had a nonexistent component.
619
620@item EACCES
621A component of a path was not searchable.  Or, mounting a read-only
622filesystem was attempted without giving the MS_RDONLY flag.  Or, the
623block device Specialfile is located on a filesystem mounted with
624the MS_NODEV option.
625
626@item ENXIO
627The major number of the block device @code{specialfile} is out of
628range.
629
630@item EMFILE
631(In case no block device is required:) Table of dummy devices is full.
632
633@end table
634
635@subheading DESCRIPTION:
636
637@code{Umount} removes the attachment of the filesystem specified
638by @code{specialfile} or @code{dir}.
639
640Only the super-user may umount filesystems.
641
642@subheading NOTES: None
643
644@page
645@subsection aio_read -
646
647@subheading CALLING SEQUENCE:
648
649@ifset is-C
650@example
651int aio_read(
652);
653@end example
654@end ifset
655
656@ifset is-Ada
657@end ifset
658
659@subheading STATUS CODES:
660
661@table @b
662@item E
663The
664
665@end table
666
667@subheading DESCRIPTION:
668
669@subheading NOTES:
670
671This routine is not currently supported by RTEMS but could be
672in a future version.
673
674@page
675@subsection aio_write -
676
677@subheading CALLING SEQUENCE:
678
679@ifset is-C
680@example
681int aio_write(
682);
683@end example
684@end ifset
685
686@ifset is-Ada
687@end ifset
688
689@subheading STATUS CODES:
690
691@table @b
692@item E
693The
694
695@end table
696
697@subheading DESCRIPTION:
698
699@subheading NOTES:
700
701This routine is not currently supported by RTEMS but could be
702in a future version.
703
704@page
705@subsection lio_listio -
706
707@subheading CALLING SEQUENCE:
708
709@ifset is-C
710@example
711int lio_listio(
712);
713@end example
714@end ifset
715
716@ifset is-Ada
717@end ifset
718
719@subheading STATUS CODES:
720
721@table @b
722@item E
723The
724
725@end table
726
727@subheading DESCRIPTION:
728
729@subheading NOTES:
730
731This routine is not currently supported by RTEMS but could be
732in a future version.
733
734@page
735@subsection aio_error -
736
737@subheading CALLING SEQUENCE:
738
739@ifset is-C
740@example
741int aio_error(
742);
743@end example
744@end ifset
745
746@ifset is-Ada
747@end ifset
748
749@subheading STATUS CODES:
750
751@table @b
752@item E
753The
754
755@end table
756
757@subheading DESCRIPTION:
758
759@subheading NOTES:
760
761This routine is not currently supported by RTEMS but could be
762in a future version.
763
764@page
765@subsection aio_return -
766
767@subheading CALLING SEQUENCE:
768
769@ifset is-C
770@example
771int aio_return(
772);
773@end example
774@end ifset
775
776@ifset is-Ada
777@end ifset
778
779@subheading STATUS CODES:
780
781@table @b
782@item E
783The
784
785@end table
786
787@subheading DESCRIPTION:
788
789@subheading NOTES:
790
791This routine is not currently supported by RTEMS but could be
792in a future version.
793
794@page
795@subsection aio_cancel -
796
797@subheading CALLING SEQUENCE:
798
799@ifset is-C
800@example
801int aio_cancel(
802);
803@end example
804@end ifset
805
806@ifset is-Ada
807@end ifset
808
809@subheading STATUS CODES:
810
811@table @b
812@item E
813The
814
815@end table
816
817@subheading DESCRIPTION:
818
819@subheading NOTES:
820
821This routine is not currently supported by RTEMS but could be
822in a future version.
823
824@page
825@subsection aio_suspend -
826
827@subheading CALLING SEQUENCE:
828
829@ifset is-C
830@example
831int aio_suspend(
832);
833@end example
834@end ifset
835
836@ifset is-Ada
837@end ifset
838
839@subheading STATUS CODES:
840
841@table @b
842@item E
843The
844
845@end table
846
847@subheading DESCRIPTION:
848
849@subheading NOTES:
850
851This routine is not currently supported by RTEMS but could be
852in a future version.
853
854@page
855@subsection aio_fsync -
856
857@subheading CALLING SEQUENCE:
858
859@ifset is-C
860@example
861int aio_fsync(
862);
863@end example
864@end ifset
865
866@ifset is-Ada
867@end ifset
868
869@subheading STATUS CODES:
870
871@table @b
872@item E
873The
874
875@end table
876
877@subheading DESCRIPTION:
878
879@subheading NOTES:
880
881This routine is not currently supported by RTEMS but could be
882in a future version.
Note: See TracBrowser for help on using the repository browser.