source: rtems/doc/new_chapters/io.t @ 487c5d58

@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} - XXX
@item @code{fsynch} - XXX
@item @code{fdatasynch} - XXX
@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

@section Operations

@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:

@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 f         ildes,
         void         *buf,
         unsigned int  nbyte
);
@end example
@end ifset

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item EAGAIN
The
@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:
  - The number of bytes left in the file is less than @code{nbyte} 
  - The @code{read()} request was interrupted by a signal 
  - The file is a pipe or FIFO or special file with less than @code{nbytes}
    immediately available for reading.

When attempting to read from any empty pipe or FIFO:
  - If no process has the pipe open for writing, zero is returned to 
    indicate end-of-file.
  - If some process has the pipe open for writing and O_NONBLOCK is set,
    -1 is returned and @code{errno} is set to EAGAIN.
  - 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.

When attempting to read from a file other than a pipe or FIFO and no data
is available
  - If O_NONBLOCK is set, -1 is returned and @code{errno} is set to EAGAIN.
  - If O_NONBLOCK is clear, @code{read()} waits for some data to become 
    available.
  - The O_NONBLOCK flag is ignored if data is available.

@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
The
@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:

@subheading NOTES:

@page
@subsection lseek - 

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@subsection fsynch - 

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@page
@subsection fdatasynch - 

@subheading CALLING SEQUENCE:

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

@ifset is-Ada
@end ifset

@subheading STATUS CODES:

@table @b
@item E
The

@end table

@subheading DESCRIPTION:

@subheading NOTES:

@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:

@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:

@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:

@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:

@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:

@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:

@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:

@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.