summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/new_chapters/files.t589
1 files changed, 525 insertions, 64 deletions
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 <sys/types.h>
+#include <dirent.h>
+
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 <sys/types.h>
+#include <dirent.h>
+
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 <unistd.h>
+
+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 <unistd.h>
+
+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 <sys/types.h>
+#include <sys/stat.h>
+#include <fcntl.h>
+
+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 <sys/types.h>
+#include <sys/stat.h>
+
+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 <unistd.h>
+
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 <sys/types.h>
+#include <sys/stat.h>
+
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 <unistd.h>
+
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 <unistd.h>
+
+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 <sys/types.h>
+#include <sys/stat.h>
+
+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 <sys/types.h>
+#include <sys/stat.h>
+
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 <sys/types.h>
+#include <unistd.h>
+
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 -