summaryrefslogtreecommitdiffstats
path: root/posix_users/input_and_output.rst
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-02-26 18:22:07 +1100
committerAmar Takhar <verm@darkbeer.org>2016-05-02 20:51:26 -0400
commitfa70fd20878e402610c263f129266593d31a0376 (patch)
treec609d33c7047b975cfe8e0ac0df020fb26dae255 /posix_users/input_and_output.rst
parentUpdate the shell user's guide top level. (diff)
downloadrtems-docs-fa70fd20878e402610c263f129266593d31a0376.tar.bz2
POSIX User clean up.
Diffstat (limited to 'posix_users/input_and_output.rst')
-rw-r--r--posix_users/input_and_output.rst840
1 files changed, 453 insertions, 387 deletions
diff --git a/posix_users/input_and_output.rst b/posix_users/input_and_output.rst
index 4ecd4bc..638d000 100644
--- a/posix_users/input_and_output.rst
+++ b/posix_users/input_and_output.rst
@@ -1,3 +1,7 @@
+.. COMMENT: COPYRIGHT (c) 1988-2002.
+.. COMMENT: On-Line Applications Research Corporation (OAR).
+.. COMMENT: All rights reserved.
+
Input and Output Primitives Manager
###################################
@@ -8,51 +12,51 @@ The input and output primitives manager is ...
The directives provided by the input and output primitives manager are:
-- ``pipe`` - Create an Inter-Process Channel
+- pipe_ - Create an Inter-Process Channel
-- ``dup`` - Duplicates an open file descriptor
+- dup_ - Duplicates an open file descriptor
-- ``dup2`` - Duplicates an open file descriptor
+- dup2_ - Duplicates an open file descriptor
-- ``close`` - Closes a file
+- close_ - Closes a file
-- ``read`` - Reads from a file
+- read_ - Reads from a file
-- ``write`` - Writes to a file
+- write_ - Writes to a file
-- ``fcntl`` - Manipulates an open file descriptor
+- fcntl_ - Manipulates an open file descriptor
-- ``lseek`` - Reposition read/write file offset
+- lseek_ - Reposition read/write file offset
-- ``fsync`` - Synchronize file complete in-core state with that on disk
+- fsync_ - Synchronize file complete in-core state with that on disk
-- ``fdatasync`` - Synchronize file in-core data with that on disk
+- fdatasync_ - Synchronize file in-core data with that on disk
-- ``sync`` - Schedule file system updates
+- sync_ - Schedule file system updates
-- ``mount`` - Mount a file system
+- mount_ - Mount a file system
-- ``unmount`` - Unmount file systems
+- unmount_ - Unmount file systems
-- ``readv`` - Vectored read from a file
+- readv_ - Vectored read from a file
-- ``writev`` - Vectored write to a file
+- writev_ - Vectored write to a file
-- ``aio_read`` - Asynchronous Read
+- aio_read_ - Asynchronous Read
-- ``aio_write`` - Asynchronous Write
+- aio_write_ - Asynchronous Write
-- ``lio_listio`` - List Directed I/O
+- lio_listio_ - List Directed I/O
-- ``aio_error`` - Retrieve Error Status of Asynchronous I/O Operation
+- aio_error_ - Retrieve Error Status of Asynchronous I/O Operation
-- ``aio_return`` - Retrieve Return Status Asynchronous I/O Operation
+- aio_return_ - Retrieve Return Status Asynchronous I/O Operation
-- ``aio_cancel`` - Cancel Asynchronous I/O Request
+- aio_cancel_ - Cancel Asynchronous I/O Request
-- ``aio_suspend`` - Wait for Asynchronous I/O Request
+- aio_suspend_ - Wait for Asynchronous I/O Request
-- ``aio_fsync`` - Asynchronous File Synchronization
+- aio_fsync_ - Asynchronous File Synchronization
Background
==========
@@ -67,10 +71,11 @@ There is currently no text in this 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.
+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.
+
+.. _pipe:
pipe - Create an Inter-Process Channel
--------------------------------------
@@ -79,15 +84,18 @@ pipe - Create an Inter-Process Channel
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int pipe(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
@@ -96,6 +104,8 @@ pipe - Create an Inter-Process Channel
This routine is not currently supported by RTEMS but could be
in a future version.
+.. _dup:
+
dup - Duplicates an open file descriptor
----------------------------------------
.. index:: dup
@@ -103,35 +113,38 @@ dup - Duplicates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int dup(
- int fildes
+ int fildes
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor.
-
-*EINTR*
- Function was interrupted by a signal.
+.. list-table::
+ :class: rtems-table
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
+ * - ``EBADF``
+ - Invalid file descriptor.
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EMFILE``
+ - The process already has the maximum number of file descriptors open and
+ tried to open a new one.
**DESCRIPTION:**
The ``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.
+descriptor. This new desciptor refers to the same open file as the original
+descriptor and shares any locks.
**NOTES:**
NONE
+.. _dup2:
+
dup2 - Duplicates an open file descriptor
-----------------------------------------
.. index:: dup2
@@ -139,37 +152,42 @@ dup2 - Duplicates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int dup2(
- int fildes,
- int fildes2
+ int fildes,
+ int fildes2
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor.
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Function was interrupted by a signal.
-
-*EMFILE*
- The process already has the maximum number of file descriptors open
- and tried to open a new one.
+ * - ``EBADF``
+ - Invalid file descriptor.
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EMFILE``
+ - The process already has the maximum number of file descriptors open and
+ tried to open a new one.
**DESCRIPTION:**
``dup2`` creates a copy of the file descriptor ``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``lseek`` on one of the descriptors, the position is also changed for the other.
+position pointers and flags; for example, if the file position is modified by
+using ``lseek`` on one of the descriptors, the position is also changed for the
+other.
**NOTES:**
NONE
+.. _close:
+
close - Closes a file
---------------------
.. index:: close
@@ -177,30 +195,35 @@ close - Closes a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int close(
- int fildes
+ int fildes
);
**STATUS CODES:**
-*EBADF*
- Invalid file descriptor
+.. list-table::
+ :class: rtems-table
-*EINTR*
- Function was interrupted by a signal.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EINTR``
+ - Function was interrupted by a signal.
**DESCRIPTION:**
-The ``close()`` function deallocates the file descriptor named by``fildes`` and makes it available for reuse. All outstanding
-record locks owned by this process for the file are unlocked.
+The ``close()`` function deallocates the file descriptor named by ``fildes``
+and makes it available for reuse. All outstanding record locks owned by this
+process for the file are unlocked.
**NOTES:**
-A signal can interrupt the ``close()`` function. In that case,``close()`` returns -1 with ``errno`` set to EINTR. The file
-may or may not be closed.
+A signal can interrupt the ``close()`` function. In that case, ``close()``
+returns -1 with ``errno`` set to EINTR. The file may or may not be closed.
+
+.. _read:
read - Reads from a file
------------------------
@@ -209,43 +232,41 @@ read - Reads from a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int read(
- int fildes,
- void \*buf,
- unsigned int nbyte
+ int fildes,
+ void *buf,
+ unsigned int nbyte
);
**STATUS CODES:**
-On error, this routine returns -1 and sets ``errno`` to one of
-the following:
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EINTR*
- Function was interrupted by a signal.
+On error, this routine returns -1 and sets ``errno`` to one of the following:
-*EIO*
- Input or output error
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- Bad buffer pointer
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EINTR``
+ - Function was interrupted by a signal.
+ * - ``EIO``
+ - Input or output error
+ * - ``EINVAL``
+ - Bad buffer pointer
**DESCRIPTION:**
-The ``read()`` function reads ``nbyte`` bytes from the file
-associated with ``fildes`` into the buffer pointed to by ``buf``.
+The ``read()`` function reads ``nbyte`` bytes from the file associated with
+``fildes`` into the buffer pointed to by ``buf``.
-The ``read()`` function returns the number of bytes actually read
-and placed in the buffer. This will be less than ``nbyte`` if:
+The ``read()`` function returns the number of bytes actually read and placed in
+the buffer. This will be less than ``nbyte`` if:
- The number of bytes left in the file is less than ``nbyte``.
@@ -256,21 +277,21 @@ and placed in the buffer. This will be less than ``nbyte`` if:
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 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 ``errno`` is set to EAGAIN.
-- If some process has the pipe open for writing and O_NONBLOCK is clear,``read()`` waits for some data to be written or the pipe to be closed.
+- If some process has the pipe open for writing and O_NONBLOCK is clear,
+ ``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.
+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 ``errno`` is set to EAGAIN.
-- If O_NONBLOCK is clear, ``read()`` waits for some data to become
- available.
+- If O_NONBLOCK is clear, ``read()`` waits for some data to become available.
- The O_NONBLOCK flag is ignored if data is available.
@@ -278,6 +299,8 @@ is available.
NONE
+.. _write:
+
write - Writes to a file
------------------------
.. index:: write
@@ -285,60 +308,57 @@ write - Writes to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <unistd.h>
int write(
int fildes,
- const void \*buf,
- unsigned int nbytes
+ const void *buf,
+ unsigned int nbytes
);
**STATUS CODES:**
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EFBIG*
- An attempt was made to write to a file that exceeds the maximum file
- size
-
-*EINTR*
- The function was interrupted by a signal.
-
-*EIO*
- Input or output error.
-
-*ENOSPC*
- No space left on disk.
-
-*EPIPE*
- Attempt to write to a pope or FIFO with no reader.
-
-*EINVAL*
- Bad buffer pointer
+.. list-table::
+ :class: rtems-table
+
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EFBIG``
+ - An attempt was made to write to a file that exceeds the maximum file size
+ * - ``EINTR``
+ - The function was interrupted by a signal.
+ * - ``EIO``
+ - Input or output error.
+ * - ``ENOSPC``
+ - No space left on disk.
+ * - ``EPIPE``
+ - Attempt to write to a pope or FIFO with no reader.
+ * - ``EINVAL``
+ - Bad buffer pointer
**DESCRIPTION:**
-The ``write()`` function writes ``nbyte`` from the array pointed
-to by ``buf`` into the file associated with ``fildes``.
+The ``write()`` function writes ``nbyte`` from the array pointed to by ``buf``
+into the file associated with ``fildes``.
-If ``nybte`` is zero and the file is a regular file, the ``write()``
-function returns zero and has no other effect. If ``nbyte`` is zero
-and the file is a special file, te results are not portable.
+If ``nybte`` is zero and the file is a regular file, the ``write()`` function
+returns zero and has no other effect. If ``nbyte`` is zero and the file is a
+special file, te results are not portable.
-The ``write()`` function returns the number of bytes written. This
-number will be less than ``nbytes`` if there is an error. It will never
-be greater than ``nbytes``.
+The ``write()`` function returns the number of bytes written. This number will
+be less than ``nbytes`` if there is an error. It will never be greater than
+``nbytes``.
**NOTES:**
NONE
+.. _fcntl:
+
fcntl - Manipulates an open file descriptor
-------------------------------------------
.. index:: fcntl
@@ -346,106 +366,97 @@ fcntl - Manipulates an open file descriptor
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <fcntl.h>
#include <unistd.h>
int fcntl(
- int fildes,
- int cmd
+ int fildes,
+ int cmd
);
**STATUS CODES:**
-*EACCESS*
- Search permission is denied for a direcotry in a file's path
- prefix.
-
-*EAGAIN*
- The O_NONBLOCK flag is set for a file descriptor and the process
- would be delayed in the I/O operation.
-
-*EBADF*
- Invalid file descriptor
-
-*EDEADLK*
- An ``fcntl`` with function F_SETLKW would cause a deadlock.
-
-*EINTR*
- The functioin was interrupted by a signal.
-
-*EINVAL*
- Invalid argument
-
-*EMFILE*
- Too many file descriptor or in use by the process.
-
-*ENOLCK*
- No locks available
+.. list-table::
+ :class: rtems-table
+
+ * - ``EACCESS``
+ - Search permission is denied for a direcotry in a file's path prefix.
+ * - ``EAGAIN``
+ - The O_NONBLOCK flag is set for a file descriptor and the process would be
+ delayed in the I/O operation.
+ * - ``EBADF``
+ - Invalid file descriptor
+ * - ``EDEADLK``
+ - An ``fcntl`` with function ``F_SETLKW`` would cause a deadlock.
+ * - ``EINTR``
+ - The functioin was interrupted by a signal.
+ * - ``EINVAL``
+ - Invalid argument
+ * - ``EMFILE``
+ - Too many file descriptor or in use by the process.
+ * - ``ENOLCK``
+ - No locks available
**DESCRIPTION:**
-``fcntl()`` performs one of various miscellaneous operations on``fd``. The operation in question is determined by ``cmd``:
-
-*F_DUPFD*
- Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary.
- The same functionality can be more easily achieved by using ``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 ``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.
-
-*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.
-
-*F_SETFD*
- Set the close-on-exec flag to the value specified by ``arg`` (only the least
- significant bit is used).
-
-*F_GETFL*
- Read the descriptor's flags (all flags (as set by open()) are returned).
-
-*F_SETFL*
- Set the descriptor's flags to the value specified by ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set.
- The flags are shared between copies (made with ``dup()`` etc.) of the same
- file descriptor.
- The flags and their semantics are described in ``open()``.
-
-*F_GETLK, F_SETLK and F_SETLKW*
- Manage discretionary file locks. The third argument ``arg`` is a pointer to a
- struct flock (that may be overwritten by this call).
-
-*F_GETLK*
- Return the flock structure that prevents us from obtaining the lock, or set the``l_type`` field of the lock to ``F_UNLCK`` if there is no obstruction.
-
-*F_SETLK*
- The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or
- cleared (when it is ``F_UNLCK``. If lock is held by someone else, this
- call returns -1 and sets ``errno`` to EACCES or EAGAIN.
-
-*F_SETLKW*
- Like ``F_SETLK``, but instead of returning an error we wait for the lock to
- be released.
-
-*F_GETOWN*
- Get the process ID (or process group) of the owner of a socket.
- Process groups are returned as negative values.
-
-*F_SETOWN*
- Set the process or process group that owns a socket.
- For these commands, ownership means receiving ``SIGIO`` or ``SIGURG``
- signals.
- Process groups are specified using negative values.
+``fcntl()`` performs one of various miscellaneous operations on``fd``. The
+operation in question is determined by ``cmd``:
+
+.. list-table::
+ :class: rtems-table
+
+ * - ``F_DUPFD``
+ - Makes ``arg`` be a copy of ``fd``, closing ``fd`` first if necessary. The
+ same functionality can be more easily achieved by using ``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 ``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.
+ * - ``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.
+ * - ``F_SETFD``
+ - Set the close-on-exec flag to the value specified by ``arg`` (only the
+ least significant bit is used).
+ * - ``F_GETFL``
+ - Read the descriptor's flags (all flags (as set by open()) are returned).
+ * - ``F_SETFL``
+ - Set the descriptor's flags to the value specified by
+ ``arg``. Only``O_APPEND`` and ``O_NONBLOCK`` may be set. The flags are
+ shared between copies (made with ``dup()`` etc.) of the same file
+ descriptor. The flags and their semantics are described in ``open()``.
+ * - ``F_GETLK``, ``F_SETLK`` and ``F_SETLKW``
+ - Manage discretionary file locks. The third argument ``arg`` is a pointer
+ to a struct flock (that may be overwritten by this call).
+ * - ``F_GETLK``
+ - Return the flock structure that prevents us from obtaining the lock, or
+ set the``l_type`` field of the lock to ``F_UNLCK`` if there is no
+ obstruction.
+ * - ``F_SETLK``
+ - The lock is set (when ``l_type`` is ``F_RDLCK`` or ``F_WRLCK``) or cleared
+ (when it is ``F_UNLCK``. If lock is held by someone else, this call
+ returns -1 and sets ``errno`` to EACCES or EAGAIN.
+ * - ``F_SETLKW``
+ - Like ``F_SETLK``, but instead of returning an error we wait for the lock
+ to be released.
+ * - ``F_GETOWN``
+ - Get the process ID (or process group) of the owner of a socket. Process
+ groups are returned as negative values.
+ * - ``F_SETOWN``
+ - Set the process or process group that owns a socket. For these commands,
+ ownership means receiving ``SIGIO`` or ``SIGURG`` signals. Process groups
+ are specified using negative values.
**NOTES:**
-The errors returned by ``dup2`` are different from those returned by``F_DUPFD``.
+The errors returned by ``dup2`` are different from those returned by ``F_DUPFD``.
+
+.. _lseek:
lseek - Reposition read/write file offset
-----------------------------------------
@@ -454,32 +465,34 @@ lseek - Reposition read/write file offset
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/types.h>
#include <unistd.h>
int lseek(
- int fildes,
- off_t offset,
- int whence
+ int fildes,
+ off_t offset,
+ int whence
);
**STATUS CODES:**
-*EBADF*
- ``fildes`` is not an open file descriptor.
-
-*ESPIPE*
- ``fildes`` is associated with a pipe, socket or FIFO.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- ``whence`` is not a proper value.
+ * - ``EBADF``
+ - ``fildes`` is not an open file descriptor.
+ * - ``ESPIPE``
+ - ``fildes`` is associated with a pipe, socket or FIFO.
+ * - ``EINVAL``
+ - ``whence`` is not a proper value.
**DESCRIPTION:**
-The ``lseek`` function repositions the offset of the file descriptor``fildes`` to the argument offset according to the directive whence.
-The argument ``fildes`` must be an open file descriptor. ``Lseek``
-repositions the file pointer fildes as follows:
+The ``lseek`` function repositions the offset of the file descriptor ``fildes``
+to the argument offset according to the directive whence. The argument
+``fildes`` must be an open file descriptor. ``Lseek`` repositions the file
+pointer fildes as follows:
- If ``whence`` is SEEK_SET, the offset is set to ``offset`` bytes.
@@ -489,18 +502,20 @@ repositions the file pointer fildes as follows:
- If ``whence`` is SEEK_END, the offset is set to the size of the
file plus ``offset`` bytes.
-The ``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).
+The ``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.
+Some devices are incapable of seeking. The value of the pointer associated with
+such a device is undefined.
**NOTES:**
NONE
+.. _fsync:
+
fsync - Synchronize file complete in-core state with that on disk
-----------------------------------------------------------------
.. index:: fsync
@@ -508,28 +523,30 @@ fsync - Synchronize file complete in-core state with that on disk
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int fsync(
- int fd
+ int fd
);
**STATUS CODES:**
-On success, zero is returned. On error, -1 is returned, and ``errno``
-is set appropriately.
-
-*EBADF*
- ``fd`` is not a valid descriptor open for writing
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support support synchronization
+On success, zero is returned. On error, -1 is returned, and ``errno`` is set
+appropriately.
-*EROFS*
- ``fd`` is bound to a special file which does not support support synchronization
+.. list-table::
+ :class: rtems-table
-*EIO*
- An error occurred during synchronization
+ * - ``EBADF``
+ - ``fd`` is not a valid descriptor open for writing
+ * - ``EINVAL``
+ - ``fd`` is bound to a special file which does not support support
+ synchronization
+ * - ``EROFS``
+ - ``fd`` is bound to a special file which does not support support
+ synchronization
+ * - ``EIO``
+ - An error occurred during synchronization
**DESCRIPTION:**
@@ -539,6 +556,8 @@ is set appropriately.
NONE
+.. _fdatasync:
+
fdatasync - Synchronize file in-core data with that on disk
-----------------------------------------------------------
.. index:: fdatasync
@@ -546,47 +565,50 @@ fdatasync - Synchronize file in-core data with that on disk
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int fdatasync(
- int fd
+ int fd
);
**STATUS CODES:**
-On success, zero is returned. On error, -1 is returned, and ``errno`` is
-set appropriately.
-
-*EBADF*
- ``fd`` is not a valid file descriptor open for writing.
-
-*EINVAL*
- ``fd`` is bound to a special file which does not support synchronization.
+On success, zero is returned. On error, -1 is returned, and ``errno`` is set
+appropriately.
-*EIO*
- An error occurred during synchronization.
+.. list-table::
+ :class: rtems-table
-*EROFS*
- ``fd`` is bound to a special file which dows not support synchronization.
+ * - ``EBADF``
+ - ``fd`` is not a valid file descriptor open for writing.
+ * - ``EINVAL``
+ - ``fd`` is bound to a special file which does not support synchronization.
+ * - ``EIO``
+ - An error occurred during synchronization.
+ * - ``EROFS``
+ - ``fd`` is bound to a special file which dows not support synchronization.
**DESCRIPTION:**
-``fdatasync`` flushes all data buffers of a file to disk (before the system call
-returns). It resembles ``fsync`` but is not required to update the metadata such
-as access time.
+``fdatasync`` flushes all data buffers of a file to disk (before the system
+call returns). It resembles ``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 ``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 ``fdatasync`` can be
-used to avoid unnecessary inode disk write operations.
+Applications that access databases or log files often write a tiny data
+fragment (e.g., one line in a log file) and then call ``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 ``fdatasync`` can be used to avoid unnecessary inode disk
+write operations.
**NOTES:**
NONE
+.. _sync:
+
sync - Schedule file system updates
-----------------------------------
.. index:: sync
@@ -594,7 +616,7 @@ sync - Schedule file system updates
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
void sync(void);
@@ -604,14 +626,15 @@ NONE
**DESCRIPTION:**
-The ``sync`` service causes all information in memory that updates
-file systems to be scheduled for writing out to all file systems.
+The ``sync`` service causes all information in memory that updates file systems
+to be scheduled for writing out to all file systems.
**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 ``sync``.
+The writing of data to the file systems is only guaranteed to be scheduled upon
+return. It is not necessarily complete upon return from ``sync``.
+
+.. _mount:
mount - Mount a file system
---------------------------
@@ -620,15 +643,15 @@ mount - Mount a file system
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#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
+ rtems_filesystem_mount_table_entry_t **mt_entry,
+ rtems_filesystem_operations_table *fs_ops,
+ rtems_filesystem_options_t fsoptions,
+ char *device,
+ char *mount_point
);
**STATUS CODES:**
@@ -637,19 +660,21 @@ mount - Mount a file system
**DESCRIPTION:**
-The ``mount`` routines mounts the filesystem class
-which uses the filesystem operations specified by ``fs_ops``
-and ``fsoptions``. The filesystem is mounted at the directory``mount_point`` and the mode of the mounted filesystem is
-specified by ``fsoptions``. If this filesystem class requires
-a device, then the name of the device must be specified by ``device``.
+The ``mount`` routines mounts the filesystem class which uses the filesystem
+operations specified by ``fs_ops`` and ``fsoptions``. The filesystem is
+mounted at the directory ``mount_point`` and the mode of the mounted filesystem
+is specified by ``fsoptions``. If this filesystem class requires a device,
+then the name of the device must be specified by ``device``.
-If this operation succeeds, the mount table entry for the mounted
-filesystem is returned in ``mt_entry``.
+If this operation succeeds, the mount table entry for the mounted filesystem is
+returned in ``mt_entry``.
**NOTES:**
NONE
+.. _unmount:
+
unmount - Unmount file systems
------------------------------
.. index:: unmount
@@ -657,11 +682,11 @@ unmount - Unmount file systems
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <libio.h>
int unmount(
- const char \*mount_path
+ const char \*mount_path
);
**STATUS CODES:**
@@ -670,13 +695,15 @@ unmount - Unmount file systems
**DESCRIPTION:**
-The ``unmount`` routine removes the attachment of the filesystem specified
-by ``mount_path``.
+The ``unmount`` routine removes the attachment of the filesystem specified by
+``mount_path``.
**NOTES:**
NONE
+.. _readv:
+
readv - Vectored read from a file
---------------------------------
.. index:: readv
@@ -684,43 +711,48 @@ readv - Vectored read from a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/uio.h>
ssize_t readv(
- int fd,
- const struct iovec \*iov,
- int iovcnt
+ int fd,
+ const struct iovec *iov,
+ int iovcnt
);
**STATUS CODES:**
-In addition to the errors detected by``Input and Output Primitives Manager read - Reads from a file, read()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
+In addition to the errors detected by *Input and Output Primitives Manager
+read - Reads from a file, read()*, this routine may return -1 and sets
+``errno`` based upon the following errors:
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
+ * - ``EINVAL``
+ - The sum of the ``iov_len`` values in the iov array overflowed
+ an ``ssize_t``.
+ * - ``EINVAL``
+ - The ``iovcnt`` argument was less than or equal to 0, or greater than
+ ``IOV_MAX``.
**DESCRIPTION:**
-The ``readv()`` function is equivalent to ``read()``
-except as described here. The ``readv()`` function shall place
-the input data into the ``iovcnt`` buffers specified by the
-members of the ``iov`` array: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
+The ``readv()`` function is equivalent to ``read()`` except as described
+here. The ``readv()`` function shall place the input data into the ``iovcnt``
+buffers specified by the members of the ``iov`` array: ``iov[0], iov[1], ...,
+iov[iovcnt-1]``.
-Each ``iovec`` entry specifies the base address and length of an area
-in memory where data should be placed. The ``readv()`` function
-always fills an area completely before proceeding to the next.
+Each ``iovec`` entry specifies the base address and length of an area in memory
+where data should be placed. The ``readv()`` function always fills an area
+completely before proceeding to the next.
**NOTES:**
NONE
+.. _writev:
+
writev - Vectored write to a file
---------------------------------
.. index:: writev
@@ -728,50 +760,53 @@ writev - Vectored write to a file
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
#include <sys/uio.h>
ssize_t writev(
- int fd,
- const struct iovec \*iov,
- int iovcnt
+ int fd,
+ const struct iovec \*iov,
+ int iovcnt
);
**STATUS CODES:**
-In addition to the errors detected by``Input and Output Primitives Manager write - Write to a file, write()``,
-this routine may return -1 and sets ``errno`` based upon the following
-errors:
+In addition to the errors detected by *Input and Output Primitives Manager
+write - Write to a file, write()*, this routine may return -1 and sets
+``errno`` based upon the following errors:
-*EINVAL*
- The sum of the ``iov_len`` values in the iov array overflowed an``ssize_t``.
+.. list-table::
+ :class: rtems-table
-*EINVAL*
- The ``iovcnt`` argument was less than or equal to 0, or greater
- than ``IOV_MAX``.
+ * - ``EINVAL``
+ - The sum of the ``iov_len`` values in the iov array overflowed
+ an ``ssize_t``.
+ * - ``EINVAL``
+ - The ``iovcnt`` argument was less than or equal to 0, or greater than
+ ``IOV_MAX``.
**DESCRIPTION:**
-The ``writev()`` function is equivalent to ``write()``,
-except as noted here. The ``writev()`` function gathers output
-data from the ``iovcnt`` buffers specified by the members of
-the ``iov array``: ``iov[0], iov[1], ..., iov[iovcnt-1]``.
-The ``iovcnt`` argument is valid if greater than 0 and less
+The ``writev()`` function is equivalent to ``write()``, except as noted
+here. The ``writev()`` function gathers output data from the ``iovcnt`` buffers
+specified by the members of the ``iov array``: ``iov[0], iov[1], ...,
+iov[iovcnt-1]``. The ``iovcnt`` argument is valid if greater than 0 and less
than or equal to ``IOV_MAX``.
-Each ``iovec`` entry specifies the base address and length of
-an area in memory from which data should be written. The ``writev()``
-function always writes a complete area before proceeding to the next.
+Each ``iovec`` entry specifies the base address and length of an area in memory
+from which data should be written. The ``writev()`` function always writes a
+complete area before proceeding to the next.
-If ``fd`` refers to a regular file and all of the ``iov_len``
-members in the array pointed to by ``iov`` are 0, ``writev()``
-returns 0 and has no other effect. For other file types, the behavior
-is unspecified by POSIX.
+If ``fd`` refers to a regular file and all of the ``iov_len`` members in the
+array pointed to by ``iov`` are 0, ``writev()`` returns 0 and has no other
+effect. For other file types, the behavior is unspecified by POSIX.
**NOTES:**
NONE
+.. _aio_read:
+
aio_read - Asynchronous Read
----------------------------
.. index:: aio_read
@@ -779,22 +814,27 @@ aio_read - Asynchronous Read
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_read(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_write:
aio_write - Asynchronous Write
------------------------------
@@ -803,22 +843,27 @@ aio_write - Asynchronous Write
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_write(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _lio_listio:
lio_listio - List Directed I/O
------------------------------
@@ -827,22 +872,27 @@ lio_listio - List Directed I/O
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int lio_listio(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_error:
aio_error - Retrieve Error Status of Asynchronous I/O Operation
---------------------------------------------------------------
@@ -851,22 +901,27 @@ aio_error - Retrieve Error Status of Asynchronous I/O Operation
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_error(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_return:
aio_return - Retrieve Return Status Asynchronous I/O Operation
--------------------------------------------------------------
@@ -875,22 +930,27 @@ aio_return - Retrieve Return Status Asynchronous I/O Operation
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_return(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_cancel:
aio_cancel - Cancel Asynchronous I/O Request
--------------------------------------------
@@ -899,22 +959,27 @@ aio_cancel - Cancel Asynchronous I/O Request
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_cancel(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_suspend:
aio_suspend - Wait for Asynchronous I/O Request
-----------------------------------------------
@@ -923,22 +988,27 @@ aio_suspend - Wait for Asynchronous I/O Request
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_suspend(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
+This routine is not currently supported by RTEMS but could be in a future
+version.
+
+.. _aio_fsync:
aio_fsync - Asynchronous File Synchronization
---------------------------------------------
@@ -947,26 +1017,22 @@ aio_fsync - Asynchronous File Synchronization
**CALLING SEQUENCE:**
-.. code:: c
+.. code-block:: c
int aio_fsync(
);
**STATUS CODES:**
-*E*
- The
+.. list-table::
+ :class: rtems-table
+
+ * - ``E``
+ - The
**DESCRIPTION:**
**NOTES:**
-This routine is not currently supported by RTEMS but could be
-in a future version.
-
-.. COMMENT: COPYRIGHT (c) 1988-2002.
-
-.. COMMENT: On-Line Applications Research Corporation (OAR).
-
-.. COMMENT: All rights reserved.
-
+This routine is not currently supported by RTEMS but could be in a future
+version.