source: rtems/doc/new_chapters/io.t @ b8ea1c8e

@c
@c  COPYRIGHT (c) 1988-1998.
@c  On-Line Applications Research Corporation (OAR).
@c  All rights reserved. 
@c
@c  $Id$
@c

@chapter Input and Output Primitives Manager

@section Introduction

The input and output primitives manager is ...

The directives provided by the input and output primitives manager are:

@itemize @bullet
@item @code{pipe} - YYY
@item @code{dup} - Duplicates an open file descriptor
@item @code{dup2} - Duplicates an open file descriptor
@item @code{close} - Closes a file
@item @code{read} - Reads from a file
@item @code{write} - Writes to a file
@item @code{fcntl} - Manipulates an open file descriptor
@item @code{lseek} - Reposition read/write file offset
@item @code{fsync} - Synchronize a file's complete in-core state with that on disk
@item @code{fdatasync} - synchronize a file's in-core data with that on disk
@item @code{mount} - Mount a file system
@item @code{umount} - Unmount file systems
@item @code{aio_read} - YYY
@item @code{aio_write} - YYY
@item @code{lio_listio} - YYY
@item @code{aio_error} - YYY
@item @code{aio_return} - YYY
@item @code{aio_cancel} - YYY
@item @code{aio_suspend} - YYY
@item @code{aio_fsync} - YYY
@end itemize

@section Background

There is currently no text in this section.

@section Operations

There is currently no text in this section.

@section Directives

This section details the input and output primitives manager's directives.
A subsection is dedicated to each of this manager's directives
and describes the calling sequence, related constants, usage,
and status codes.

@page
@subsection pipe - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int pipe(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection dup - Duplicates an open file descriptor

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <unistd.h>

int dup(
  int fildes
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
Invalid file descriptor.

@item EINTR
Function was interrupted by a signal.

@item EMFILE
The process already has the maximum number of file descriptors open 
and tried to open a new one.
@end table

@subheading DESCRIPTION:

The @code{dup} function returns the lowest numbered available file 
descriptor.  This new desciptor refers to the same open file as the
original descriptor and shares any locks.

@subheading NOTES: 

NONE

@page
@subsection dup2 - Duplicates an open file descriptor

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <unistd.h>

int dup2(
  int fildes,
  int fildes2
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
Invalid file descriptor.

@item EINTR
Function was interrupted by a signal.

@item EMFILE
The process already has the maximum number of file descriptors open 
and tried to open a new one.
@end table

@subheading DESCRIPTION:

@code{Dup2} creates a copy of the file descriptor @code{oldfd}.

The old and new descriptors may be used interchangeably.  They share locks, file
position pointers and flags; for example, if the file position is modified by using
@code{lseek} on one of the descriptors, the position is also changed for the other.

@subheading NOTES: 

NONE

@page
@subsection close - Closes a file. 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <unistd.h>

int close(
  int fildes
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
Invalid file descriptor

@item EINTR
Function was interrupted by a signal.
@end table

@subheading DESCRIPTION:

The @code{close()} function deallocates the file descriptor named by
@code{fildes} and makes it available for reuse.  All outstanding 
record locks owned by this process for the file are unlocked.

@subheading NOTES:

A signal can interrupt the @code{close()} function.  In that case,
@code{close()} returns -1 with @code{errno} set to EINTR.  The file
may or may not be closed.

@page
@subsection read - Reads from a file.

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <unistd.h>

int read(
  int           fildes,
  void         *buf,
  unsigned int  nbyte
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

On error, this routine returns -1 and sets @code{errno} to one of
the following:
 
@table @b
@item EAGAIN
The O_NONBLOCK flag is set for a file descriptor and the process
would be delayed in the I/O operation.

@item EBADF
Invalid file descriptor

@item EINTR
Function was interrupted by a signal.

@item EIO
Input or output error

@end table

@subheading DESCRIPTION:

The @code{read()} function reads @code{nbyte} bytes from the file 
associated with @code{fildes} into the buffer pointed to by @code{buf}.

The @code{read()} function returns the number of bytes actually read
and placed in the buffer. This will be less than @code{nbyte} if:

@itemize @bullet

@item The number of bytes left in the file is less than @code{nbyte}.

@item The @code{read()} request was interrupted by a signal.

@item The file is a pipe or FIFO or special file with less than @code{nbytes}
immediately available for reading.

@end itemize

When attempting to read from any empty pipe or FIFO:


@itemize @bullet

@item If no process has the pipe open for writing, zero is returned to 
indicate end-of-file.

@item If some process has the pipe open for writing and O_NONBLOCK is set,
-1 is returned and @code{errno} is set to EAGAIN.

@item If some process has the pipe open for writing and O_NONBLOCK is clear,
@code{read()} waits for some data to be written or the pipe to be closed.

@end itemize


When attempting to read from a file other than a pipe or FIFO and no data
is available.

@itemize @bullet

@item If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN.

@item If O_NONBLOCK is clear, @code{read()} waits for some data to become 
available.

@item The O_NONBLOCK flag is ignored if data is available.

@end itemize

@subheading NOTES:

NONE

@page
@subsection write - Writes to a file

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <unistd.h>

int write(
  int           fildes,
  const void   *buf,
  unsigned int  nbytes
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EAGAIN
The O_NONBLOCK flag is set for a file descriptor and the process
would be delayed in the I/O operation.

@item EBADF
Invalid file descriptor

@item EFBIG
An attempt was made to write to a file that exceeds the maximum file 
size

@item EINTR
The function was interrupted by a signal.

@item EIO
Input or output error.

@item ENOSPC
No space left on disk.

@item EPIPE
Attempt to write to a pope or FIFO with no reader.

@end table

@subheading DESCRIPTION:

The @code{write()} function writes @code{nbyte} from the array pointed
to by @code{buf} into the file associated with @code{fildes}.

If @code{nybte} is zero and the file is a regular file, the @code{write()}
function returns zero and has no other effect.  If @code{nbyte} is zero
and the file is a special file, te results are not portable.

The @code{write()} function returns the number of bytes written.  This 
number will be less than @code{nbytes} if there is an error.  It will never
be greater than @code{nbytes}.

@subheading NOTES: 

NONE

@page
@subsection fcntl - Manipulates an open file descriptor

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>

int fcntl(
  int   fildes,
  int   cmd
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EACCESS
Search permission is denied for a direcotry in a file's path
prefix.

@item EAGAIN
The O_NONBLOCK flag is set for a file descriptor and the process
would be delayed in the I/O operation.

@item EBADF
Invalid file descriptor

@item EDEADLK
An @code{fcntl} with function F_SETLKW would cause a deadlock.

@item EINTR
The functioin was interrupted by a signal.

@item EINVAL
Invalid argument

@item EMFILE
Too many file descriptor or in use by the process.

@item ENOLCK
No locks available

@end table

@subheading DESCRIPTION:

@code{fcntl()} performs one of various miscellaneous operations on
@code{fd}.  The operation in question is determined by @code{cmd}:

@table @b 

@item F_DUPFD  
Makes @code{arg} be a copy of @code{fd}, closing @code{fd} first if necessary.

The same functionality can be more easily achieved by using @code{dup2()}.

The old and new descriptors may be used interchangeably. They share locks, 
file position pointers and flags;  for example, if the file position is 
modified by using @code{lseek()} on one of the descriptors, the position is  
also changed for the other.

The two descriptors do not share the close-on-exec flag, however.  The 
close-on-exec flag of the copy is off, meaning that it will be closed on 
exec.

On success, the new descriptor is returned.

@item F_GETFD  
Read the close-on-exec flag.  If the low-order bit is 0, the file will 
remain open across exec, otherwise it will be closed.

@item F_SETFD  
Set the close-on-exec flag to the value specified by @code{arg} (only the least 
significant bit is used).

@item F_GETFL  
Read the descriptor's flags (all flags (as set by open()) are returned).

@item F_SETFL  
Set the descriptor's flags to the value specified by @code{arg}. Only  
@code{O_APPEND} and @code{O_NONBLOCK} may be set.

The flags are shared between copies (made with @code{dup()} etc.) of the same 
file descriptor.

The flags and their semantics are described in @code{open()}.

@item F_GETLK, F_SETLK and F_SETLKW
Manage discretionary file locks.  The third argument @code{arg} is a pointer to a 
struct flock (that may be overwritten by this call).

@item F_GETLK
Return the flock structure that prevents us from obtaining the lock, or set the
@code{l_type} field of the lock to @code{F_UNLCK} if there is no obstruction.

@item F_SETLK
The lock is set (when @code{l_type} is @code{F_RDLCK} or @code{F_WRLCK}) or 
cleared (when it is @code{F_UNLCK}.  If lock is held by someone else, this
call returns -1 and sets @code{errno} to EACCES or EAGAIN.

@item F_SETLKW 
Like @code{F_SETLK}, but instead of returning an error we wait for the lock to 
be released.

@item F_GETOWN 
Get the process ID (or process group) of the owner of a socket.

Process groups are returned as negative values.

@item F_SETOWN 
Set the process or process group that owns a socket.

For these commands, ownership means receiving @code{SIGIO} or @code{SIGURG}
signals.

Process groups are specified using negative  values.

@end table

@subheading NOTES:

The errors returned by @code{dup2} are different from those returned by
@code{F_DUPFD}.

@page
@subsection lseek - Reposition read/write file offset

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/types.h>
#include <unistd.h>

int lseek(
  int   fildes,
  off_t offset,
  int whence
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EBADF
@code{Fildes} is not an open file descriptor.

@item ESPIPE
@code{Fildes} is associated with a pipe, socket or FIFO. 

@item EINVAL
@code{Whence} is not a proper value. 

@end table

@subheading DESCRIPTION:

The @code{lseek} function repositions the offset of the file descriptor
@code{fildes} to the argument offset according to the directive whence.   
The argument @code{fildes} must be an open file descriptor. @code{Lseek}
repositions the file pointer fildes as follows:

@itemize @bullet

@item 
If @code{whence} is SEEK_SET, the offset is set to @code{offset} bytes.

@item 
If @code{whence} is SEEK_CUR, the offset is set to its current location
plus offset bytes.

@item 
If @code{whence} is SEEK_END, the offset is set to the size of the
file plus @code{offset} bytes.

@end itemize

The @code{lseek} function allows the file offset to be set beyond the end
of the existing end-of-file of the file. If data is later written at this
point, subsequent reads of the data in the gap return bytes of zeros
(until data is actually written into the gap).

Some devices are incapable of seeking.  The value of the pointer associated
with such a device is undefined.

@subheading NOTES: 

NONE

@page
@subsection fsync - Synchronize a file's complete in-core state with that on disk

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int fsync(
  int fd
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

On success, zero is returned.  On error, -1 is returned, and @code{errno}
is set appropriately.

@table @b
@item EBADF
@code{fd} is not a valid descriptor open for writing

@item EINVAL
@code{fd} is bound to a special file which does not support support synchronization

@item EROFS
@code{fd} is bound to a special file which does not support support synchronization

@item EIO
An error occurred during synchronization

@end table

@subheading DESCRIPTION:

@code{fsync} copies all in-core parts of a file to disk.

@subheading NOTES:

NONE

@page
@subsection fdatasync - synchronize a file's in-core data with that on disk. 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int fdatasync(
  int fd
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

On success, zero is returned.  On error, -1 is returned, and @code{errno} is
set appropriately.

@table @b
@item EBADF
@code{fd} is not a valid file descriptor open for writing.

@item EINVAL
@code{fd} is bound to a special file which does not support synchronization.

@item EIO
An error occurred during synchronization.

@item EROFS
@code{fd} is bound to a special file which dows not support synchronization.

@end table

@subheading DESCRIPTION:

@code{fdatasync} flushes all data buffers of a file to disk (before the system call
returns).  It resembles @code{fsync} but is not required to update the metadata such  
as access time.

Applications that access databases or log files often write a tiny data fragment
(e.g., one line in a log file) and then call @code{fsync} immediately in order to  
ensure that the written data is physically stored on the harddisk.  Unfortunately, 
fsync will always initiate two write operations: one for the newly written data and 
another one in order to update the modification time stored in the inode.  If the 
modification time is not a part of the transaction concept @code{fdatasync} can be 
used to avoid unnecessary inode disk write operations.

@subheading NOTES:

NONE

@page
@subsection mount - Mount a file system

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/mount.h>
#include <linux/fs.h>

int mount(
  const char *specialfile,
  const char * dir,
  const char * filesystemtype,
  unsigned long rwflag,
  const void * data
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EPERM
The user is not the super-user.

@item ENODEV
@code{filesystemtype} not configured in the kernel.

@item ENOTBLK
@code{specialfile} is not a block device (if a device was required).

@item EBUSY
@code{specialfile} is already mounted.  Or, it cannot be remounted
read-only, because it still holds files open for writing.  Or, it 
cannot be mounted on @code{dir} because @code{dir} is still busy
(it is the working directory of some task, the mount point of another
device, has open files, etc.).

@item EINVAL
@code{specialfile} had an invalid superblock.  Or, a remount was 
attempted, while @code{specialfile} was not already mounted on @code{dir}.
Or, an umount was attempted, while @code{dir} was not a mount point.

@item EFAULT
One of the pointer arguments points outside the user address space.

@item ENOMEM
The kernel could not allocate a free page to copy filenames or data into.

@item ENAMETOOLONG
A pathname was longer than MAXPATHLEN.

@item ENOTDIR
A pathname was empty or had a nonexistent component.

@item EACCES
A component of a path was not searchable.  Or, mounting a read-only 
filesystem was attempted without giving the MS_RDONLY flag.  Or, the 
block device @code{specialfile} is located on a filesystem mounted with
the MS_NODEV option.

@item ENXIO
The major number of the block device @code{specialfile} is out of
range.

@item EMFILE
(In case no block device is required:) Table of dummy devices is full.
              
@end table

@subheading DESCRIPTION:

@code{Mount} attaches the filesystem specified by @code{specialfile}
(which is often a device name) to the directory specified by @code{dir}.

Only the super-user may mount filesystems.

The @code{filesystemtype} argument may take one of the values listed in
/proc/filesystems (link "minix", "ext2", "msdos", "proc", "nfs", 
"iso9660" etc.).

The @code{rwflag} argument has the magic number 0xCOED in the top 16 bits,
and various mount flags in the low order 16 bits.  If the magic number is
absent, then the last two arguments are not used.

The @code{data} argument is interpreted by the different file systems.

@subheading NOTES:

NONE

@page
@subsection umount - Umount file systems

@subheading CALLING SEQUENCE:

@ifset is-C
@example
#include <sys/mount.h>
#include <linux/fs.h>

int umount(
  const char *specialfile
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EPERM
The user is not the super-user.

@item ENODEV
@code{Filesystemtype} not configured in the kernel.

@item ENOTBLK
@code{Specialfile} is not a block device (if a device was required).

@item EBUSY
@code{Specialfile} is already mounted.  Or, it cannot be remounted
read-only, because it still holds files open for writing.  Or, it 
cannot be mounted on @code{dir} because @code{dir} is still busy
(it is the working directory of some task, the mount point of another
device, has open files, etc.).

@item EINVAL
@code{specialfile} had an invalid superblock.  Or, a remount was 
attempted, while @code{specialfile} was not already mounted on @code{dir}.
Or, an umount was attempted, while @code{dir} was not a mount point.

@item EFAULT
One of the pointer arguments points outside the user address space.

@item ENOMEM
The kernel could not allocate a free page to copy filenames or data into.

@item ENAMETOOLONG
A pathname was longer than MAXPATHLEN.

@item ENOTDIR
A pathname was empty or had a nonexistent component.

@item EACCES
A component of a path was not searchable.  Or, mounting a read-only 
filesystem was attempted without giving the MS_RDONLY flag.  Or, the 
block device @code{specialfile} is located on a filesystem mounted with
the MS_NODEV option.

@item ENXIO
The major number of the block device @code{specialfile} is out of
range.

@item EMFILE
(In case no block device is required:) Table of dummy devices is full.

@end table

@subheading DESCRIPTION:

@code{Umount} removes the attachment of the filesystem specified
by @code{specialfile} or @code{dir}.

Only the super-user may umount filesystems.

@subheading NOTES: 

NONE

@page
@subsection aio_read - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_read(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_write - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_write(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection lio_listio - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int lio_listio(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_error - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_error(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_return - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_return(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_cancel - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_cancel(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_suspend - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_suspend(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.

@page
@subsection aio_fsync - 

@subheading CALLING SEQUENCE:

@ifset is-C
@example
int aio_fsync(
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

This routine is not currently supported by RTEMS but could be 
in a future version.