From 1d2366e5ea16beb0d3cfb06fae2a617c5b235ac6 Mon Sep 17 00:00:00 2001 From: Joel Sherrill Date: Fri, 25 Sep 1998 12:50:36 +0000 Subject: Stuff added by Kerwin. --- doc/new_chapters/files.t | 589 ++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 525 insertions(+), 64 deletions(-) (limited to 'doc') diff --git a/doc/new_chapters/files.t b/doc/new_chapters/files.t index 09bc2bb076..01a05d3d71 100644 --- a/doc/new_chapters/files.t +++ b/doc/new_chapters/files.t @@ -10,34 +10,35 @@ @section Introduction -The -files and directories manager is ... +The files and directories manager is ... The directives provided by the files and directories manager are: @itemize @bullet -@item @code{opendir} - -@item @code{readdir} - +@item @code{opendir} - Open a Directory +@item @code{readdir} - Reads a directory @item @code{readdir_r} - @item @code{rewinddir} - +@item @code{scandir} - +@item @code{telldir} - @item @code{closedir} - -@item @code{chdir} - -@item @code{getcwd} - -@item @code{open} - +@item @code{chdir} - Changes the current working directory +@item @code{getcwd} - Gets current working directory +@item @code{open} - Opens a file @item @code{creat} - -@item @code{umask} - -@item @code{link} - -@item @code{mkdir} - +@item @code{umask} - Sets a file creation mask +@item @code{link} - Creates a link to a file +@item @code{mkdir} - Makes a directory @item @code{mkfifo} - -@item @code{unlink} - +@item @code{unlink} - Removes a directory entry @item @code{rmdir} - -@item @code{rename} - -@item @code{stat} - +@item @code{rename} - Renames a file +@item @code{stat} - Gets information about a file. @item @code{fstat} - @item @code{access} - -@item @code{chmod} - +@item @code{chmod} - Changes file mode @item @code{fchmod} - -@item @code{chown} - +@item @code{chown} - Changes the owner and/ or group of a file @item @code{utime} - @item @code{ftrunctate} - @item @code{pathconf} - @@ -56,13 +57,17 @@ and describes the calling sequence, related constants, usage, and status codes. @page -@subsection opendir - +@subsection opendir - Open a Directory @subheading CALLING SEQUENCE: @ifset is-C @example +#include +#include + int opendir( + const char *dirname ); @end example @end ifset @@ -73,6 +78,11 @@ int opendir( @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 +for the directory itself. + @item E The @@ -80,16 +90,26 @@ The @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 - +@subsection readdir - Reads a directory @subheading CALLING SEQUENCE: @ifset is-C @example +#include +#include + int readdir( + DIR *dirp ); @end example @end ifset @@ -100,15 +120,32 @@ int readdir( @subheading STATUS CODES: @table @b -@item E -The +@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 readdir_r - @@ -136,6 +173,8 @@ The @subheading NOTES: +XXX must be implemented in RTEMS. + @page @subsection rewinddir - @@ -163,14 +202,16 @@ The @subheading NOTES: +The routine is implemented in Cygnus newlib. + @page -@subsection closedir - +@subsection scandir - @subheading CALLING SEQUENCE: @ifset is-C @example -int closedir( +int scandir( ); @end example @end ifset @@ -190,14 +231,16 @@ The @subheading NOTES: +The routine is implemented in Cygnus newlib. + @page -@subsection chdir - +@subsection telldir - @subheading CALLING SEQUENCE: @ifset is-C @example -int chdir( +int telldir( ); @end example @end ifset @@ -217,14 +260,17 @@ The @subheading NOTES: +The routine is implemented in Cygnus newlib. + + @page -@subsection getcwd - +@subsection closedir - @subheading CALLING SEQUENCE: @ifset is-C @example -int getcwd( +int closedir( ); @end example @end ifset @@ -244,14 +290,18 @@ The @subheading NOTES: +The routine is implemented in Cygnus newlib. + @page -@subsection open - +@subsection chdir - Changes the current working directory @subheading CALLING SEQUENCE: @ifset is-C @example -int open( +#include + +int chdir( const char *path ); @end example @end ifset @@ -262,23 +312,43 @@ int open( @subheading STATUS CODES: @table @b -@item E -The +@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: -@subheading NOTES: +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 creat - +@subsection getcwd - Gets current working directory @subheading CALLING SEQUENCE: @ifset is-C @example -int creat( +#include + +int getcwd( ); @end example @end ifset @@ -289,23 +359,158 @@ int creat( @subheading STATUS CODES: @table @b -@item E -The +@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 @cdoe{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: + @page -@subsection umask - +@subsection creat - @subheading CALLING SEQUENCE: @ifset is-C @example -int umask( +int creat( ); @end example @end ifset @@ -325,14 +530,59 @@ The @subheading NOTES: +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 - +@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 @@ -343,23 +593,58 @@ int link( @subheading STATUS CODES: @table @b -@item E -The +@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: -@subheading NOTES: +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 callder may (or may not) need permission to access the existing file. + +@subheading NOTES: None @page -@subsection mkdir - +@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 @@ -370,14 +655,38 @@ int mkdir( @subheading STATUS CODES: @table @b -@item E -The +@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: -@subheading NOTES: +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 - @@ -407,13 +716,16 @@ The @subheading NOTES: @page -@subsection unlink - +@subsection unlink - Removes a directory entry @subheading CALLING SEQUENCE: @ifset is-C @example +#include + int unlink( + const char path ); @end example @end ifset @@ -424,14 +736,34 @@ int unlink( @subheading STATUS CODES: @table @b -@item E -The +@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 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: -@subheading NOTES: +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 - @@ -461,13 +793,16 @@ The @subheading NOTES: @page -@subsection rename - +@subsection rename - Renames a file @subheading CALLING SEQUENCE: @ifset is-C @example -int rename( +#include + +int rename(const char *old, + const char *new ); @end example @end ifset @@ -478,23 +813,71 @@ int rename( @subheading STATUS CODES: @table @b -@item E -The - +@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 - +@subsection stat - Gets information about a file @subheading CALLING SEQUENCE: @ifset is-C @example -int stat( +#include +#include + +int stat(const char *path, + struct stat *buf ); @end example @end ifset @@ -505,14 +888,30 @@ int stat( @subheading STATUS CODES: @table @b -@item E -The +@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: -@subheading NOTES: +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{but}. + +@subheading NOTES: None @page @subsection fstat - @@ -569,13 +968,18 @@ The @subheading NOTES: @page -@subsection chmod - +@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 @@ -586,13 +990,32 @@ int chmod( @subheading STATUS CODES: @table @b -@item E -The +@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: @page @@ -623,13 +1046,19 @@ The @subheading NOTES: @page -@subsection chown - +@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 @@ -640,15 +1069,47 @@ int chown( @subheading STATUS CODES: @table @b -@item E -The +@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 _PC_CHOWN_RESTRICTED flag. + + + @page @subsection utime - -- cgit v1.2.3