From fa70fd20878e402610c263f129266593d31a0376 Mon Sep 17 00:00:00 2001 From: Chris Johns Date: Fri, 26 Feb 2016 18:22:07 +1100 Subject: POSIX User clean up. --- posix_users/files_and_directory.rst | 2062 +++++++++++++++++------------------ 1 file changed, 1028 insertions(+), 1034 deletions(-) (limited to 'posix_users/files_and_directory.rst') diff --git a/posix_users/files_and_directory.rst b/posix_users/files_and_directory.rst index 7ebb8b4..a9d95c0 100644 --- a/posix_users/files_and_directory.rst +++ b/posix_users/files_and_directory.rst @@ -1,3 +1,7 @@ +.. COMMENT: COPYRIGHT (c) 1988-2002. +.. COMMENT: On-Line Applications Research Corporation (OAR). +.. COMMENT: All rights reserved. + Files and Directories Manager ############################# @@ -8,73 +12,73 @@ The files and directories manager is ... The directives provided by the files and directories manager are: -- ``opendir`` - Open a Directory +- opendir_ - Open a Directory -- ``readdir`` - Reads a directory +- readdir_ - Reads a directory -- ``rewinddir`` - Resets the ``readdir()`` pointer +- rewinddir_ - Resets the ``readdir()`` pointer -- ``scandir`` - Scan a directory for matching entries +- scandir_ - Scan a directory for matching entries -- ``telldir`` - Return current location in directory stream +- telldir_ - Return current location in directory stream -- ``closedir`` - Ends directory read operation +- closedir_ - Ends directory read operation -- ``getdents`` - Get directory entries +- getdents_ - Get directory entries -- ``chdir`` - Changes the current working directory +- chdir_ - Changes the current working directory -- ``fchdir`` - Changes the current working directory +- fchdir_ - Changes the current working directory -- ``getcwd`` - Gets current working directory +- getcwd_ - Gets current working directory -- ``open`` - Opens a file +- open_ - Opens a file -- ``creat`` - Create a new file or rewrite an existing one +- creat_ - Create a new file or rewrite an existing one -- ``umask`` - Sets a file creation mask +- umask_ - Sets a file creation mask -- ``link`` - Creates a link to a file +- link_ - Creates a link to a file -- ``symlink`` - Creates a symbolic link to a file +- symlink_ - Creates a symbolic link to a file -- ``readlink`` - Obtain the name of the link destination +- readlink_ - Obtain the name of the link destination -- ``mkdir`` - Makes a directory +- mkdir_ - Makes a directory -- ``mkfifo`` - Makes a FIFO special file +- mkfifo_ - Makes a FIFO special file -- ``unlink`` - Removes a directory entry +- unlink_ - Removes a directory entry -- ``rmdir`` - Delete a directory +- rmdir_ - Delete a directory -- ``rename`` - Renames a file +- rename_ - Renames a file -- ``stat`` - Gets information about a file. +- stat_ - Gets information about a file. -- ``fstat`` - Gets file status +- fstat_ - Gets file status -- ``lstat`` - Gets file status +- lstat_ - Gets file status -- ``access`` - Check permissions for a file. +- access_ - Check permissions for a file. -- ``chmod`` - Changes file mode +- chmod_ - Changes file mode -- ``fchmod`` - Changes permissions of a file +- fchmod_ - Changes permissions of a file -- ``chown`` - Changes the owner and/ or group of a file +- chown_ - Changes the owner and/ or group of a file -- ``utime`` - Change access and/or modification times of an inode +- utime_ - Change access and/or modification times of an inode -- ``ftruncate`` - Truncate a file to a specified length +- ftruncate_ - Truncate a file to a specified length -- ``truncate`` - Truncate a file to a specified length +- truncate_ - Truncate a file to a specified length -- ``pathconf`` - Gets configuration values for files +- pathconf_ - Gets configuration values for files -- ``fpathconf`` - Get configuration values for files +- fpathconf_ - Get configuration values for files -- ``mknod`` - Create a directory +- mknod_ - Create a directory Background ========== @@ -82,18 +86,17 @@ Background Path Name Evaluation -------------------- -A pathname is a string that consists of no more than ``PATH_MAX`` -bytes, including the terminating null character. A pathname has an optional -beginning slash, followed by zero or more filenames separated by slashes. -If the pathname refers to a directory, it may also have one or more trailing -slashes. Multiple successive slahes are considered to be the same as -one slash. +A pathname is a string that consists of no more than ``PATH_MAX`` bytes, +including the terminating null character. A pathname has an optional beginning +slash, followed by zero or more filenames separated by slashes. If the +pathname refers to a directory, it may also have one or more trailing +slashes. Multiple successive slahes are considered to be the same as one slash. POSIX allows a pathname that begins with precisely two successive slashes to be interpreted in an implementation-defined manner. RTEMS does not currently -recognize this as a special condition. Any number of successive -slashes is treated the same as a single slash. POSIX requires that -an implementation treat more than two leading slashes as a single slash. +recognize this as a special condition. Any number of successive slashes is +treated the same as a single slash. POSIX requires that an implementation treat +more than two leading slashes as a single slash. Operations ========== @@ -103,10 +106,11 @@ There is currently no text in this section. Directives ========== -This section details the files and directories 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 files and directories 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. + +.. _opendir: opendir - Open a Directory -------------------------- @@ -115,34 +119,32 @@ opendir - Open a Directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int opendir( - const char \*dirname + const char *dirname ); **STATUS CODES:** -*EACCES* - Search permission was denied on a component of the path - prefix of ``dirname``, or read permission is denied - -*EMFILE* - Too many file descriptors in use by process - -*ENFILE* - Too many files are currently open in the system. - -*ENOENT* - Directory does not exist, or ``name`` is an empty string. - -*ENOMEM* - Insufficient memory to complete the operation. - -*ENOTDIR* - ``name`` is not a directory. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission was denied on a component of the path prefix of + ``dirname``, or read permission is denied + * - ``EMFILE`` + - Too many file descriptors in use by process + * - ``ENFILE`` + - Too many files are currently open in the system. + * - ``ENOENT`` + - Directory does not exist, or ``name`` is an empty string. + * - ``ENOMEM`` + - Insufficient memory to complete the operation. + * - ``ENOTDIR`` + - ``name`` is not a directory. **DESCRIPTION:** @@ -154,6 +156,8 @@ directory stream is positioned at the first entry. The routine is implemented in Cygnus newlib. +.. _readdir: + readdir - Reads a directory --------------------------- .. index:: readdir @@ -161,37 +165,45 @@ readdir - Reads a directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include - int readdir( - DIR \*dirp + int readdir( + DIR *dirp ); **STATUS CODES:** -*EBADF* - Invalid file descriptor +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid file descriptor **DESCRIPTION:** The ``readdir()`` function returns a pointer to a structure ``dirent`` -representing the next directory entry from the directory stream pointed to -by ``dirp``. On end-of-file, NULL is returned. +representing the next directory entry from the directory stream pointed to by +``dirp``. On end-of-file, ``NULL`` is returned. -The ``readdir()`` function may (or may not) return entries for . or .. Your -program should tolerate reading dot and dot-dot but not require them. +The ``readdir()`` function may (or may not) return entries for ``.`` or ``..`` +Your program should tolerate reading dot and dot-dot but not require them. -The data pointed to be ``readdir()`` may be overwritten by another call to``readdir()`` for the same directory stream. It will not be overwritten by -a call for another directory. +The data pointed to be ``readdir()`` may be overwritten by another call to +``readdir()`` for the same directory stream. It will not be overwritten by a +call for another directory. **NOTES:** -If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or``realloc()`` or has been deallocated with ``free()`` or``realloc()``, the results are not portable and are probably disastrous. +If ``ptr`` is not a pointer returned by ``malloc()``, ``calloc()``, or +``realloc()`` or has been deallocated with ``free()`` or ``realloc()``, the +results are not portable and are probably disastrous. The routine is implemented in Cygnus newlib. +.. _rewinddir: + rewinddir - Resets the readdir() pointer ---------------------------------------- .. index:: rewinddir @@ -199,12 +211,12 @@ rewinddir - Resets the readdir() pointer **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include void rewinddir( - DIR \*dirp + DIR *dirp ); **STATUS CODES:** @@ -213,19 +225,20 @@ No value is returned. **DESCRIPTION:** -The ``rewinddir()`` function resets the position associated with -the directory stream pointed to by ``dirp``. It also causes the -directory stream to refer to the current state of the directory. +The ``rewinddir()`` function resets the position associated with the directory +stream pointed to by ``dirp``. It also causes the directory stream to refer to +the current state of the directory. **NOTES:** NONE -If ``dirp`` is not a pointer by ``opendir()``, the results are -undefined. +If ``dirp`` is not a pointer by ``opendir()``, the results are undefined. The routine is implemented in Cygnus newlib. +.. _scandir: + scandir - Scan a directory for matching entries ----------------------------------------------- .. index:: scandir @@ -233,33 +246,39 @@ scandir - Scan a directory for matching entries **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int scandir( - const char \*dir, - struct dirent \***namelist, - int (\*select)(const struct dirent \*), - int (\*compar)(const struct dirent \**, const struct dirent \**) + const char *dir, + struct dirent ***namelist, + int (*select)(const struct dirent *), + int (*compar)(const struct dirent **, const struct dirent **) ); **STATUS CODES:** -*ENOMEM* - Insufficient memory to complete the operation. +.. list-table:: + :class: rtems-table + + * - ``ENOMEM`` + - Insufficient memory to complete the operation. **DESCRIPTION:** -The ``scandir()`` function scans the directory ``dir``, calling``select()`` on each directory entry. Entries for which ``select()`` -returns non-zero are stored in strings allocated via ``malloc()``, -sorted using ``qsort()`` with the comparison function ``compar()``, -and collected in array ``namelist`` which is allocated via ``malloc()``. -If ``select`` is NULL, all entries are selected. +The ``scandir()`` function scans the directory ``dir``, calling ``select()`` on +each directory entry. Entries for which ``select()`` returns non-zero are +stored in strings allocated via ``malloc()``, sorted using ``qsort()`` with the +comparison function ``compar()``, and collected in array ``namelist`` which is +allocated via ``malloc()``. If ``select`` is ``NULL``, all entries are +selected. **NOTES:** The routine is implemented in Cygnus newlib. +.. _telldir: + telldir - Return current location in directory stream ----------------------------------------------------- .. index:: telldir @@ -267,17 +286,20 @@ telldir - Return current location in directory stream **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include off_t telldir( - DIR \*dir + DIR *dir ); **STATUS CODES:** -*EBADF* - Invalid directory stream descriptor ``dir``. +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid directory stream descriptor ``dir``. **DESCRIPTION:** @@ -288,6 +310,8 @@ directory stream ``dir``. The routine is implemented in Cygnus newlib. +.. _closedir: + closedir - Ends directory read operation ---------------------------------------- .. index:: closedir @@ -295,33 +319,38 @@ closedir - Ends directory read operation **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int closedir( - DIR \*dirp + DIR *dirp ); **STATUS CODES:** -*EBADF* - Invalid file descriptor +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid file descriptor **DESCRIPTION:** -The directory stream associated with ``dirp`` is closed. -The value in ``dirp`` may not be usable after a call to``closedir()``. +The directory stream associated with ``dirp`` is closed. The value in ``dirp`` +may not be usable after a call to ``closedir()``. **NOTES:** NONE -The argument to ``closedir()`` must be a pointer returned by``opendir()``. If it is not, the results are not portable and -most likely unpleasant. +The argument to ``closedir()`` must be a pointer returned by ``opendir()``. If +it is not, the results are not portable and most likely unpleasant. The routine is implemented in Cygnus newlib. +.. _chdir: + chdir - Changes the current working directory --------------------------------------------- .. index:: chdir @@ -329,45 +358,45 @@ chdir - Changes the current working directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int chdir( - const char \*path + const char *path ); **STATUS CODES:** -On error, this routine returns -1 and sets ``errno`` to one of -the following: - -*EACCES* - Search permission is denied for a directory in a file's path prefix. +On error, this routine returns -1 and sets ``errno`` to one of the following: -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is - in effect. +.. list-table:: + :class: rtems-table -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified pathname was not a directory when directory - was expected. + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when directory + was expected. **DESCRIPTION:** -The ``chdir()`` function causes the directory named by ``path`` to -become the current working directory; that is, the starting point for -searches of pathnames not beginning with a slash. +The ``chdir()`` function causes the directory named by ``path`` to become the +current working directory; that is, the starting point for searches of +pathnames not beginning with a slash. -If ``chdir()`` detects an error, the current working directory is not -changed. +If ``chdir()`` detects an error, the current working directory is not changed. **NOTES:** NONE +.. _fchdir: + fchdir - Changes the current working directory ---------------------------------------------- .. index:: fchdir @@ -375,45 +404,45 @@ fchdir - Changes the current working directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int fchdir( - int fd + int fd ); **STATUS CODES:** -On error, this routine returns -1 and sets ``errno`` to one of -the following: +On error, this routine returns -1 and sets ``errno`` to one of the following: -*EACCES* - Search permission is denied for a directory in a file's path prefix. +.. list-table:: + :class: rtems-table -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is - in effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified pathname was not a directory when directory - was expected. + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when directory + was expected. **DESCRIPTION:** -The ``fchdir()`` function causes the directory named by ``fd`` to -become the current working directory; that is, the starting point for -searches of pathnames not beginning with a slash. +The ``fchdir()`` function causes the directory named by ``fd`` to become the +current working directory; that is, the starting point for searches of +pathnames not beginning with a slash. -If ``fchdir()`` detects an error, the current working directory is not -changed. +If ``fchdir()`` detects an error, the current working directory is not changed. **NOTES:** NONE +.. _getcwd: + getcwd - Gets current working directory --------------------------------------- .. index:: getcwd @@ -421,38 +450,41 @@ getcwd - Gets current working directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int getcwd( void ); **STATUS CODES:** -*EINVAL* - Invalid argument - -*ERANGE* - Result is too large +.. list-table:: + :class: rtems-table -*EACCES* - Search permission is denied for a directory in a file's path prefix. + * - ``EINVAL`` + - Invalid argument + * - ``ERANGE`` + - Result is too large + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. **DESCRIPTION:** -The ``getcwd()`` function copies the absolute pathname of the current -working directory to the character array pointed to by ``buf``. The``size`` argument is the number of bytes available in ``buf`` +The ``getcwd()`` function copies the absolute pathname of the current working +directory to the character array pointed to by ``buf``. The ``size`` argument +is the number of bytes available in ``buf`` **NOTES:** -There is no way to determine the maximum string length that ``fetcwd()`` -may need to return. Applications should tolerate getting ``ERANGE`` -and allocate a larger buffer. +There is no way to determine the maximum string length that ``fetcwd()`` may +need to return. Applications should tolerate getting ``ERANGE`` and allocate a +larger buffer. -It is possible for ``getcwd()`` to return EACCES if, say, ``login`` -puts the process into a directory without read access. +It is possible for ``getcwd()`` to return EACCES if, say, ``login`` puts the +process into a directory without read access. -The 1988 standard uses ``int`` instead of ``size_t`` for the second -parameter. +The 1988 standard uses ``int`` instead of ``size_t`` for the second parameter. + +.. _open: open - Opens a file ------------------- @@ -461,113 +493,104 @@ open - Opens a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include #include int open( - const char \*path, - int oflag, - mode_t mode + const char *path, + int oflag, + mode_t mode ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix. - -*EEXIST* - The named file already exists. - -*EINTR* - Function was interrupted by a signal. - -*EISDIR* - Attempt to open a directory for writing or to rename a file to be a - directory. - -*EMFILE* - Too many file descriptors are in use by this process. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENFILE* - Too many files are currently open in the system. - -*ENOENT* - A file or directory does not exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*ENXIO* - No such device. This error may also occur when a device is not ready, for - example, a tape drive is off-line. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``EEXIST`` + - The named file already exists. + * - ``EINTR`` + - Function was interrupted by a signal. + * - ``EISDIR`` + - Attempt to open a directory for writing or to rename a file to be a + directory. + * - ``EMFILE`` + - Too many file descriptors are in use by this process. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENFILE`` + - Too many files are currently open in the system. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``ENXIO`` + - No such device. This error may also occur when a device is not ready, for + example, a tape drive is off-line. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** The ``open`` function establishes a connection between a file and a file descriptor. The file descriptor is a small integer that is used by I/O -functions to reference the file. The ``path`` argument points to the -pathname for the file. - -The ``oflag`` argument is the bitwise inclusive OR of the values of -symbolic constants. The programmer must specify exactly one of the following -three symbols: +functions to reference the file. The ``path`` argument points to the pathname +for the file. -*O_RDONLY* - Open for reading only. +The ``oflag`` argument is the bitwise inclusive OR of the values of symbolic +constants. The programmer must specify exactly one of the following three +symbols: -*O_WRONLY* - Open for writing only. +.. list-table:: + :class: rtems-table -*O_RDWR* - Open for reading and writing. + * - ``O_RDONLY`` + - Open for reading only. + * - ``O_WRONLY`` + - Open for writing only. + * - ``O_RDWR`` + - Open for reading and writing. Any combination of the following symbols may also be used. -*O_APPEND* - Set the file offset to the end-of-file prior to each write. - -*O_CREAT* - If the file does not exist, allow it to be created. This flag indicates - that the ``mode`` argument is present in the call to ``open``. - -*O_EXCL* - This flag may be used only if O_CREAT is also set. It causes the call - to ``open`` to fail if the file already exists. - -*O_NOCTTY* - If ``path`` identifies a terminal, this flag prevents that teminal from - becoming the controlling terminal for thi9s process. See Chapter 8 for a - description of terminal I/O. - -*O_NONBLOCK* - Do no wait for the device or file to be ready or available. After the file - is open, the ``read`` and ``write`` calls return immediately. If the - process would be delayed in the read or write opermation, -1 is returned and``errno`` is set to ``EAGAIN`` instead of blocking the caller. - -*O_TRUNC* - This flag should be used only on ordinary files opened for writing. It - causes the file to be tuncated to zero length.. - -Upon successful completion, ``open`` returns a non-negative file -descriptor. +.. list-table:: + :class: rtems-table + + * - ``O_APPEND`` + - Set the file offset to the end-of-file prior to each write. + * - ``O_CREAT`` + - If the file does not exist, allow it to be created. This flag indicates + that the ``mode`` argument is present in the call to ``open``. + * - ``O_EXCL`` + - This flag may be used only if ``O_CREAT`` is also set. It causes the call + to ``open`` to fail if the file already exists. + * - ``O_NOCTTY`` + - Do not assign controlling terminal. + * - ``O_NONBLOCK`` + - Do no wait for the device or file to be ready or available. After the file + is open, the ``read`` and ``write`` calls return immediately. If the + process would be delayed in the read or write opermation, -1 is returned + and``errno`` is set to ``EAGAIN`` instead of blocking the caller. + * - ``O_TRUNC`` + - This flag should be used only on ordinary files opened for writing. It + causes the file to be tuncated to zero length.. + +Upon successful completion, ``open`` returns a non-negative file descriptor. **NOTES:** NONE +.. _creat: + creat - Create a new file or rewrite an existing one ---------------------------------------------------- .. index:: creat @@ -575,65 +598,55 @@ creat - Create a new file or rewrite an existing one **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include #include int creat( - const char \*path, - mode_t mode + const char *path, + mode_t mode ); **STATUS CODES:** -*EEXIST* - ``path`` already exists and O_CREAT and O_EXCL were used. - -*EISDIR* - ``path`` refers to a directory and the access requested involved - writing - -*ETXTBSY* - ``path`` refers to an executable image which is currently being - executed and write access was requested - -*EFAULT* - ``path`` points outside your accessible address space - -*EACCES* - The requested access to the file is not allowed, or one of the - directories in ``path`` did not allow search (execute) permission. - -*ENAMETOOLONG* - ``path`` was too long. - -*ENOENT* - A directory component in ``path`` does not exist or is a dangling - symbolic link. - -*ENOTDIR* - A component used as a directory in ``path`` is not, in fact, a - directory. - -*EMFILE* - The process alreadyh has the maximum number of files open. - -*ENFILE* - The limit on the total number of files open on the system has been - reached. - -*ENOMEM* - Insufficient kernel memory was available. - -*EROFS* - ``path`` refers to a file on a read-only filesystem and write access - was requested +.. list-table:: + :class: rtems-table + + * - ``EEXIST`` + - ``path`` already exists and ``O_CREAT`` and ``O_EXCL`` were used. + * - ``EISDIR`` + - ``path`` refers to a directory and the access requested involved writing + * - ``ETXTBSY`` + - ``path`` refers to an executable image which is currently being executed + and write access was requested + * - ``EFAULT`` + - ``path`` points outside your accessible address space + * - ``EACCES`` + - The requested access to the file is not allowed, or one of the directories + in ``path`` did not allow search (execute) permission. + * - ``ENAMETOOLONG`` + - ``path`` was too long. + * - ``ENOENT`` + - A directory component in ``path`` does not exist or is a dangling symbolic + link. + * - ``ENOTDIR`` + - A component used as a directory in ``path`` is not, in fact, a directory. + * - ``EMFILE`` + - The process alreadyh has the maximum number of files open. + * - ``ENFILE`` + - The limit on the total number of files open on the system has been + reached. + * - ``ENOMEM`` + - Insufficient kernel memory was available. + * - ``EROFS`` + - ``path`` refers to a file on a read-only filesystem and write access was + requested **DESCRIPTION:** -``creat`` attempts to create a file and return a file descriptor for -use in read, write, etc. +``creat`` attempts to create a file and return a file descriptor for use in +read, write, etc. **NOTES:** @@ -641,6 +654,8 @@ NONE The routine is implemented in Cygnus newlib. +.. _umask: + umask - Sets a file creation mask. ---------------------------------- .. index:: umask @@ -648,34 +663,37 @@ umask - Sets a file creation mask. **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include mode_t umask( - mode_t cmask + mode_t cmask ); **STATUS CODES:** **DESCRIPTION:** -The ``umask()`` function sets the process file creation mask to ``cmask``. -The file creation mask is used during ``open()``, ``creat()``, ``mkdir()``,``mkfifo()`` calls to turn off permission bits in the ``mode`` argument. -Bit positions that are set in ``cmask`` are cleared in the mode of the -created file. +The ``umask()`` function sets the process file creation mask to ``cmask``. The +file creation mask is used during ``open()``, ``creat()``, ``mkdir()``, +``mkfifo()`` calls to turn off permission bits in the ``mode`` argument. Bit +positions that are set in ``cmask`` are cleared in the mode of the created +file. **NOTES:** NONE -The ``cmask`` argument should have only permission bits set. All other -bits should be zero. +The ``cmask`` argument should have only permission bits set. All other bits +should be zero. + +In a system which supports multiple processes, the file creation mask is +inherited across ``fork()`` and ``exec()`` calls. This makes it possible to +alter the default permission bits of created files. RTEMS does not support +multiple processes so this behavior is not possible. -In a system which supports multiple processes, the file creation mask is inherited -across ``fork()`` and ``exec()`` calls. This makes it possible to alter the -default permission bits of created files. RTEMS does not support multiple processes -so this behavior is not possible. +.. _link: link - Creates a link to a file ------------------------------- @@ -684,53 +702,47 @@ link - Creates a link to a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int link( - const char \*existing, - const char \*new + const char *existing, + const char *new ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EEXIST* - The named file already exists. - -*EMLINK* - The number of links would exceed ``LINK_MAX``. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*EPERM* - Operation is not permitted. Process does not have the appropriate priviledges - or permissions to perform the requested operations. - -*EROFS* - Read-only file system. - -*EXDEV* - Attempt to link a file to another file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EEXIST`` + - The named file already exists. + * - ``EMLINK`` + - The number of links would exceed ``LINK_MAX``. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EPERM`` + - Operation is not permitted. Process does not have the appropriate + priviledges or permissions to perform the requested operations. + * - ``EROFS`` + - Read-only file system. + * - ``EXDEV`` + - Attempt to link a file to another file system. **DESCRIPTION:** -The ``link()`` function atomically creates a new link for an existing file -and increments the link count for the file. +The ``link()`` function atomically creates a new link for an existing file and +increments the link count for the file. If the ``link()`` function fails, no directories are modified. @@ -742,6 +754,8 @@ The caller may (or may not) need permission to access the existing file. NONE +.. _symlink: + symlink - Creates a symbolic link to a file ------------------------------------------- .. index:: symlink @@ -749,42 +763,38 @@ symlink - Creates a symbolic link to a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int symlink( - const char \*topath, - const char \*frompath + const char *topath, + const char *frompath ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EEXIST* - The named file already exists. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*EPERM* - Operation is not permitted. Process does not have the appropriate priviledges - or permissions to perform the requested operations. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EEXIST`` + - The named file already exists. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EPERM`` + - Operation is not permitted. Process does not have the appropriate + priviledges or permissions to perform the requested operations. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** @@ -799,6 +809,8 @@ The caller may (or may not) need permission to access the existing file. NONE +.. _readlink: + readlink - Obtain the name of a symbolic link destination --------------------------------------------------------- .. index:: readlink @@ -806,51 +818,51 @@ readlink - Obtain the name of a symbolic link destination **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int readlink( - const char \*path, - char \*buf, - size_t bufsize + const char *path, + char *buf, + size_t bufsize ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the prefix pathname was not a directory when a directory - was expected. - -*ELOOP* - Too many symbolic links were encountered in the pathname. - -*EINVAL* - The pathname does not refer to a symbolic link - -*EFAULT* - An invalid pointer was passed into the ``readlink()`` routine. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the prefix pathname was not a directory when a directory + was expected. + * - ``ELOOP`` + - Too many symbolic links were encountered in the pathname. + * - ``EINVAL`` + - The pathname does not refer to a symbolic link + * - ``EFAULT`` + - An invalid pointer was passed into the ``readlink()`` routine. **DESCRIPTION:** -The ``readlink()`` function places the symbolic link destination into``buf`` argument and returns the number of characters copied. +The ``readlink()`` function places the symbolic link destination into ``buf`` +argument and returns the number of characters copied. -If the symbolic link destination is longer than bufsize characters the -name will be truncated. +If the symbolic link destination is longer than bufsize characters the name +will be truncated. **NOTES:** NONE +.. _mkdir: + mkdir - Makes a directory ------------------------- .. index:: mkdir @@ -858,57 +870,54 @@ mkdir - Makes a directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int mkdir( - const char \*path, - mode_t mode + const char *path, + mode_t mode ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EEXIST* - The name file already exist. - -*EMLINK* - The number of links would exceed LINK_MAX - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EEXIST`` + - The name file already exist. + * - ``EMLINK`` + - The number of links would exceed ``LINK_MAX`` + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** -The ``mkdir()`` function creates a new diectory named ``path``. The -permission bits (modified by the file creation mask) are set from ``mode``. -The owner and group IDs for the directory are set from the effective user ID -and group ID. +The ``mkdir()`` function creates a new diectory named ``path``. The permission +bits (modified by the file creation mask) are set from ``mode``. The owner and +group IDs for the directory are set from the effective user ID and group ID. -The new directory may (or may not) contain entries for.. and .. but is otherwise -empty. +The new directory may (or may not) contain entries for ``.`` and ``..`` but is +otherwise empty. **NOTES:** NONE +.. _mkfifo: + mkfifo - Makes a FIFO special file ---------------------------------- .. index:: mkfifo @@ -916,46 +925,47 @@ mkfifo - Makes a FIFO special file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int mkfifo( - const char \*path, - mode_t mode + const char *path, + mode_t mode ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EEXIST* - The named file already exists. - -*ENOENT* - A file or directory does not exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified ``path`` was not a directory when a directory - was expected. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EEXIST`` + - The named file already exists. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified ``path`` was not a directory when a directory + was expected. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** -The ``mkfifo()`` function creates a new FIFO special file named ``path``. -The permission bits (modified by the file creation mask) are set from``mode``. The owner and group IDs for the FIFO are set from the efective -user ID and group ID. +The ``mkfifo()`` function creates a new FIFO special file named ``path``. The +permission bits (modified by the file creation mask) are set from ``mode``. The +owner and group IDs for the FIFO are set from the efective user ID and +group ID. **NOTES:** NONE +.. _unlink: + unlink - Removes a directory entry ---------------------------------- .. index:: unlink @@ -963,50 +973,49 @@ unlink - Removes a directory entry **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int unlink( - const char path + const char path ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EBUSY* - The directory is in use. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified ``path`` was not a directory when a directory - was expected. - -*EPERM* - Operation is not permitted. Process does not have the appropriate priviledges - or permissions to perform the requested operations. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EBUSY`` + - The directory is in use. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified ``path`` was not a directory when a directory + was expected. + * - ``EPERM`` + - Operation is not permitted. Process does not have the appropriate + priviledges or permissions to perform the requested operations. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** The ``unlink`` function removes the link named by ``path`` and decrements the link count of the file referenced by the link. When the link count goes to zero -and no process has the file open, the space occupied by the file is freed and the -file is no longer accessible. +and no process has the file open, the space occupied by the file is freed and +the file is no longer accessible. **NOTES:** NONE +.. _rmdir: + rmdir - Delete a directory -------------------------- .. index:: rmdir @@ -1014,61 +1023,52 @@ rmdir - Delete a directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int rmdir( - const char \*pathname + const char *pathname ); **STATUS CODES:** -*EPERM* - The filesystem containing ``pathname`` does not support the removal - of directories. - -*EFAULT* - ``pathname`` points ouside your accessible address space. - -*EACCES* - Write access to the directory containing ``pathname`` was not - allowed for the process's effective uid, or one of the directories in``pathname`` did not allow search (execute) permission. - -*EPERM* - The directory containing ``pathname`` has the stickybit (S_ISVTX) - set and the process's effective uid is neither the uid of the file to - be delected nor that of the director containing it. - -*ENAMETOOLONG* - ``pathname`` was too long. - -*ENOENT* - A dirctory component in ``pathname`` does not exist or is a - dangling symbolic link. - -*ENOTDIR* - ``pathname``, or a component used as a directory in ``pathname``, - is not, in fact, a directory. - -*ENOTEMPTY* - ``pathname`` contains entries other than . and .. . - -*EBUSY* - ``pathname`` is the current working directory or root directory of - some process - -*EBUSY* - ``pathname`` is the current directory or root directory of some - process. - -*ENOMEM* - Insufficient kernel memory was available - -*EROGS* - ``pathname`` refers to a file on a read-only filesystem. - -*ELOOP* - ``pathname`` contains a reference to a circular symbolic link +.. list-table:: + :class: rtems-table + + * - ``EPERM`` + - The filesystem containing ``pathname`` does not support the removal of + directories. + * - ``EFAULT`` + - ``pathname`` points ouside your accessible address space. + * - ``EACCES`` + - Write access to the directory containing ``pathname`` was not allowed for + the process's effective uid, or one of the directories in``pathname`` did + not allow search (execute) permission. + * - ``EPERM`` + - The directory containing ``pathname`` has the stickybit (S_ISVTX) set and + the process's effective uid is neither the uid of the file to be delected + nor that of the director containing it. + * - ``ENAMETOOLONG`` + - ``pathname`` was too long. + * - ``ENOENT`` + - A dirctory component in ``pathname`` does not exist or is a dangling + symbolic link. + * - ``ENOTDIR`` + - ``pathname``, or a component used as a directory in ``pathname``, is not, + in fact, a directory. + * - ``ENOTEMPTY`` + - ``pathname`` contains entries other than . and .. . + * - ``EBUSY`` + - ``pathname`` is the current working directory or root directory of some + process + * - ``EBUSY`` + - ``pathname`` is the current directory or root directory of some process. + * - ``ENOMEM`` + - Insufficient kernel memory was available + * - ``EROGS`` + - ``pathname`` refers to a file on a read-only filesystem. + * - ``ELOOP`` + - ``pathname`` contains a reference to a circular symbolic link **DESCRIPTION:** @@ -1078,6 +1078,8 @@ rmdir - Delete a directory NONE +.. _rename: + rename - Renames a file ----------------------- .. index:: rename @@ -1085,75 +1087,69 @@ rename - Renames a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int rename( - const char \*old, - const char \*new + const char *old, + const char *new ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix. - -*EBUSY* - The directory is in use. - -*EEXIST* - The named file already exists. - -*EINVAL* - Invalid argument. - -*EISDIR* - Attempt to open a directory for writing or to rename a file to be a - directory. - -*EMLINK* - The number of links would exceed LINK_MAX. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is - in effect. - -*ENOENT* - A file or directory does no exist. - -*ENOSPC* - No space left on disk. - -*ENOTDIR* - A component of the specified pathname was not a directory when a - directory was expected. - -*ENOTEMPTY* - Attempt to delete or rename a non-empty directory. - -*EROFS* - Read-only file system - -*EXDEV* - Attempt to link a file to another file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``EBUSY`` + - The directory is in use. + * - ``EEXIST`` + - The named file already exists. + * - ``EINVAL`` + - Invalid argument. + * - ``EISDIR`` + - Attempt to open a directory for writing or to rename a file to be a + directory. + * - ``EMLINK`` + - The number of links would exceed ``LINK_MAX``. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does no exist. + * - ``ENOSPC`` + - No space left on disk. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``ENOTEMPTY`` + - Attempt to delete or rename a non-empty directory. + * - ``EROFS`` + - Read-only file system + * - ``EXDEV`` + - Attempt to link a file to another file system. **DESCRIPTION:** -The ``rename()`` function causes the file known bo ``old`` to -now be known as ``new``. +The ``rename()`` function causes the file known bo ``old`` to now be known as +``new``. -Ordinary files may be renamed to ordinary files, and directories may be -renamed to directories; however, files cannot be converted using``rename()``. The ``new`` pathname may not contain a path prefix -of ``old``. +Ordinary files may be renamed to ordinary files, and directories may be renamed +to directories; however, files cannot be converted using ``rename()``. The +``new`` pathname may not contain a path prefix of ``old``. **NOTES:** -If a file already exists by the name ``new``, it is removed. The``rename()`` function is atomic. If the ``rename()`` detects an -error, no files are removed. This guarantees that the``rename("x", "x")`` does not remove ``x``. +If a file already exists by the name ``new``, it is removed. The ``rename()`` +function is atomic. If the ``rename()`` detects an error, no files are +removed. This guarantees that the ``rename("x", "x")`` does not remove ``x``. You may not rename dot or dot-dot. -The routine is implemented in Cygnus newlib using ``link()`` and``unlink()``. +The routine is implemented in Cygnus newlib using ``link()`` and ``unlink()``. + +.. _stat: stat - Gets information about a file ------------------------------------ @@ -1162,45 +1158,46 @@ stat - Gets information about a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int stat( - const char \*path, - struct stat \*buf + const char *path, + struct stat *buf ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix. - -*EBADF* - Invalid file descriptor. - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is - in effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified pathname was not a directory when a - directory was expected. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``EBADF`` + - Invalid file descriptor. + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. **DESCRIPTION:** -The ``path`` argument points to a pathname for a file. Read, write, or -execute permission for the file is not required, but all directories listed -in ``path`` must be searchable. The ``stat()`` function obtains -information about the named file and writes it to the area pointed to by``buf``. +The ``path`` argument points to a pathname for a file. Read, write, or execute +permission for the file is not required, but all directories listed in ``path`` +must be searchable. The ``stat()`` function obtains information about the named +file and writes it to the area pointed to by ``buf``. **NOTES:** NONE +.. _fstat: + fstat - Gets file status ------------------------ .. index:: fstat @@ -1208,31 +1205,35 @@ fstat - Gets file status **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int fstat( - int fildes, - struct stat \*buf + int fildes, + struct stat *buf ); **STATUS CODES:** -*EBADF* - Invalid file descriptor +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid file descriptor **DESCRIPTION:** -The ``fstat()`` function obtains information about the file -associated with ``fildes`` and writes it to the area pointed -to by the ``buf`` argument. +The ``fstat()`` function obtains information about the file associated with +``fildes`` and writes it to the area pointed to by the ``buf`` argument. **NOTES:** -If the filesystem object referred to by ``fildes`` is a -link, then the information returned in ``buf`` refers -to the destination of that link. This is in contrast to``lstat()`` which does not follow the link. +If the filesystem object referred to by ``fildes`` is a link, then the +information returned in ``buf`` refers to the destination of that link. This +is in contrast to ``lstat()`` which does not follow the link. + +.. _lstat: lstat - Gets file status ------------------------ @@ -1241,35 +1242,38 @@ lstat - Gets file status **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int lstat( - int fildes, - struct stat \*buf + int fildes, + struct stat *buf ); **STATUS CODES:** -*EBADF* - Invalid file descriptor +.. list-table:: + :class: rtems-table + + * - ``EBADF`` + - Invalid file descriptor **DESCRIPTION:** -The ``lstat()`` function obtains information about the file -associated with ``fildes`` and writes it to the area pointed -to by the ``buf`` argument. +The ``lstat()`` function obtains information about the file associated with +``fildes`` and writes it to the area pointed to by the ``buf`` argument. **NOTES:** -If the filesystem object referred to by ``fildes`` is a -link, then the information returned in ``buf`` refers -to the link itself. This is in contrast to ``fstat()`` -which follows the link. +If the filesystem object referred to by ``fildes`` is a link, then the +information returned in ``buf`` refers to the link itself. This is in contrast +to ``fstat()`` which follows the link. -The ``lstat()`` routine is defined by BSD 4.3 and SVR4 -and not included in POSIX 1003.1b-1996. +The ``lstat()`` routine is defined by BSD 4.3 and SVR4 and not included in +POSIX 1003.1b-1996. + +.. _access: access - Check permissions for a file ------------------------------------- @@ -1278,52 +1282,53 @@ access - Check permissions for a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int access( - const char \*pathname, - int mode + const char *pathname, + int mode ); **STATUS CODES:** -*EACCES* - The requested access would be denied, either to the file itself or - one of the directories in ``pathname``. - -*EFAULT* - ``pathname`` points outside your accessible address space. - -*EINVAL* - ``Mode`` was incorrectly specified. - -*ENAMETOOLONG* - ``pathname`` is too long. - -*ENOENT* - A directory component in ``pathname`` would have been accessible but - does not exist or was a dangling symbolic link. - -*ENOTDIR* - A component used as a directory in ``pathname`` is not, in fact, - a directory. - -*ENOMEM* - Insufficient kernel memory was available. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - The requested access would be denied, either to the file itself or one of + the directories in ``pathname``. + * - ``EFAULT`` + - ``pathname`` points outside your accessible address space. + * - ``EINVAL`` + - ``Mode`` was incorrectly specified. + * - ``ENAMETOOLONG`` + - ``pathname`` is too long. + * - ``ENOENT`` + - A directory component in ``pathname`` would have been accessible but does + not exist or was a dangling symbolic link. + * - ``ENOTDIR`` + - A component used as a directory in ``pathname`` is not, in fact, a + directory. + * - ``ENOMEM`` + - Insufficient kernel memory was available. **DESCRIPTION:** -``Access`` checks whether the process would be allowed to read, write or -test for existence of the file (or other file system object) whose name is``pathname``. If ``pathname`` is a symbolic link permissions of the -file referred by this symbolic link are tested. +``Access`` checks whether the process would be allowed to read, write or test +for existence of the file (or other file system object) whose name is +``pathname``. If ``pathname`` is a symbolic link permissions of the file +referred by this symbolic link are tested. -``Mode`` is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. +``Mode`` is a mask consisting of one or more of ``R_OK``, ``W_OK``, ``X_OK`` +and ``F_OK``. **NOTES:** NONE +.. _chmod: + chmod - Changes file mode. -------------------------- .. index:: chmod @@ -1331,49 +1336,49 @@ chmod - Changes file mode. **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int chmod( - const char \*path, - mode_t mode + const char *path, + mode_t mode ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*EPERM* - Operation is not permitted. Process does not have the appropriate priviledges - or permissions to perform the requested operations. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EPERM`` + - Operation is not permitted. Process does not have the appropriate + priviledges or permissions to perform the requested operations. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** -Set the file permission bits, the set user ID bit, and the set group ID bit -for the file named by ``path`` to ``mode``. If the effective user ID -does not match the owner of the file and the calling process does not have -the appropriate privileges, ``chmod()`` returns -1 and sets ``errno`` to``EPERM``. +Set the file permission bits, the set user ID bit, and the set group ID bit for +the file named by ``path`` to ``mode``. If the effective user ID does not match +the owner of the file and the calling process does not have the appropriate +privileges, ``chmod()`` returns -1 and sets ``errno`` to ``EPERM``. **NOTES:** NONE +.. _fchmod: + fchmod - Changes permissions of a file -------------------------------------- .. index:: fchmod @@ -1381,61 +1386,55 @@ fchmod - Changes permissions of a file **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int fchmod( - int fildes, - mode_t mode + int fildes, + mode_t mode ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix. - -*EBADF* - The descriptor is not valid. - -*EFAULT* - ``path`` points outside your accessible address space. - -*EIO* - A low-level I/o error occurred while modifying the inode. - -*ELOOP* - ``path`` contains a circular reference - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is - in effect. - -*ENOENT* - A file or directory does no exist. - -*ENOMEM* - Insufficient kernel memory was avaliable. - -*ENOTDIR* - A component of the specified pathname was not a directory when a - directory was expected. - -*EPERM* - The effective UID does not match the owner of the file, and is not - zero - -*EROFS* - Read-only file system +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix. + * - ``EBADF`` + - The descriptor is not valid. + * - ``EFAULT`` + - ``path`` points outside your accessible address space. + * - ``EIO`` + - A low-level I/o error occurred while modifying the inode. + * - ``ELOOP`` + - ``path`` contains a circular reference + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does no exist. + * - ``ENOMEM`` + - Insufficient kernel memory was avaliable. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EPERM`` + - The effective UID does not match the owner of the file, and is not zero + * - ``EROFS`` + - Read-only file system **DESCRIPTION:** -The mode of the file given by ``path`` or referenced by``filedes`` is changed. +The mode of the file given by ``path`` or referenced by ``filedes`` is changed. **NOTES:** NONE +.. _getdents: + getdents - Get directory entries -------------------------------- .. index:: getdents @@ -1443,48 +1442,49 @@ getdents - Get directory entries **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include #include long getdents( - int dd_fd, - char \*dd_buf, - int dd_len + int dd_fd, + char *dd_buf, + int dd_len ); **STATUS CODES:** -A successful call to ``getdents`` returns th the number of bytes read. -On end of directory, 0 is returned. When an error occurs, -1 is returned, -and ``errno`` is set appropriately. - -*EBADF* - Invalid file descriptor ``fd``. - -*EFAULT* - Argument points outside the calling process's address space. - -*EINVAL* - Result buffer is too small. +A successful call to ``getdents`` returns th the number of bytes read. On end +of directory, 0 is returned. When an error occurs, -1 is returned, and +``errno`` is set appropriately. -*ENOENT* - No such directory. +.. list-table:: + :class: rtems-table -*ENOTDIR* - File descriptor does not refer to a directory. + * - ``EBADF`` + - Invalid file descriptor ``fd``. + * - ``EFAULT`` + - Argument points outside the calling process's address space. + * - ``EINVAL`` + - Result buffer is too small. + * - ``ENOENT`` + - No such directory. + * - ``ENOTDIR`` + - File descriptor does not refer to a directory. **DESCRIPTION:** -``getdents`` reads several ``dirent`` structures from the directory -pointed by ``fd`` into the memory area pointed to by ``dirp``. The -parameter ``count`` is the size of the memory area. +``getdents`` reads several ``dirent`` structures from the directory pointed by +``fd`` into the memory area pointed to by ``dirp``. The parameter ``count`` is +the size of the memory area. **NOTES:** NONE +.. _chown: + chown - Changes the owner and/or group of a file. ------------------------------------------------- .. index:: chown @@ -1492,59 +1492,59 @@ chown - Changes the owner and/or group of a file. **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include int chown( - const char \*path, - uid_t owner, - gid_t group + const char *path, + uid_t owner, + gid_t group ); **STATUS CODES:** -*EACCES* - Search permission is denied for a directory in a file's path prefix - -*EINVAL* - Invalid argument - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in - effect. - -*ENOENT* - A file or directory does not exist. - -*ENOTDIR* - A component of the specified pathname was not a directory when a directory - was expected. - -*EPERM* - Operation is not permitted. Process does not have the appropriate priviledges - or permissions to perform the requested operations. - -*EROFS* - Read-only file system. +.. list-table:: + :class: rtems-table + + * - ``EACCES`` + - Search permission is denied for a directory in a file's path prefix + * - ``EINVAL`` + - Invalid argument + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist. + * - ``ENOTDIR`` + - A component of the specified pathname was not a directory when a directory + was expected. + * - ``EPERM`` + - Operation is not permitted. Process does not have the appropriate + priviledges or permissions to perform the requested operations. + * - ``EROFS`` + - Read-only file system. **DESCRIPTION:** -The user ID and group ID of the file named by ``path`` are set to``owner`` and ``path``, respectively. +The user ID and group ID of the file named by ``path`` are set to ``owner`` and +``path``, respectively. -For regular files, the set group ID (S_ISGID) and set user ID (S_ISUID) +For regular files, the set group ID (``S_ISGID``) and set user ID (``S_ISUID``) bits are cleared. Some systems consider it a security violation to allow the owner of a file to -be changed, If users are billed for disk space usage, loaning a file to -another user could result in incorrect billing. The ``chown()`` function -may be restricted to privileged users for some or all files. The group ID can -still be changed to one of the supplementary group IDs. +be changed, If users are billed for disk space usage, loaning a file to another +user could result in incorrect billing. The ``chown()`` function may be +restricted to privileged users for some or all files. The group ID can still be +changed to one of the supplementary group IDs. **NOTES:** -This function may be restricted for some file. The ``pathconf`` function -can be used to test the ``_PC_CHOWN_RESTRICTED`` flag. +This function may be restricted for some file. The ``pathconf`` function can be +used to test the ``_PC_CHOWN_RESTRICTED`` flag. + +.. _utime: utime - Change access and/or modification times of an inode ----------------------------------------------------------- @@ -1553,33 +1553,37 @@ utime - Change access and/or modification times of an inode **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int utime( - const char \*filename, - struct utimbuf \*buf + const char *filename, + struct utimbuf *buf ); **STATUS CODES:** -*EACCES* - Permission to write the file is denied +.. list-table:: + :class: rtems-table -*ENOENT* - ``Filename`` does not exist + * - ``EACCES`` + - Permission to write the file is denied + * - ``ENOENT`` + - ``Filename`` does not exist **DESCRIPTION:** -``Utime`` changes the access and modification times of the inode -specified by ``filename`` to the ``actime`` and ``modtime`` -fields of ``buf`` respectively. If ``buf`` is NULL, then the -access and modification times of the file are set to the current time. +``Utime`` changes the access and modification times of the inode specified by +``filename`` to the ``actime`` and ``modtime`` fields of ``buf`` +respectively. If ``buf`` is ``NULL``, then the access and modification times of the +file are set to the current time. **NOTES:** NONE +.. _ftruncate: + ftruncate - truncate a file to a specified length ------------------------------------------------- .. index:: ftruncate @@ -1587,67 +1591,60 @@ ftruncate - truncate a file to a specified length **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int ftrunctate( - int fd, - size_t length + int fd, + size_t length ); **STATUS CODES:** -*ENOTDIR* - A component of the path prefix is not a directory. - -*EINVAL* - The pathname contains a character with the high-order bit set. - -*ENAMETOOLONG* - A component of a pathname exceeded 255 characters, or an entire - path name exceeded 1023 characters. - -*ENOENT* - The named file does not exist. - -*EACCES* - The named file is not writable by the user. - -*EACCES* - Search permission is denied for a component of the path prefix. - -*ELOOP* - Too many symbolic links were encountered in translating the - pathname - -*EISDIR* - The named file is a directory. - -*EROFS* - The named file resides on a read-only file system - -*ETXTBSY* - The file is a pure procedure (shared text) file that is being - executed - -*EIO* - An I/O error occurred updating the inode. - -*EFAULT* - ``Path`` points outside the process's allocated address space. - -*EBADF* - The ``fd`` is not a valid descriptor. +.. list-table:: + :class: rtems-table + + * - ``ENOTDIR`` + - A component of the path prefix is not a directory. + * - ``EINVAL`` + - The pathname contains a character with the high-order bit set. + * - ``ENAMETOOLONG`` + - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length + of a component of the pathname exceeds ``NAME_MAX`` bytes. + * - ``ENOENT`` + - The named file does not exist. + * - ``EACCES`` + - The named file is not writable by the user. + * - ``EACCES`` + - Search permission is denied for a component of the path prefix. + * - ``ELOOP`` + - Too many symbolic links were encountered in translating the pathname + * - ``EISDIR`` + - The named file is a directory. + * - ``EROFS`` + - The named file resides on a read-only file system + * - ``ETXTBSY`` + - The file is a pure procedure (shared text) file that is being executed + * - ``EIO`` + - An I/O error occurred updating the inode. + * - ``EFAULT`` + - ``Path`` points outside the process's allocated address space. + * - ``EBADF`` + - The ``fd`` is not a valid descriptor. **DESCRIPTION:** -``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the -file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing. +``truncate()`` causes the file named by ``path`` or referenced by ``fd`` to be +truncated to at most ``length`` bytes in size. If the file previously was +larger than this size, the extra data is lost. With ``ftruncate()``, the file +must be open for writing. **NOTES:** NONE +.. _truncate: + truncate - truncate a file to a specified length ------------------------------------------------ .. index:: truncate @@ -1655,67 +1652,60 @@ truncate - truncate a file to a specified length **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int trunctate( - const char \*path, - size_t length + const char *path, + size_t length ); **STATUS CODES:** -*ENOTDIR* - A component of the path prefix is not a directory. - -*EINVAL* - The pathname contains a character with the high-order bit set. - -*ENAMETOOLONG* - A component of a pathname exceeded 255 characters, or an entire - path name exceeded 1023 characters. - -*ENOENT* - The named file does not exist. - -*EACCES* - The named file is not writable by the user. - -*EACCES* - Search permission is denied for a component of the path prefix. - -*ELOOP* - Too many symbolic links were encountered in translating the - pathname - -*EISDIR* - The named file is a directory. - -*EROFS* - The named file resides on a read-only file system - -*ETXTBSY* - The file is a pure procedure (shared text) file that is being - executed - -*EIO* - An I/O error occurred updating the inode. - -*EFAULT* - ``Path`` points outside the process's allocated address space. - -*EBADF* - The ``fd`` is not a valid descriptor. +.. list-table:: + :class: rtems-table + + * - ``ENOTDIR`` + - A component of the path prefix is not a directory. + * - ``EINVAL`` + - The pathname contains a character with the high-order bit set. + * - ``ENAMETOOLONG`` + - The length of the specified pathname exceeds ``PATH_MAX`` bytes, or the length + of a component of the pathname exceeds ``NAME_MAX`` bytes. + * - ``ENOENT`` + - The named file does not exist. + * - ``EACCES`` + - The named file is not writable by the user. + * - ``EACCES`` + - Search permission is denied for a component of the path prefix. + * - ``ELOOP`` + - Too many symbolic links were encountered in translating the pathname + * - ``EISDIR`` + - The named file is a directory. + * - ``EROFS`` + - The named file resides on a read-only file system + * - ``ETXTBSY`` + - The file is a pure procedure (shared text) file that is being executed + * - ``EIO`` + - An I/O error occurred updating the inode. + * - ``EFAULT`` + - ``Path`` points outside the process's allocated address space. + * - ``EBADF`` + - The ``fd`` is not a valid descriptor. **DESCRIPTION:** -``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be truncated to at most ``length`` bytes in size. If the -file previously was larger than this size, the extra data is lost. With``ftruncate()``, the file must be open for writing. +``truncate()`` causes the file named by ``path`` or referenced by``fd`` to be +truncated to at most ``length`` bytes in size. If the file previously was +larger than this size, the extra data is lost. With ``ftruncate()``, the file +must be open for writing. **NOTES:** NONE +.. _pathconf: + pathconf - Gets configuration values for files ---------------------------------------------- .. index:: pathconf @@ -1723,71 +1713,77 @@ pathconf - Gets configuration values for files **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int pathconf( - const char \*path, - int name + const char *path, + int name ); **STATUS CODES:** -*EINVAL* - Invalid argument - -*EACCES* - Permission to write the file is denied - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC - is in effect. - -*ENOENT* - A file or directory does not exist - -*ENOTDIR* - A component of the specified ``path`` was not a directory whan a - directory was expected. +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument + * - ``EACCES`` + - Permission to write the file is denied + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist + * - ``ENOTDIR`` + - A component of the specified ``path`` was not a directory whan a directory + was expected. **DESCRIPTION:** -``pathconf()`` gets a value for the configuration option ``name`` -for the open file descriptor ``filedes``. +``pathconf()`` gets a value for the configuration option ``name`` for the open +file descriptor ``filedes``. The possible values for ``name`` are: -*_PC_LINK_MAX* - returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole - directory. The corresponding macro is ``_POSIX_LINK_MAX``. - -*_PC_MAX_CANON* - returns the maximum length of a formatted input line, where ``filedes`` - or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``. - -*_PC_MAX_INPUT* - returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``. - -*_PC_NAME_MAX* - returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro - is ``_POSIX_NAME_MAX``. - -*_PC_PATH_MAX* - returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro - is ``_POSIX_PATH_MAX``. - -*_PC_PIPE_BUF* - returns the size of the pipe buffer, where ``filedes`` must refer to a - pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro - is ``_POSIX_PIPE_BUF``. - -*_PC_CHOWN_RESTRICTED* - returns nonzero if the chown(2) call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all - files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``. +.. list-table:: + :class: rtems-table + + * - ``_PC_LINK_MAX`` + - Returns the maximum number of links to the file. If ``filedes`` or``path`` + refer to a directory, then the value applies to the whole directory. The + corresponding macro is ``_POSIX_LINK_MAX``. + * - ``_PC_MAX_CANON`` + - Returns the maximum length of a formatted input line, where ``filedes`` or + ``path`` must refer to a terminal. The corresponding macro is + ``_POSIX_MAX_CANON``. + * - ``_PC_MAX_INPUT`` + - Returns the maximum length of an input line, where ``filedes`` or ``path`` + must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``. + * - ``_PC_NAME_MAX`` + - Returns the maximum length of a filename in the directory ``path`` or + ``filedes``. The process is allowed to create. The corresponding macro is + ``_POSIX_NAME_MAX``. + * - ``_PC_PATH_MAX`` + - returns the maximum length of a relative pathname when ``path`` + or``filedes`` is the current working directory. The corresponding macro is + ``_POSIX_PATH_MAX``. + * - ``_PC_PIPE_BUF`` + - returns the size of the pipe buffer, where ``filedes`` must refer to a + pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is + ``_POSIX_PIPE_BUF``. + * - ``_PC_CHOWN_RESTRICTED`` + - Returns nonzero if the ``chown(2)`` call may not be used on this + file. If``filedes`` or ``path`` refer to a directory, then this applies to + all files in that directory. The corresponding macro is + ``_POSIX_CHOWN_RESTRICTED``. **NOTES:** -Files with name lengths longer than the value returned for ``name`` equal``_PC_NAME_MAX`` may exist in the given directory. +Files with name lengths longer than the value returned for ``name`` equal +``_PC_NAME_MAX`` may exist in the given directory. + +.. _fpathconf: fpathconf - Gets configuration values for files ----------------------------------------------- @@ -1796,72 +1792,77 @@ fpathconf - Gets configuration values for files **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include int fpathconf( - int filedes, - int name + int filedes, + int name ); **STATUS CODES:** -*EINVAL* - Invalid argument - -*EACCES* - Permission to write the file is denied - -*ENAMETOOLONG* - Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC - is in effect. - -*ENOENT* - A file or directory does not exist - -*ENOTDIR* - A component of the specified ``path`` was not a directory whan a - directory was expected. +.. list-table:: + :class: rtems-table + + * - ``EINVAL`` + - Invalid argument + * - ``EACCES`` + - Permission to write the file is denied + * - ``ENAMETOOLONG`` + - Length of a filename string exceeds ``PATH_MAX`` and ``_POSIX_NO_TRUNC`` + is in effect. + * - ``ENOENT`` + - A file or directory does not exist + * - ``ENOTDIR`` + - A component of the specified ``path`` was not a directory whan a directory + was expected. **DESCRIPTION:** -``pathconf()`` gets a value for the configuration option ``name`` -for the open file descriptor ``filedes``. +``pathconf()`` gets a value for the configuration option ``name`` for the open +file descriptor ``filedes``. The possible values for name are: -*_PC_LINK_MAX* - returns the maximum number of links to the file. If ``filedes`` or``path`` refer to a directory, then the value applies to the whole - directory. The corresponding macro is _POSIX_LINK_MAX. - -*_PC_MAX_CANON* - returns the maximum length of a formatted input line, where ``filedes`` - or ``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_CANON``. - -*_PC_MAX_INPUT* - returns the maximum length of an input line, where ``filedes`` or``path`` must refer to a terminal. The corresponding macro is``_POSIX_MAX_INPUT``. - -*_PC_NAME_MAX* - returns the maximum length of a filename in the directory ``path`` or``filedes``. The process is allowed to create. The corresponding macro - is ``_POSIX_NAME_MAX``. - -*_PC_PATH_MAX* - returns the maximum length of a relative pathname when ``path`` or``filedes`` is the current working directory. The corresponding macro - is ``_POSIX_PATH_MAX``. - -*_PC_PIPE_BUF* - returns the size of the pipe buffer, where ``filedes`` must refer to a - pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro - is ``_POSIX_PIPE_BUF``. - -*_PC_CHOWN_RESTRICTED* - returns nonzero if the ``chown()`` call may not be used on this file. If``filedes`` or ``path`` refer to a directory, then this applies to all - files in that directory. The corresponding macro is``_POSIX_CHOWN_RESTRICTED``. +.. list-table:: + :class: rtems-table + + * - ``_PC_LINK_MAX`` + - Returns the maximum number of links to the file. If ``filedes`` or + ``path`` refer to a directory, then the value applies to the whole + directory. The corresponding macro is ``_POSIX_LINK_MAX``. + * - ``_PC_MAX_CANON`` + - returns the maximum length of a formatted input line, where ``filedes`` or + ``path`` must refer to a terminal. The corresponding macro is + ``_POSIX_MAX_CANON``. + * - ``_PC_MAX_INPUT`` + - Returns the maximum length of an input line, where ``filedes`` or ``path`` + must refer to a terminal. The corresponding macro is ``_POSIX_MAX_INPUT``. + * - ``_PC_NAME_MAX`` + - Returns the maximum length of a filename in the directory ``path`` or + ``filedes``. The process is allowed to create. The corresponding macro is + ``_POSIX_NAME_MAX``. + * - ``_PC_PATH_MAX`` + - Returns the maximum length of a relative pathname when ``path`` or + ``filedes`` is the current working directory. The corresponding macro is + ``_POSIX_PATH_MAX``. + * - ``_PC_PIPE_BUF`` + - Returns the size of the pipe buffer, where ``filedes`` must refer to a + pipe or FIFO and ``path`` must refer to a FIFO. The corresponding macro is + ``_POSIX_PIPE_BUF``. + * - ``_PC_CHOWN_RESTRICTED`` + - Returns nonzero if the ``chown()`` call may not be used on this file. If + ``filedes`` or ``path`` refer to a directory, then this applies to all + files in that directory. The corresponding macro is + ``_POSIX_CHOWN_RESTRICTED``. **NOTES:** NONE +.. _mknod: + mknod - create a directory -------------------------- .. index:: mknod @@ -1869,16 +1870,16 @@ mknod - create a directory **CALLING SEQUENCE:** -.. code:: c +.. code-block:: c #include #include #include #include long mknod( - const char \*pathname, - mode_t mode, - dev_t dev + const char *pathname, + mode_t mode, + dev_t dev ); **STATUS CODES:** @@ -1886,28 +1887,26 @@ mknod - create a directory ``mknod`` returns zero on success, or -1 if an error occurred (in which case, errno is set appropriately). -*ENAMETOOLONG* - ``pathname`` was too long. - -*ENOENT* - A directory component in ``pathname`` does not exist or is a dangling symbolic - link. - -*ENOTDIR* - A component used in the directory ``pathname`` is not, in fact, a directory. - -*ENOMEM* - Insufficient kernel memory was available - -*EROFS* - ``pathname`` refers to a file on a read-only filesystem. - -*ELOOP* - ``pathname`` contains a reference to a circular symbolic link, ie a symbolic - link whose expansion contains a reference to itself. - -*ENOSPC* - The device containing ``pathname`` has no room for the new node. +.. list-table:: + :class: rtems-table + + * - ``ENAMETOOLONG`` + - ``pathname`` was too long. + * - ``ENOENT`` + - A directory component in ``pathname`` does not exist or is a dangling + symbolic link. + * - ``ENOTDIR`` + - A component used in the directory ``pathname`` is not, in fact, a + directory. + * - ``ENOMEM`` + - Insufficient kernel memory was available + * - ``EROFS`` + - ``pathname`` refers to a file on a read-only filesystem. + * - ``ELOOP`` + - ``pathname`` contains a reference to a circular symbolic link, ie a + symbolic link whose expansion contains a reference to itself. + * - ``ENOSPC`` + - The device containing ``pathname`` has no room for the new node. **DESCRIPTION:** @@ -1922,26 +1921,21 @@ below and the permissions for the new node. The permissions are modified by the process's ``umask`` in the usual way: the permissions of the created node are ``(mode & ~umask)``. -The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and``S_IFIFO`` to specify a normal file (which will be created empty), character -special file, block special file or FIFO (named pipe), respectively, or zero, which -will create a normal file. +The file type should be one of ``S_IFREG``, ``S_IFCHR``, ``S_IFBLK`` and +``S_IFIFO`` to specify a normal file (which will be created empty), character +special file, block special file or FIFO (named pipe), respectively, or zero, +which will create a normal file. If the file type is ``S_IFCHR`` or ``S_IFBLK`` then ``dev`` specifies the major -and minor numbers of the newly created device special file; otherwise it is ignored. +and minor numbers of the newly created device special file; otherwise it is +ignored. -The newly created node will be owned by the effective uid of the process. If the -directory containing the node has the set group id bit set, or if the filesystem -is mounted with BSD group semantics, the new node will inherit the group ownership -from its parent directory; otherwise it will be owned by the effective gid of the -process. +The newly created node will be owned by the effective uid of the process. If +the directory containing the node has the set group id bit set, or if the +filesystem is mounted with BSD group semantics, the new node will inherit the +group ownership from its parent directory; otherwise it will be owned by the +effective gid of the process. **NOTES:** NONE - -.. COMMENT: COPYRIGHT (c) 1988-2002. - -.. COMMENT: On-Line Applications Research Corporation (OAR). - -.. COMMENT: All rights reserved. - -- cgit v1.2.3