Changeset 80189ac2 in rtems


Ignore:
Timestamp:
Sep 29, 1998, 9:51:52 PM (21 years ago)
Author:
Wade A Smith <warm38@…>
Branches:
4.10, 4.11, 4.8, 4.9, master
Children:
6e62b72e
Parents:
f1ccfde
Message:

Made cosmetic changes, and document routines in the file.

File:
1 edited

Legend:

Unmodified
Added
Removed
  • doc/new_chapters/io.t

    rf1ccfde r80189ac2  
    2424@item @code{fcntl} - Manipulates an open file descriptor
    2525@item @code{lseek} - Reposition read/write file offset
    26 @item @code{fsynch} - XXX
    27 @item @code{fdatasynch} - XXX
     26@item @code{fsync} - XXX
     27@item @code{fdatasync} - XXX
    2828@item @code{mount} - Mount a file system
    2929@item @code{umount} - Unmount file systems
     
    4040@section Background
    4141
     42There is currently no text in this section.
     43
    4244@section Operations
     45
     46There is currently no text in this section.
    4347
    4448@section Directives
     
    101105@item EBADF
    102106Invalid file descriptor.
     107
    103108@item EINTR
    104109Function was interrupted by a signal.
     110
    105111@item EMFILE
    106112The process already has the maximum number of file descriptors open
     
    114120original descriptor and shares any locks.
    115121
    116 @subheading NOTES: None
     122@subheading NOTES:
     123
     124NONE
    117125
    118126@page
     
    125133#include <unistd.h>
    126134
    127 int dup2(int fildes,
    128          int fildes2
     135int dup2(
     136  int fildes,
     137  int fildes2
    129138);
    130139@end example
     
    139148@item EBADF
    140149Invalid file descriptor.
     150
    141151@item EINTR
    142152Function was interrupted by a signal.
     153
    143154@item EMFILE
    144155The process already has the maximum number of file descriptors open
     
    154165@code{lseek} on one of the descriptors, the position is also changed for the other.
    155166
    156 @subheading NOTES: None
     167@subheading NOTES:
     168
     169NONE
    157170
    158171@page
     
    178191@item EBADF
    179192Invalid file descriptor
     193
    180194@item EINTR
    181195Function was interrupted by a signal.
     
    203217#include <unistd.h>
    204218
    205 int 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 
     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 
    217235@table @b
    218236@item EAGAIN
    219237The
     238
    220239@item EBADF
    221240Invalid file descriptor
     241
    222242@item EINTR
    223243Function was interrupted by a signal.
     244
    224245@item EIO
    225246Input or output error
     
    234255The @code{read()} function returns the number of bytes actually read
    235256and 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.
     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
    240268
    241269When 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.
     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
    248285
    249286When attempting to read from a file other than a pipe or FIFO and no data
    250 is 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
     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
    257303
    258304@page
     
    281327The O_NONBLOCK flag is set for a file descriptor and the process
    282328would be delayed in the I/O operation.
     329
    283330@item EBADF
    284331Invalid file descriptor
     332
    285333@item EFBIG
    286334The
     335
    287336@item EINTR
    288337The function was interrupted by a signal.
     338
    289339@item EIO
    290340Input or output error.
     341
    291342@item ENOSPC
    292343No space left on disk.
     344
    293345@item EPIPE
    294346Attempt to write to a pope or FIFO with no reader.
     
    309361be greater than @code{nbytes}.
    310362
    311 @subheading NOTES: None
     363@subheading NOTES:
     364
     365NONE
    312366
    313367@page
     
    322376#include <unistd.h>
    323377
    324 int fcntl(int fildes,
    325           int    cmd
     378int fcntl(
     379  int   fildes,
     380  int   cmd
    326381);
    327382@end example
     
    337392Search permission is denied for a direcotry in a file's path
    338393prefix.
     394
    339395@item EAGAIN
    340396The O_NONBLOCK flag is set for a file descriptor and the process
    341397would be delayed in the I/O operation.
     398
    342399@item EBADF
    343400Invalid file descriptor
     401
    344402@item EDEADLK
    345403An @code{fcntl} with function F_SETLKW would cause a deadlock.
     404
    346405@item EINTR
    347406The functioin was interrupted by a signal.
     407
    348408@item EINVAL
    349409Invalid argument
     410
    350411@item EMFILE
    351412Too many file descriptor or in use by the process.
     413
    352414@item ENOLCK
    353415No locks available
     
    357419@subheading DESCRIPTION:
    358420
    359 @subheading NOTES:
     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}.
    360498
    361499@page
     
    366504@ifset is-C
    367505@example
     506#include <sys/types.h>
     507#include <unistd.h>
     508
    368509int lseek(
    369510  int   fildes,
     
    398539repositions the file pointer fildes as follows:
    399540
    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 
    408 The @cdoe{lseek} function allows the file offset to be set beyond the end
     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
    409557of the existing end-of-file of the file. If data is later written at this
    410558point, subsequent reads of the data in the gap return bytes of zeros
     
    414562ciated with such a device is undefined.
    415563
    416 @subheading NOTES: None
    417 
    418 @page
    419 @subsection fsynch -
    420 
    421 @subheading CALLING SEQUENCE:
    422 
    423 @ifset is-C
    424 @example
    425 int fsynch(
     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(
    426576);
    427577@end example
     
    444594
    445595@page
    446 @subsection fdatasynch -
    447 
    448 @subheading CALLING SEQUENCE:
    449 
    450 @ifset is-C
    451 @example
    452 int fdatasynch(
     596@subsection fdatasync -
     597
     598@subheading CALLING SEQUENCE:
     599
     600@ifset is-C
     601@example
     602int fdatasync(
    453603);
    454604@end example
     
    500650
    501651@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
    502743@code{Filesystemtype} not configured in the kernel.
    503744
     
    513754
    514755@item EINVAL
    515 @code{Specialfile had an invalid superblock.  Or, a remount was
     756@code{specialfile} had an invalid superblock.  Or, a remount was
    516757attempted, while @code{specialfile} was not already mounted on @code{dir}.
    517758Or, an umount was attempted, while @code{dir} was not a mount point.
     
    532773A component of a path was not searchable.  Or, mounting a read-only
    533774filesystem was attempted without giving the MS_RDONLY flag.  Or, the
    534 block device Specialfile is located on a filesystem mounted with
     775block device @code{specialfile} is located on a filesystem mounted with
    535776the MS_NODEV option.
    536777
     
    541782@item EMFILE
    542783(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 
    551 Only the super-user may mount filesystems.
    552 
    553 The @code{filesystemtype} argument may take one of the values listed in
    554 /proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs",
    555 "iso9660" etc.).
    556 
    557 The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,
    558 and various mount flags in the low order 16 bits.  If the magic number is
    559 absent, then the last two arguments are not used.
    560 
    561 The @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 
    575 int 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
    588 The 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
    598 read-only, because it still holds files open for writing.  Or, it
    599 cannot 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
    601 device, has open files, etc.).
    602 
    603 @item EINVAL
    604 @code{Specialfile had an invalid superblock.  Or, a remount was
    605 attempted, while @code{specialfile} was not already mounted on @code{dir}.
    606 Or, an umount was attempted, while @code{dir} was not a mount point.
    607 
    608 @item EFAULT
    609 One of the pointer arguments points outside the user address space.
    610 
    611 @item ENOMEM
    612 The kernel could not allocate a free page to copy filenames or data into.
    613 
    614 @item ENAMETOOLONG
    615 A pathname was longer than MAXPATHLEN.
    616 
    617 @item ENOTDIR
    618 A pathname was empty or had a nonexistent component.
    619 
    620 @item EACCES
    621 A component of a path was not searchable.  Or, mounting a read-only
    622 filesystem was attempted without giving the MS_RDONLY flag.  Or, the
    623 block device Specialfile is located on a filesystem mounted with
    624 the MS_NODEV option.
    625 
    626 @item ENXIO
    627 The major number of the block device @code{specialfile} is out of
    628 range.
    629 
    630 @item EMFILE
    631 (In case no block device is required:) Table of dummy devices is full.
    632784
    633785@end table
     
    640792Only the super-user may umount filesystems.
    641793
    642 @subheading NOTES: None
     794@subheading NOTES:
     795
     796NONE
    643797
    644798@page
Note: See TracChangeset for help on using the changeset viewer.