From 64183e20f0d8be5471f0484cede014f121c40b79 Mon Sep 17 00:00:00 2001 From: Wade A Smith Date: Fri, 25 Sep 1998 20:11:51 +0000 Subject: Documented the creat, scandir, and access routines. --- doc/new_chapters/files.t | 142 +++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 120 insertions(+), 22 deletions(-) (limited to 'doc/new_chapters') diff --git a/doc/new_chapters/files.t b/doc/new_chapters/files.t index 8e4b598921..981aa52daf 100644 --- a/doc/new_chapters/files.t +++ b/doc/new_chapters/files.t @@ -19,19 +19,20 @@ The directives provided by the files and directories manager are: @item @code{readdir} - Reads a directory @item @code{readdir_r} - @item @code{rewinddir} - -@item @code{scandir} - +@item @code{scandir} - Scan a directory for matching entries @item @code{telldir} - @item @code{closedir} - +@item @code{getdents} @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{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{mkdir} - Makes a directory @item @code{mkfifo} - @item @code{unlink} - Removes a directory entry -@item @code{rmdir} - +@item @code{rmdir} - Delete a directory @item @code{rename} - Renames a file @item @code{stat} - Gets information about a file. @item @code{fstat} - @@ -39,7 +40,7 @@ The directives provided by the files and directories manager are: @item @code{chmod} - Changes file mode @item @code{fchmod} - @item @code{chown} - Changes the owner and/ or group of a file -@item @code{utime} - +@item @code{utime} - Change access and/or modification times of an inode @item @code{ftrunctate} - @item @code{pathconf} - @item @code{fpathconf} - @@ -205,13 +206,18 @@ The The routine is implemented in Cygnus newlib. @page -@subsection scandir - +@subsection scandir - Scan a directory for matching entries @subheading CALLING SEQUENCE: @ifset is-C @example -int scandir( +#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 @@ -222,13 +228,20 @@ int scandir( @subheading STATUS CODES: @table @b -@item E -The +@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. @@ -504,13 +517,18 @@ descriptor. @page -@subsection creat - +@subsection creat - Create a new file or rewrite an existing one @subheading CALLING SEQUENCE: @ifset is-C @example -int creat( +#include +#include +#include + +int creat(const char *path, + mode_t mode ); @end example @end ifset @@ -521,14 +539,46 @@ int creat( @subheading STATUS CODES: @table @b -@item E -The +@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: -@subheading NOTES: +@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. @@ -766,13 +816,15 @@ file is no longer accessible. @subheading NOTES: None @page -@subsection rmdir - +@subsection rmdir - Delete a directory @subheading CALLING SEQUENCE: @ifset is-C @example -int rmdir( +#include + +int rmdir(const char *pathname ); @end example @end ifset @@ -783,14 +835,50 @@ int rmdir( @subheading STATUS CODES: @table @b -@item E -The +@item EPERM +The filesystem containing @code{pathname} does not support the removal +of directories. +@item EFAULT +@cdoe{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 sybolic 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. +@itemELOOP +@code{Pathname} contains a reference to a circular symbolic link @end table @subheading DESCRIPTION: -@subheading NOTES: +@code{rmdir} deletes a directory, whic must be empty + + +@subheading NOTES: None @page @subsection rename - Renames a file @@ -1136,13 +1224,16 @@ can be used to test the _PC_CHOWN_RESTRICTED flag. @page -@subsection utime - +@subsection utime - Change access and/or modification times of an inode @subheading CALLING SEQUENCE: @ifset is-C @example -int utime( +#include + +int utime(const char *filename, + struct utimbuf *buf ); @end example @end ifset @@ -1153,13 +1244,20 @@ int utime( @subheading STATUS CODES: @table @b -@item E -The +@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: @page -- cgit v1.2.3