From e9264513e4b557f78551dd33c2bd2ff770ee4cb5 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Thu, 19 Nov 1998 16:33:49 +0000 Subject: Merged these into POSIX manual. --- doc/new_chapters/files.t | 2088 ---------------------------------------------- 1 file changed, 2088 deletions(-) delete mode 100644 doc/new_chapters/files.t (limited to 'doc/new_chapters/files.t') diff --git a/doc/new_chapters/files.t b/doc/new_chapters/files.t deleted file mode 100644 index 1a116cc3fa..0000000000 --- a/doc/new_chapters/files.t +++ /dev/null @@ -1,2088 +0,0 @@ -@c -@c COPYRIGHT (c) 1988-1998. -@c On-Line Applications Research Corporation (OAR). -@c All rights reserved. -@c -@c $Id$ -@c - -@chapter Files and Directories Manager - -@section Introduction - -The files and directories manager is ... - -The directives provided by the files and directories manager are: - -@itemize @bullet -@item @code{opendir} - Open a Directory -@item @code{readdir} - Reads a directory -@item @code{rewinddir} - Resets the @code{readdir()} pointer -@item @code{scandir} - Scan a directory for matching entries -@item @code{telldir} - Return current location in directory stream -@item @code{closedir} - Ends directory read operation -@item @code{getdents} - Get directory entries -@item @code{chdir} - Changes the current working directory -@item @code{getcwd} - Gets current working directory -@item @code{open} - Opens a file -@item @code{creat} - Create a new file or rewrite an existing one -@item @code{umask} - Sets a file creation mask -@item @code{link} - Creates a link to a file -@item @code{symlink} - Creates a symbolic link to a file -@item @code{readlink} - Obtain the name of the link destination -@item @code{mkdir} - Makes a directory -@item @code{mkfifo} - Makes a FIFO special file -@item @code{unlink} - Removes a directory entry -@item @code{rmdir} - Delete a directory -@item @code{rename} - Renames a file -@item @code{stat} - Gets information about a file. -@item @code{fstat} - Gets file status -@item @code{access} - Check user's permissions for a file. -@item @code{chmod} - Changes file mode -@item @code{fchmod} - Changes permissions of a file -@item @code{chown} - Changes the owner and/ or group of a file -@item @code{utime} - Change access and/or modification times of an inode -@item @code{ftruncate} - Truncate a file to a specified length -@item @code{truncate} - Truncate a file to a specified length -@item @code{pathconf} - Gets configuration values for files -@item @code{fpathconf} - Get configuration values for files -@item @code{mknod} - Create a directory -@end itemize - -@section Background - -There is currently no text in this section. - -@section Operations - -There is currently no text in this section. - -@section Directives - -This section details the 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. - -@page -@subsection opendir - Open a Directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int opendir( - const char *dirname -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission was denied on a component of the path -prefix of @code{dirname}, or read permission is denied - -@item EMFILE -Too many file descriptors in use by process - -@item ENFILE -Too many files are currently open in the system. - -@item ENOENT -Directory does not exist, or @code{name} is an empty string. - -@item ENOMEM -Insufficient memory to complete the operation. - -@item ENOTDIR -@code{name} is not a directory. - -@end table - -@subheading DESCRIPTION: - -This routine opens a directory stream corresponding to the -directory specified by the @code{dirname} argument. The -directory stream is positioned at the first entry. - -@subheading NOTES: - -The routine is implemented in Cygnus newlib. - -@page -@subsection readdir - Reads a directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int readdir( - DIR *dirp -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EBADF -Invalid file descriptor - -@end table - -@subheading DESCRIPTION: - -The @code{readdir()} function returns a pointer to a structure @code{dirent} -representing the next directory entry from the directory stream pointed to -by @code{dirp}. On end-of-file, NULL is returned. - -The @code{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 @code{readdir()} may be overwritten by another call to -@code{readdir()} for the same directory stream. It will not be overwritten by -a call for another directory. - -@subheading NOTES: - -If @code{ptr} is not a pointer returned by @code{malloc()}, @code{calloc()}, or -@code{realloc()} or has been deallocated with @code{free()} or -@code{realloc()}, the results are not portable and are probably disastrous. - -The routine is implemented in Cygnus newlib. - -@page -@subsection rewinddir - Resets the readdir() pointer - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -void rewinddir( - DIR *dirp -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -No value is returned. - -@subheading DESCRIPTION: - -The @code{rewinddir()} function resets the position associated with -the directory stream pointed to by @code{dirp}. It also causes the -directory stream to refer to the current state of the directory. - -@subheading NOTES: - -NONE - -If @code{dirp} is not a pointer by @code{opendir()}, the results are -undefined. - -The routine is implemented in Cygnus newlib. - -@page -@subsection scandir - Scan a directory for matching entries - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int scandir( - const char *dir, - struct direct ***namelist, - int (*select)(const struct dirent *), - int (*compar)(const struct dirent **, const struct dirent **) -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item ENOMEM -Insufficient memory to complete the operation. - -@end table - -@subheading DESCRIPTION: - -The @code{scandir()} function scans the directory @code{dir}, calling -@code{select()} on each directory entry. Entries for which @code{select()} -returns non-zero are stored in strings allocated via @code{malloc()}, -sorted using @code{qsort()} with the comparison function @code{compar()}, -and collected in array @code{namelist} which is allocated via @code{malloc()}. -If @code{select} is NULL, all entries are selected. - -@subheading NOTES: - -The routine is implemented in Cygnus newlib. - -@page -@subsection telldir - Return current location in directory stream - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -off_t telldir( - DIR *dir -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EBADF -Invalid directory stream descriptor @code{dir}. - -@end table - -@subheading DESCRIPTION: - -The @code{telldir()} function returns the current location associated with the -directory stream @code{dir}. - -@subheading NOTES: - -The routine is implemented in Cygnus newlib. - -@page -@subsection closedir - Ends directory read operation - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int closedir( - DIR *dirp -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EBADF -Invalid file descriptor - -@end table - -@subheading DESCRIPTION: - -The directory stream associated with @code{dirp} is closed. -The value in @code{dirp} may not be usable after a call to -@code{closedir()}. - -@subheading NOTES: - -NONE - -The argument to @code{closedir()} must be a pointer returned by -@code{opendir()}. If it is not, the results are not portable and -most likely unpleasant. - -The routine is implemented in Cygnus newlib. - -@page -@subsection chdir - Changes the current working directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int chdir( - const char *path -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is -in effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the specified pathname was not a directory when directory -was expected. - -@end table - -@subheading DESCRIPTION: - -The @code{chdir()} function causes the directory named by @code{path} to -become the current working directory; that is, the starting point for -searches of pathnames not beginning with a slash. - -If @code{chdir()} detects an error, the current working directory is not -changed. - -@subheading NOTES: - -NONE - -@page -@subsection getcwd - Gets current working directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int getcwd( void ); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -Invalid argument - -@item ERANGE -Result is too large - -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@end table - -@subheading DESCRIPTION: - -The @code{getcwd()} function copies the absolute pathname of the current -working directory to the character array pointed to by @code{buf}. The -@code{size} argument is the number of bytes available in @code{buf} - -@subheading NOTES: - -There is no way to determine the maximum string length that @code{fetcwd()} -may need to return. Applications should tolerate getting @code{ERANGE} -and allocate a larger buffer. - -It is possible for @code{getcwd()} to return EACCES if, say, @code{login} -puts the process into a directory without read access. - -The 1988 standard uses @code{int} instead of @code{size_t} for the second -parameter. - -@page -@subsection open - Opens a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include -#include - -int open( - const char *path, - int oflag, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b - -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@item EEXIST -The named file already exists. - -@item EINTR -Function was interrupted by a signal. - -@item EISDIR -Attempt to open a directory for writing or to rename a file to be a -directory. - -@item EMFILE -Too many file descriptors are in use by this process. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENFILE -Too many files are currently open in the system. - -@item ENOENT -A file or directory does not exist. - -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item ENXIO -No such device. This error may also occur when a device is not ready, for -example, a tape drive is off-line. - -@item EROFS -Read-only file system. -@end table - -@subheading DESCRIPTION: - -The @code{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 @code{path} argument points to the -pathname for the file. - -The @code{oflag} argument is the bitwise inclusive OR of the values of -symbolic constants. The programmer must specify exactly one of the following -three symbols: - -@table @b -@item O_RDONLY -Open for reading only. - -@item O_WRONLY -Open for writing only. - -@item O_RDWR -Open for reading and writing. - -@end table - -Any combination of the following symbols may also be used. - -@table @b -@item O_APPEND -Set the file offset to the end-of-file prior to each write. - -@item O_CREAT -If the file does not exist, allow it to be created. This flag indicates -that the @code{mode} argument is present in the call to @code{open}. - -@item O_EXCL -This flag may be used only if O_CREAT is also set. It causes the call -to @code{open} to fail if the file already exists. - -@item O_NOCTTY -If @code{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. - -@item O_NONBLOCK -Do no wait for the device or file to be ready or available. After the file -is open, the @code{read} and @code{write} calls return immediately. If the -process would be delayed in the read or write opermation, -1 is returned and -@code{errno} is set to @code{EAGAIN} instead of blocking the caller. - -@item O_TRUNC -This flag should be used only on ordinary files opened for writing. It -causes the file to be tuncated to zero length.. - -@end table - -Upon successful completion, @code{open} returns a non-negative file -descriptor. - -@subheading NOTES: - -NONE - -@page -@subsection creat - Create a new file or rewrite an existing one - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include -#include - -int creat( - const char *path, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EEXIST -@code{path} already exists and O_CREAT and O_EXCL were used. - -@item EISDIR -@code{path} refers to a directory and the access requested involved -writing - -@item ETXTBSY -@code{path} refers to an executable image which is currently being -executed and write access was requested - -@item EFAULT -@code{path} points outside your accessible address space - -@item EACCES -The requested access to the file is not allowed, or one of the -directories in @code{path} did not allow search (execute) permission. - -@item ENAMETOOLONG -@code{path} was too long. - -@item ENOENT -A directory component in @code{path} does not exist or is a dangling -symbolic link. - -@item ENOTDIR -A component used as a directory in @code{path} is not, in fact, a -directory. - -@item EMFILE -The process alreadyh has the maximum number of files open. - -@item ENFILE -The limit on the total number of files open on the system has been -reached. - -@item ENOMEM -Insufficient kernel memory was available. - -@item EROFS -@code{path} refers to a file on a read-only filesystem and write access -was requested - -@end table - -@subheading DESCRIPTION: - -@code{creat} attempts to create a file and return a file descriptor for -use in read, write, etc. - -@subheading NOTES: - -NONE - -The routine is implemented in Cygnus newlib. - -@page -@subsection umask - Sets a file creation mask. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -mode_t umask( - mode_t cmask -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@subheading DESCRIPTION: - -The @code{umask()} function sets the process file creation mask to @code{cmask}. -The file creation mask is used during @code{open()}, @code{creat()}, @code{mkdir()}, -@code{mkfifo()} calls to turn off permission bits in the @code{mode} argument. -Bit positions that are set in @code{cmask} are cleared in the mode of the -created file. - -@subheading NOTES: - -NONE - -The @code{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 @code{fork()} and @code{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. - -@page -@subsection link - Creates a link to a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int link( - const char *existing, - const char *new -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b - -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EEXIST -The named file already exists. - -@item EMLINK -The number of links would exceed @code{LINK_MAX}. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. - -@item EROFS -Read-only file system. - -@item EXDEV -Attempt to link a file to another file system. - -@end table - -@subheading DESCRIPTION: - -The @code{link()} function atomically creates a new link for an existing file -and increments the link count for the file. - -If the @code{link()} function fails, no directories are modified. - -The @code{existing} argument should not be a directory. - -The caller may (or may not) need permission to access the existing file. - -@subheading NOTES: - -NONE - -@page -@subsection symlink - Creates a symbolic link to a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int symlink( - const char *topath, - const char *frompath -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b - -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EEXIST -The named file already exists. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The @code{symlink()} function creates a symbolic link from the frombath to the -topath. The symbolic link will be interpreted at run-time. - -If the @code{symlink()} function fails, no directories are modified. - -The caller may (or may not) need permission to access the existing file. - -@subheading NOTES: - -NONE - -@page -@subsection readlink - Obtain the name of a symbolic link destination - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int readlink( - const char *path, - char *buf, - size_t bufsize -); - -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b - -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the prefix pathname was not a directory when a directory -was expected. - -@item ELOOP -Too many symbolic links were encountered in the pathname. - -@item EINVAL -The pathname does not refer to a symbolic link - -@item EFAULT -An invalid pointer was passed into the @code{readlink()} routine. - -@end table - -@subheading DESCRIPTION: - -The @code{readlink()} function places the symbolic link destination into -@code{buf} argument and returns the number of characters copied. - -If the symbolic link destination is longer than bufsize characters the -name will be truncated. - -@subheading NOTES: - -NONE - -@page -@subsection mkdir - Makes a directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int mkdir( - const char *path, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EEXIST -The name file already exist. - -@item EMLINK -The number of links would exceed LINK_MAX - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The @code{mkdir()} function creates a new diectory named @code{path}. The -permission bits (modified by the file creation mask) are set from @code{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. - -@subheading NOTES: - -NONE - -@page -@subsection mkfifo - Makes a FIFO special file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - - -int mkfifo( - const char *path, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EEXIST -The named file already exists. - -@item ENOENT -A file or directory does not exist. - -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified @code{path} was not a directory when a directory -was expected. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The @code{mkfifo()} function creates a new FIFO special file named @code{path}. -The permission bits (modified by the file creation mask) are set from -@code{mode}. The owner and group IDs for the FIFO are set from the efective -user ID and group ID. - -@subheading NOTES: - -NONE - -@page -@subsection unlink - Removes a directory entry - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int unlink( - const char path -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EBUSY -The directory is in use. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the specified @code{path} was not a directory when a directory -was expected. - -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The @code{unlink} function removes the link named by @code{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. - -@subheading NOTES: - -NONE - -@page -@subsection rmdir - Delete a directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int rmdir( - const char *pathname -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EPERM -The filesystem containing @code{pathname} does not support the removal -of directories. - -@item EFAULT -@code{pathname} points ouside your accessible address space. - -@item EACCES -Write access to the directory containing @code{pathname} was not -allowed for the process's effective uid, or one of the directories in -@code{pathname} did not allow search (execute) permission. - -@item EPERM -The directory containing @code{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. - -@item ENAMETOOLONG -@code{pathname} was too long. - -@item ENOENT -A dirctory component in @code{pathname} does not exist or is a -dangling symbolic link. - -@item ENOTDIR -@code{pathname}, or a component used as a directory in @code{pathname}, -is not, in fact, a directory. - -@item ENOTEMPTY -@code{pathname} contains entries other than . and .. . - -@item EBUSY -@code{pathname} is the current working directory or root directory of -some process - -@item EBUSY -@code{pathname} is the current directory or root directory of some -process. - -@item ENOMEM -Insufficient kernel memory was available - -@item EROGS -@code{pathname} refers to a file on a read-only filesystem. - -@item ELOOP -@code{pathname} contains a reference to a circular symbolic link - -@end table - -@subheading DESCRIPTION: - -@code{rmdir} deletes a directory, which must be empty - - -@subheading NOTES: - -NONE - -@page -@subsection rename - Renames a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int rename( - const char *old, - const char *new -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@item EBUSY -The directory is in use. - -@item EEXIST -The named file already exists. - -@item EINVAL -Invalid argument. - -@item EISDIR -Attempt to open a directory for writing or to rename a file to be a -directory. - -@item EMLINK -The number of links would exceed LINK_MAX. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is -in effect. - -@item ENOENT -A file or directory does no exist. - -@item ENOSPC -No space left on disk. - -@item ENOTDIR -A component of the specified pathname was not a directory when a -directory was expected. - -@item ENOTEMPTY -Attempt to delete or rename a non-empty directory. - -@item EROFS -Read-only file system - -@item EXDEV -Attempt to link a file to another file system. -@end table - -@subheading DESCRIPTION: - -The @code{rename()} function causes the file known bo @code{old} to -now be known as @code{new}. - -Ordinary files may be renamed to ordinary files, and directories may be -renamed to directories; however, files cannot be converted using -@code{rename()}. The @code{new} pathname may not contain a path prefix -of @code{old}. - -@subheading NOTES: - -If a file already exists by the name @code{new}, it is removed. The -@code{rename()} function is atomic. If the @code{rename()} detects an -error, no files are removed. This guarantees that the -@code{rename("x", "x")} does not remove @code{x}. - -You may not rename dot or dot-dot. - -The routine is implemented in Cygnus newlib using @code{link()} and -@code{unlink()}. - -@page -@subsection stat - Gets information about a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int stat( - const char *path, - struct stat *buf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@item EBADF -Invalid file descriptor. - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is -in effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the specified pathname was not a directory when a -directory was expected. - -@end table - -@subheading DESCRIPTION: - -The @code{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 @code{path} must be searchable. The @code{stat()} function obtains -information about the named file and writes it to the area pointed to by -@code{buf}. - -@subheading NOTES: - -NONE - -@page -@subsection fstat - Gets file status - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int fstat( - int fildes, - struct stat *buf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EBADF -Invalid file descriptor - -@end table - -@subheading DESCRIPTION: - -The @code{fstat()} function obtains information about the file -associated with @code{fildes} and writes it to the area pointed -to by the @code{buf} argument. - -@subheading NOTES: - -NONE - -@page -@subsection access - Check user's permissions for a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int access( - const char *pathname, - int mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -The requested access would be denied, either to the file itself or -one of the directories in @code{pathname}. - -@item EFAULT -@code{pathname} points outside your accessible address space. - -@item EINVAL -@code{Mode} was incorrectly specified. - -@item ENAMETOOLONG -@code{pathname} is too long. - -@item ENOENT -A directory component in @code{pathname} would have been accessible but -does not exist or was a dangling symbolic link. - -@item ENOTDIR -A component used as a directory in @code{pathname} is not, in fact, -a directory. - -@item ENOMEM -Insufficient kernel memory was available. - -@end table - -@subheading DESCRIPTION: - -@code{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 -@code{pathname}. If @code{pathname} is a symbolic link permissions of the -file referred by this symbolic link are tested. - -@code{Mode} is a mask consisting of one or more of R_OK, W_OK, X_OK and F_OK. - -@subheading NOTES: - -NONE - -@page -@subsection chmod - Changes file mode. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int chmod( - const char *path, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -Set the file permission bits, the set user ID bit, and the set group ID bit -for the file named by @code{path} to @code{mode}. If the effective user ID -does not match the owner of the file and the calling process does not have -the appropriate privileges, @code{chmod()} returns -1 and sets @code{errno} to -@code{EPERM}. - -@subheading NOTES: - -NONE - -@page -@subsection fchmod - Changes permissions of a file - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int fchmod( - int fildes, - mode_t mode -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix. - -@item EBADF -The descriptor is not valid. - -@item EFAULT -@code{path} points outside your accessible address space. - -@item EIO -A low-level I/o error occurred while modifying the inode. - -@item ELOOP -@code{path} contains a circular reference - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is -in effect. - -@item ENOENT -A file or directory does no exist. - -@item ENOMEM -Insufficient kernel memory was avaliable. - -@item ENOTDIR -A component of the specified pathname was not a directory when a -directory was expected. - -@item EPERM -The effective UID does not match the owner of the file, and is not -zero - -@item EROFS -Read-only file system -@end table - -@subheading DESCRIPTION: - -The mode of the file given by @code{path} or referenced by -@code{filedes} is changed. - -@subheading NOTES: - -NONE - -@page -@subsection getdents - Get directory entries - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include -#include - -long getdents( - int dd_fd, - char *dd_buf, - int dd_len -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -A successful call to @code{getdents} returns th the number of bytes read. -On end of directory, 0 is returned. When an error occurs, -1 is returned, -and @code{errno} is set appropriately. - -@table @b -@item EBADF -Invalid file descriptor @code{fd}. - -@item EFAULT -Argument points outside the calling process's address space. - -@item EINVAL -Result buffer is too small. - -@item ENOENT -No such directory. - -@item ENOTDIR -File descriptor does not refer to a directory. - -@end table - -@subheading DESCRIPTION: - -@code{getdents} reads several @code{dirent} structures from the directory -pointed by @code{fd} into the memory area pointed to by @code{dirp}. The -parameter @code{count} is the size of the memory area. - -@subheading NOTES: - -NONE - -@page -@subsection chown - Changes the owner and/or group of a file. - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include - -int chown( - const char *path, - uid_t owner, - gid_t group -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Search permission is denied for a directory in a file's path prefix - -@item EINVAL -Invalid argument - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC is in -effect. - -@item ENOENT -A file or directory does not exist. - -@item ENOTDIR -A component of the specified pathname was not a directory when a directory -was expected. - -@item EPERM -Operation is not permitted. Process does not have the appropriate priviledges -or permissions to perform the requested operations. - -@item EROFS -Read-only file system. - -@end table - -@subheading DESCRIPTION: - -The user ID and group ID of the file named by @code{path} are set to -@code{owner} and @code{path}, respectively. - -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 @code{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. - -@subheading NOTES: - -This function may be restricted for some file. The @code{pathconf} function -can be used to test the @code{_PC_CHOWN_RESTRICTED} flag. - - - -@page -@subsection utime - Change access and/or modification times of an inode - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int utime( - const char *filename, - struct utimbuf *buf -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EACCES -Permission to write the file is denied - -@item ENOENT -@code{Filename} does not exist - -@end table - -@subheading DESCRIPTION: - -@code{Utime} changes the access and modification times of the inode -specified by @code{filename} to the @code{actime} and @code{modtime} -fields of @code{buf} respectively. If @code{buf} is NULL, then the -access and modification times of the file are set to the current time. - -@subheading NOTES: - -NONE - -@page -@subsection ftruncate - truncate a file to a specified length - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int ftrunctate( - int fd, - size_t length -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item ENOTDIR -A component of the path prefix is not a directory. - -@item EINVAL -The pathname contains a character with the high-order bit set. - -@item ENAMETOOLONG -A component of a pathname exceeded 255 characters, or an entire -path name exceeded 1023 characters. - -@item ENOENT -The named file does not exist. - -@item EACCES -The named file is not writable by the user. - -@item EACCES -Search permission is denied for a component of the path prefix. - -@item ELOOP -Too many symbolic links were encountered in translating the -pathname - -@item EISDIR -The named file is a directory. - -@item EROFS -The named file resides on a read-only file system - -@item ETXTBSY -The file is a pure procedure (shared text) file that is being -executed - -@item EIO -An I/O error occurred updating the inode. - -@item EFAULT -@code{Path} points outside the process's allocated address space. - -@item EBADF -The @code{fd} is not a valid descriptor. - -@end table - -@subheading DESCRIPTION: - -@code{truncate()} causes the file named by @code{path} or referenced by -@code{fd} to be truncated to at most @code{length} bytes in size. If the -file previously was larger than this size, the extra data is lost. With -@code{ftruncate()}, the file must be open for writing. - -@subheading NOTES: - -NONE - -@page -@subsection truncate - truncate a file to a specified length - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int trunctate( - const char *path, - size_t length -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item ENOTDIR -A component of the path prefix is not a directory. - -@item EINVAL -The pathname contains a character with the high-order bit set. - -@item ENAMETOOLONG -A component of a pathname exceeded 255 characters, or an entire -path name exceeded 1023 characters. - -@item ENOENT -The named file does not exist. - -@item EACCES -The named file is not writable by the user. - -@item EACCES -Search permission is denied for a component of the path prefix. - -@item ELOOP -Too many symbolic links were encountered in translating the -pathname - -@item EISDIR -The named file is a directory. - -@item EROFS -The named file resides on a read-only file system - -@item ETXTBSY -The file is a pure procedure (shared text) file that is being -executed - -@item EIO -An I/O error occurred updating the inode. - -@item EFAULT -@code{Path} points outside the process's allocated address space. - -@item EBADF -The @code{fd} is not a valid descriptor. - -@end table - -@subheading DESCRIPTION: - -@code{truncate()} causes the file named by @code{path} or referenced by -@code{fd} to be truncated to at most @code{length} bytes in size. If the -file previously was larger than this size, the extra data is lost. With -@code{ftruncate()}, the file must be open for writing. - -@subheading NOTES: - -NONE - -@page -@subsection pathconf - Gets configuration values for files - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int pathconf( - const char *path, - int name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -Invalid argument - -@item EACCES -Permission to write the file is denied - -@item ENAMETOOLONG -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC -is in effect. - -@item ENOENT -A file or directory does not exist - -@item ENOTDIR -A component of the specified @code{path} was not a directory whan a -directory was expected. - -@end table - -@subheading DESCRIPTION: - -@code{pathconf()} gets a value for the configuration option @code{name} -for the open file descriptor @code{filedes}. - -The possible values for @code{name} are: - -@table @b -@item _PC_LINK_MAX -returns the maximum number of links to the file. If @code{filedes} or -@code{path} refer to a directory, then the value applies to the whole -directory. The corresponding macro is @code{_POSIX_LINK_MAX}. - -@item _PC_MAX_CANON -returns the maximum length of a formatted input line, where @code{filedes} -or @code{path} must refer to a terminal. The corresponding macro is -@code{_POSIX_MAX_CANON}. - -@item _PC_MAX_INPUT -returns the maximum length of an input line, where @code{filedes} or -@code{path} must refer to a terminal. The corresponding macro is -@code{_POSIX_MAX_INPUT}. - -@item _PC_NAME_MAX -returns the maximum length of a filename in the directory @code{path} or -@code{filedes}. The process is allowed to create. The corresponding macro -is @code{_POSIX_NAME_MAX}. - -@item _PC_PATH_MAX -returns the maximum length of a relative pathname when @code{path} or -@code{filedes} is the current working directory. The corresponding macro -is @code{_POSIX_PATH_MAX}. - -@item _PC_PIPE_BUF -returns the size of the pipe buffer, where @code{filedes} must refer to a -pipe or FIFO and @code{path} must refer to a FIFO. The corresponding macro -is @code{_POSIX_PIPE_BUF}. - -@item _PC_CHOWN_RESTRICTED -returns nonzero if the chown(2) call may not be used on this file. If -@code{filedes} or @code{path} refer to a directory, then this applies to all -files in that directory. The corresponding macro is -@code{_POSIX_CHOWN_RESTRICTED}. - -@end table - -@subheading NOTES: - -Files with name lengths longer than the value returned for @code{name} equal -@code{_PC_NAME_MAX} may exist in the given directory. - -@page -@subsection fpathconf - Gets configuration values for files - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include - -int fpathconf( - int filedes, - int name -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@table @b -@item EINVAL -Invalid argument - -@item EACCES -Permission to write the file is denied -@item ENAMETOOLONG - -Length of a filename string exceeds PATH_MAX and _POSIX_NO_TRUNC -is in effect. - -@item ENOENT -A file or directory does not exist - -@item ENOTDIR -A component of the specified @code{path} was not a directory whan a -directory was expected. - -@end table - - -@subheading DESCRIPTION: - -@code{pathconf()} gets a value for the configuration option @code{name} -for the open file descriptor @code{filedes}. - -The possible values for name are: - -@table @b -@item _PC_LINK_MAX -returns the maximum number of links to the file. If @code{filedes} or -@code{path} refer to a directory, then the value applies to the whole -directory. The corresponding macro is _POSIX_LINK_MAX. - -@item _PC_MAX_CANON -returns the maximum length of a formatted input line, where @code{filedes} -or @code{path} must refer to a terminal. The corresponding macro is -@code{_POSIX_MAX_CANON}. - -@item _PC_MAX_INPUT -returns the maximum length of an input line, where @code{filedes} or -@code{path} must refer to a terminal. The corresponding macro is -@code{_POSIX_MAX_INPUT}. - -@item _PC_NAME_MAX -returns the maximum length of a filename in the directory @code{path} or -@code{filedes}. The process is allowed to create. The corresponding macro -is @code{_POSIX_NAME_MAX}. - -@item _PC_PATH_MAX -returns the maximum length of a relative pathname when @code{path} or -@code{filedes} is the current working directory. The corresponding macro -is @code{_POSIX_PATH_MAX}. - -@item _PC_PIPE_BUF -returns the size of the pipe buffer, where @code{filedes} must refer to a -pipe or FIFO and @code{path} must refer to a FIFO. The corresponding macro -is @code{_POSIX_PIPE_BUF}. - -@item _PC_CHOWN_RESTRICTED -returns nonzero if the @code{chown()} call may not be used on this file. If -@code{filedes} or @code{path} refer to a directory, then this applies to all -files in that directory. The corresponding macro is -@code{_POSIX_CHOWN_RESTRICTED}. - -@end table - -@subheading NOTES: - -NONE - -@page -@subsection mknod - create a directory - -@subheading CALLING SEQUENCE: - -@ifset is-C -@example -#include -#include -#include -#include - -long mknod( - const char *pathname, - mode_t mode, - dev_t dev -); -@end example -@end ifset - -@ifset is-Ada -@end ifset - -@subheading STATUS CODES: - -@code{mknod} returns zero on success, or -1 if an error occurred (in which case, -errno is set appropriately). - -@table @b -@item ENAMETOOLONG -@code{pathname} was too long. - -@item ENOENT -A directory component in @code{pathname} does not exist or is a dangling symbolic -link. - -@item ENOTDIR -A component used in the directory @code{pathname} is not, in fact, a directory. - -@item ENOMEM -Insufficient kernel memory was available - -@item EROFS -@code{pathname} refers to a file on a read-only filesystem. - -@item ELOOP -@code{pathname} contains a reference to a circular symbolic link, ie a symbolic -link whose expansion contains a reference to itself. - -@item ENOSPC -The device containing @code{pathname} has no room for the new node. - -@end table - -@subheading DESCRIPTION: - -@code{mknod} attempts to create a filesystem node (file, device special file or -named pipe) named @code{pathname}, specified by @code{mode} and @code{dev}. - -@code{mode} specifies both the permissions to use and the type of node to be created. - -It should be a combination (using bitwise OR) of one of the file types listed -below and the permissions for the new node. - -The permissions are modified by the process's @code{umask} in the usual way: the -permissions of the created node are @code{(mode & ~umask)}. - -The file type should be one of @code{S_IFREG}, @code{S_IFCHR}, @code{S_IFBLK} and -@code{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 @code{S_IFCHR} or @code{S_IFBLK} then @code{dev} specifies the major -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. - - -@subheading NOTES: - -NONE -- cgit v1.2.3