Subversion Repositories or1k

@c

@c COPYRIGHT (c) 1988-2002.

@c On-Line Applications Research Corporation (OAR).

@c All rights reserved.

@c

@c files.t,v 1.11 2002/01/17 21:47:45 joel Exp

@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{fchdir} - 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{lstat} - Gets file status

@item @code{access} - Check 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

@subsection Path Name Evaluation

A pathname is a string that consists of no more than @code{PATH_MAX}

bytes, including the terminating null character. A pathname has an optional

beginning slash, followed by zero or more filenames separated by slashes.

If the pathname refers to a directory, it may also have one or more trailing

slashes. Multiple successive slahes are considered to be the same as

one slash.

POSIX allows a pathname that begins with precisely two successive slashes to be

interpreted in an implementation-defined manner. RTEMS does not currently

recognize this as a special condition. Any number of successive

slashes is treated the same as a single slash. POSIX requires that

an implementation treat more than two leading slashes as a single slash.

@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.

@c

@c

@c

@page

@subsection opendir - Open a Directory

@findex opendir

@cindex  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.

@c

@c

@c

@page

@subsection readdir - Reads a directory

@findex readdir

@cindex  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.

@c

@c

@c

@page

@subsection rewinddir - Resets the readdir() pointer

@findex rewinddir

@cindex  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.

@c

@c

@c

@page

@subsection scandir - Scan a directory for matching entries

@findex scandir

@cindex  scan a directory for matching entries

@subheading CALLING SEQUENCE:

@ifset is-C

@example

#include 

int scandir(

  const char       *dir,

  struct dirent ***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.

@c

@c

@c

@page

@subsection telldir - Return current location in directory stream

@findex telldir

@cindex  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.

@c

@c

@c

@page

@subsection closedir - Ends directory read operation

@findex closedir

@cindex  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.

@c

@c

@c

@page

@subsection chdir - Changes the current working directory

@findex chdir

@cindex  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:

On error, this routine returns -1 and sets @code{errno} to one of

the following:

@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

@c

@c

@c

@page

@subsection fchdir - Changes the current working directory

@findex fchdir

@cindex  changes the current working directory

@subheading CALLING SEQUENCE:

@ifset is-C

@example

#include 

int fchdir(

  int fd

);

@end example

@end ifset

@ifset is-Ada

@end ifset

@subheading STATUS CODES:

On error, this routine returns -1 and sets @code{errno} to one of

the following:

@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{fchdir()} function causes the directory named by @code{fd} to

become the current working directory; that is, the starting point for

searches of pathnames not beginning with a slash.

If @code{fchdir()} detects an error, the current working directory is not

changed.

@subheading NOTES:

NONE

@c

@c

@c

@page

@subsection getcwd - Gets current working directory

@findex getcwd

@cindex  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.

@c

@c

@c

@page

@subsection open - Opens a file

@findex open

@cindex  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

@c

@c

@c

@page

@subsection creat - Create a new file or rewrite an existing one

@findex creat

@cindex  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.

@c

@c

@c

@page

@subsection umask - Sets a file creation mask.

@findex umask

@cindex  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.

@c

@c

@c

@page

@subsection link - Creates a link to a file

@findex link

@cindex  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

@c

@c

@c

@page

@subsection symlink - Creates a symbolic link to a file

@findex symlink

@cindex  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.