Description: Documentation

## function chdir

### Synopsis

Change the current working directory.

### Usage

Integer_Type chdir (String_Type dir)

### Description

The chdir function may be used to changed the current working directory to the directory specified by dir . Upon sucess it returns zero; however, upon failure it returns -1 and sets errno accordingly.

### See also

mkdir , stat_file

## function chmod

### Synopsis

Change the mode of a file

### Usage

Integer_Type chmod (String_Type file, Integer_Type mode)

### Description

The chmod function changes the permissions of file to those specified 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

## function chown

### Synopsis

Change the owner of a file

### Usage

Integer_Type chown (String_Type file, Integer_Type uid, Integer_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 zero upon success and -1 upon failure, with errno set accordingly.

### Notes

On most systems, only the super user can change the ownership of a file. Some systems do not support this function.

### See also

chmod , stat_file

## function 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. Some versions also include the drive specifier.

### See also

mkdir , chdir , errno

## function 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

## function 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

## function mkdir

### Synopsis

Create a new directory

### Usage

Integer_Type mkdir (String_Type dir, Integer_Type mode)

### Description

The mkdir function creates a directory whose name is specified by the dir parameter with permissions specified by mode . Upon success mkdir returns zero, or it returns -1 and sets 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, 0777)) return;
            if (errno == EEXIST) return;
            verror ("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

## function 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 and returns it as a string. Upon failure, \NULL is returned and errno set accordingly.

### Notes

Not all systems support this function.

### See also

lstat_file , stat_file , stat_is

## function remove

### Synopsis

Delete a file

### Usage

Integer_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

## function rename

### Synopsis

Rename a file

### Usage

Integer_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 do not refer to the same file system. It returns 0 upon success, or \-1 upon error and sets errno accordingly.

### See also

remove , errno

## function rmdir

### Synopsis

Remove a directory

### Usage

Integer_Type rmdir (String_Type dir)

### Description

The rmdir function deletes a 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

## function 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 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 man page for stat for a discussion 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) verror ("Unable to stat %s", file);
            return st.st_size;
         }

### See also

lstat_file , stat_is

## function stat_is

### Synopsis

Parse the st_mode field of a stat structure

### Usage

Char_Type stat_is (String_Type type, Integer_Type st_mode)

### Description

The stat_is function returns a signed character value about the type of file specified by st_mode . 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