1 files changed, 1144 insertions, 0 deletions
diff --git a/doc/posix_users/io.t b/doc/posix_users/io.t
new file mode 100644
index 0000000000..570772c543
--- /dev/null
+++ b/doc/posix_users/io.t
@@ -0,0 +1,1144 @@
+@c
+@c COPYRIGHT (c) 1988-2002.
+@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} - Create an Inter-Process Channel
+@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 file complete in-core state with that on disk
+@item @code{fdatasync} - Synchronize file in-core data with that on disk
+@item @code{sync} - Schedule file system updates
+@item @code{mount} - Mount a file system
+@item @code{unmount} - Unmount file systems
+@item @code{aio_read} - Asynchronous Read
+@item @code{aio_write} - Asynchronous Write
+@item @code{lio_listio} - List Directed I/O
+@item @code{aio_error} - Retrieve Error Status of Asynchronous I/O Operation
+@item @code{aio_return} - Retrieve Return Status Asynchronous I/O Operation
+@item @code{aio_cancel} - Cancel Asynchronous I/O Request
+@item @code{aio_suspend} - Wait for Asynchronous I/O Request
+@item @code{aio_fsync} - Asynchronous File Synchronization
+@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.
+
+@c
+@c
+@c
+@page
+@subsection pipe - Create an Inter-Process Channel
+
+@findex pipe
+@cindex  create an inter
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection dup - Duplicates an open file descriptor
+
+@findex dup
+@cindex  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
+
+@c
+@c
+@c
+@page
+@subsection dup2 - Duplicates an open file descriptor
+
+@findex dup2
+@cindex  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
+
+@c
+@c
+@c
+@page
+@subsection close - Closes a file.
+
+@findex close
+@cindex  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.
+
+@c
+@c
+@c
+@page
+@subsection read - Reads from a file.
+
+@findex read
+@cindex  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
+
+@c
+@c
+@c
+@page
+@subsection write - Writes to a file
+
+@findex write
+@cindex  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
+
+@c
+@c
+@c
+@page
+@subsection fcntl - Manipulates an open file descriptor
+
+@findex fcntl
+@cindex  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}.
+
+@c
+@c
+@c
+@page
+@subsection lseek - Reposition read/write file offset
+
+@findex lseek
+@cindex  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
+
+@c
+@c
+@c
+@page
+@subsection fsync - Synchronize file complete in-core state with that on disk
+
+@findex fsync
+@cindex  synchronize file complete in
+
+@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
+
+@c
+@c
+@c
+@page
+@subsection fdatasync - Synchronize file in-core data with that on disk.
+
+@findex fdatasync
+@cindex  synchronize file in
+
+@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
+
+@c
+@c
+@c
+@page
+@subsection sync - Schedule file system updates
+
+@findex sync
+@cindex  synchronize file systems
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+void sync(void);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+NONE
+
+@subheading DESCRIPTION:
+
+The @code{sync} service causes all information in memory that updates
+file systems to be scheduled for writing out to all file systems.
+
+
+@subheading NOTES:
+
+The writing of data to the file systems is only guaranteed to be 
+scheduled upon return.  It is not necessarily complete upon return
+from @code{sync}.
+
+@c
+@c
+@c
+@page
+@subsection mount - Mount a file system
+
+@findex mount
+@cindex  mount a file system
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+#include <libio.h>
+
+int mount(
+  rtems_filesystem_mount_table_entry_t **mt_entry,
+  rtems_filesystem_operations_table    *fs_ops,
+  rtems_filesystem_options_t            fsoptions,
+  char                                 *device,
+  char                                 *mount_point
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+@table @b
+@item EXXX
+
+@end table
+
+@subheading DESCRIPTION:
+
+The @code{mount} routines mounts the filesystem class
+which uses the filesystem operations specified by @code{fs_ops}
+and @code{fsoptions}.  The filesystem is mounted at the directory
+@code{mount_point} and the mode of the mounted filesystem is
+specified by @code{fsoptions}.  If this filesystem class requires
+a device, then the name of the device must be specified by @code{device}.
+
+If this operation succeeds, the mount table entry for the mounted
+filesystem is returned in @code{mt_entry}.
+
+@subheading NOTES:
+
+NONE
+
+@c
+@c
+@c
+@page
+@subsection unmount - Unmount file systems
+
+@findex unmount
+@cindex  unmount file systems
+
+@subheading CALLING SEQUENCE:
+
+@ifset is-C
+@example
+#include <libio.h>
+
+int unmount(
+  const char *mount_path
+);
+@end example
+@end ifset
+
+@ifset is-Ada
+@end ifset
+
+@subheading STATUS CODES:
+
+@table @b
+@item EXXX
+@end table
+
+@subheading DESCRIPTION:
+
+The @code{unmount} routine removes the attachment of the filesystem specified
+by @code{mount_path}.
+
+@subheading NOTES:
+
+NONE
+
+@c
+@c
+@c
+@page
+@subsection aio_read - Asynchronous Read
+
+@findex aio_read
+@cindex  asynchronous 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.
+
+@c
+@c
+@c
+@page
+@subsection aio_write - Asynchronous Write
+
+@findex aio_write
+@cindex  asynchronous 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.
+
+@c
+@c
+@c
+@page
+@subsection lio_listio - List Directed I/O
+
+@findex lio_listio
+@cindex  list directed i/o
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection aio_error - Retrieve Error Status of Asynchronous I/O Operation
+
+@findex aio_error
+@cindex  retrieve error status of asynchronous i/o operation
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection aio_return - Retrieve Return Status Asynchronous I/O Operation
+
+@findex aio_return
+@cindex  retrieve return status asynchronous i/o operation
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection aio_cancel - Cancel Asynchronous I/O Request
+
+@findex aio_cancel
+@cindex  cancel asynchronous i/o request
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection aio_suspend - Wait for Asynchronous I/O Request
+
+@findex aio_suspend
+@cindex  wait for asynchronous i/o request
+
+@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.
+
+@c
+@c
+@c
+@page
+@subsection aio_fsync - Asynchronous File Synchronization
+
+@findex aio_fsync
+@cindex  asynchronous file synchronization
+
+@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.