summaryrefslogtreecommitdiffstats
path: root/doc/new_chapters
diff options
context:
space:
mode:
authorWade A Smith <warm38@juno.com>1998-09-25 20:11:51 +0000
committerWade A Smith <warm38@juno.com>1998-09-25 20:11:51 +0000
commit64183e20f0d8be5471f0484cede014f121c40b79 (patch)
treeb732f7bb387bdaf42c2a87a9ac78affa18224bef /doc/new_chapters
parent9a0b0089c39004c6a6bb6d27d5778998e206e8fc (diff)
downloadrtems-64183e20f0d8be5471f0484cede014f121c40b79.tar.bz2
Documented the creat, scandir, and access routines.
Diffstat (limited to 'doc/new_chapters')
-rw-r--r--doc/new_chapters/files.t142
1 files changed, 120 insertions, 22 deletions
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 <dirent.h>
+
+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 <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+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 <unistd.h>
+
+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 <sys/types.h>
+
+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