Next Previous Contents

## 15. Directory Functions

## 15.1 chdir

Synopsis

  Change the current working directory

Usage

  `Int_Type chdir (String_Type dir)`

Description

  The `chdir` function may be used to change the current working directory to the directory specified by `dir`. Upon success it returns zero. Upon failure it returns `-1` and sets `errno` accordingly.

See Also

  `mkdir, stat_file`

## 15.2 chmod

Synopsis

  Change the mode of a file

Usage

  `Int_Type chmod (String_Type file, Int_Type mode)`

Description

  The `chmod` function changes the permissions of the specified file to those given by `mode`. It returns `0` upon success, or `-1` upon failure setting `errno` accordingly.

  See the system specific documentation for the C library function `chmod` for a discussion of the `mode` parameter.

See Also

  `chown, stat_file`

## 15.3 chown

Synopsis

  Change the owner of a file

Usage

  `Int_Type chown (String_Type file, Int_Type uid, Int_Type gid)`

Description

  The `chown` function is used to change the user-id and group-id of `file` to `uid` and `gid`, respectively. It returns 0 upon success and -1 upon failure, with `errno` set accordingly.

Notes

  On most systems, only the superuser can change the ownership of a file.

  Some systems do not support this function.

See Also

  `chmod, stat_file`

## 15.4 getcwd

Synopsis

  Get the current working directory

Usage

  `String_Type getcwd ()`

Description

  The `getcwd` function returns the absolute pathname of the current working directory. If an error occurs or it cannot determine the working directory, it returns `NULL` and sets `errno` accordingly.

Notes

  Under Unix, OS/2, and MSDOS, the pathname returned by this function includes the trailing slash character. It may also include the drive specifier for systems where that is meaningful.

See Also

  `mkdir, chdir, errno`

## 15.5 listdir

Synopsis

  Get a list of the files in a directory

Usage

  `String_Type[] listdir (String_Type dir)`

Description

  The `listdir` function returns the directory listing of all the files in the specified directory `dir` as an array of strings. It does not return the special files `".."` and `"."` as part of the list.

See Also

  `stat_file, stat_is, length`

## 15.6 lstat_file

Synopsis

  Get information about a symbolic link

Usage

  `Struct_Type lstat_file (String_Type file)`

Description

  The `lstat_file` function behaves identically to `stat_file` but if `file` is a symbolic link, `lstat_file` returns information about the link itself, and not the file that it references.

  See the documentation for `stat_file` for more information.

Notes

  On systems that do not support symbolic links, there is no difference between this function and the `stat_file` function.

See Also

  `stat_file, readlink`

## 15.7 mkdir

Synopsis

  Create a new directory

Usage

  `Int_Type mkdir (String_Type dir [,Int_Type mode])`

Description

  The `mkdir` function creates a directory whose name is specified by the `dir` parameter with permissions given by the optional `mode` parameter. Upon success `mkdir` returns 0, or it returns `-1` upon failure setting `errno` accordingly. In particular, if the directory already exists, the function will fail and set errno to `EEXIST`.

Example

  > `

  >          define my_mkdir (dir)
  >          {
  >             if (0 == mkdir (dir)) return;
  >             if (errno == EEXIST) return;
  >             throw IOError,
  >                sprintf ("mkdir %s failed: %s", dir, errno_string (errno));
  >          }

  > `

Notes

  The `mode` parameter may not be meaningful on all systems. On systems where it is meaningful, the actual permissions on the newly created directory are modified by the process's umask.

See Also

  `rmdir, getcwd, chdir, fopen, errno`

## 15.8 readlink

Synopsis

  String_Type readlink (String_Type path)

Usage

  `Get the value of a symbolic link`

Description

  The `readlink` function returns the value of a symbolic link. Upon failure, `NULL` is returned and `errno` set accordingly.

Notes

  Not all systems support this function.

See Also

  `symlink, lstat_file, stat_file, stat_is`

## 15.9 remove

Synopsis

  Delete a file

Usage

  `Int_Type remove (String_Type file)`

Description

  The `remove` function deletes a file. It returns 0 upon success, or -1 upon error and sets `errno` accordingly.

See Also

  `rename, rmdir`

## 15.10 rename

Synopsis

  Rename a file

Usage

  `Int_Type rename (String_Type old, String_Type new)`

Description

  The `rename` function renames a file from `old` to `new` moving it between directories if necessary. This function may fail if the directories are not on the same file system. It returns 0 upon success, or -1 upon error and sets `errno` accordingly.

See Also

  `remove, errno`

## 15.11 rmdir

Synopsis

  Remove a directory

Usage

  `Int_Type rmdir (String_Type dir)`

Description

  The `rmdir` function deletes the specified directory. It returns 0 upon success or -1 upon error and sets `errno` accordingly.

Notes

  The directory must be empty before it can be removed.

See Also

  `rename, remove, mkdir`

## 15.12 stat_file

Synopsis

  Get information about a file

Usage

  `Struct_Type stat_file (String_Type file)`

Description

  The `stat_file` function returns information about `file` through the use of the system `stat` call. If the stat call fails, the function returns `NULL` and sets errno accordingly. If it is successful, it returns a stat structure with the following integer-value fields:

  > `

  >         st_dev
  >         st_ino
  >         st_mode
  >         st_nlink
  >         st_uid
  >         st_gid
  >         st_rdev
  >         st_size
  >         st_atime
  >         st_mtime
  >         st_ctime

  > `

  See the C library documentation of `stat` for a discussion of the meanings of these fields.
Example

  The following example shows how the `stat_file` function may be used to get the size of a file:

  > `

  >          define file_size (file)
  >          {
  >             variable st;
  >             st = stat_file(file);
  >             if (st == NULL)
  >               throw IOError, "Unable to stat $file"$;
  >             return st.st_size;
  >          }

  > `

See Also

  `lstat_file, stat_is`

## 15.13 stat_is

Synopsis

  Parse the st_mode field of a stat structure

Usage

  `Char_Type stat_is (String_Type type, Int_Type st_mode)`

Description

  The `stat_is` function returns a boolean value according to whether or not the `st_mode` parameter is of the specified type. Specifically, `type` must be one of the strings:

  > `

  >          "sock"     (socket)
  >          "fifo"     (fifo)
  >          "blk"      (block device)
  >          "chr"      (character device)
  >          "reg"      (regular file)
  >          "lnk"      (link)
  >          "dir"      (dir)

  > `

  It returns a non-zero value if `st_mode` corresponds to `type`.
Example

  The following example illustrates how to use the `stat_is` function to determine whether or not a file is a directory:

  > `

  >          define is_directory (file)
  >          {
  >             variable st;

  >             st = stat_file (file);
  >             if (st == NULL) return 0;
  >             return stat_is ("dir", st.st_mode);
  >          }

  > `

See Also

  `stat_file, lstat_file`

## 15.14 symlink

Synopsis

  Create a symbolic link

Usage

  `status = symlink (String_Type oldpath, String_Type new_path)`

Description

  The `symlink` function may be used to create a symbolic link named `new_path` for `oldpath`. If successful, the function returns 0, otherwise it returns -1 and sets `errno` appropriately.

Notes

  This function is not supported on all systems and even if supported, not all file systems support the concept of a symbolic link.

See Also

  `readlink`

Next Previous Contents