Next Previous Contents

17. Directory Functions

17.1 access

Synopsis

Check to see if a file is accessible

Usage

Int_Type access (String_Type pathname, Int_Type mode)

Description

This functions checks to see if the current process has access to the specified pathname. The mode parameter determines the type of desired access. Its value is given by the bitwise-or of one or more of the following constants:

    R_OK   Check for read permission
    W_OK   Check for write permission
    X_OK   Check for execute permission
    F_OK   Check for existence

The function will return 0 if process has the requested access permissions to the file, otherwise it will return -1 and set errno accordingly.

Access to a file depend not only upon the file itself, but also upon the permissions of each of the directories in the pathname. The checks are done using the real user and group ids of the process, and not using the effective ids.

See Also

stat_file

17.2 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

17.3 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

17.4 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

lchown, chmod, stat_file

17.5 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

17.6 hardlink

Synopsis

Create a hard-link

Usage

Int_Type hardlink (String_Type oldpath, String_Type newpath)

Description

The hardlink function creates a hard-link called newpath to the existing file oldpath. If the link was successfully created, the function will return 0. Upon error, the function returns -1 and sets errno accordingly.

Notes

Not all systems support the concept of a hard-link.

See Also

symlink

17.7 lchown

Synopsis

Change the owner of a file

Usage

Int_Type lchown (String_Type file, Int_Type uid, Int_Type gid)

Description

The lchown function is like chown, except that it does not dereference a symbolic link. Hence, it may be used to change the ownership of a symbolic link itself, and not to what it references. See the documentation for the chown function for more details.

See Also

chown, chmod, stat_file

17.8 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

17.9 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, stat_is, stat_mode_to_string, readlink

17.10 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

The following function creates a new directory, if it does not already exist (indicated by errno==EEXIST).

     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

17.11 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

17.12 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

17.13 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

17.14 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

17.15 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, stat_mode_to_string, utime

17.16 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, stat_mode_to_string

17.17 stat_mode_to_string

Synopsis

Format the file type code and access permission bits as a string

Usage

String_Type stat_mode_to_string (Int_Type st_mode)

Description

The stat_mode_to_string function returns a 10 characters string that indicates the type and permissions of a file as represented by the st_mode parameter. The returned string consists of the following characters:

     "s"      (socket)
     "p"      (fifo)
     "b"      (block device)
     "c"      (character device)
     "-"      (regular file)
     "l"      (link)
     "d"      (dir)
The access permission bit is one of the following characters:
     "s"      (set-user-id)
     "w"      (writable)
     "x"      (executable)
     "r"      (readable)

Notes

This function is an slsh intrinsic. As such, it is not part of S-Lang proper.

See Also

stat_file, lstat_file, stat_is

17.18 symlink

Synopsis

Create a symbolic link

Usage

Int_Type 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, hardlink

17.19 utime

Synopsis

Change a file's last access and modification times

Usage

Int_Type utime(String_Type file, Double_Type actime, Double_Type modtime)

Description

This function may be used to change the last access (actime) and last modification (modtime) times associated with the specified file. If sucessful, the function returns 0; otherwise it returns -1 and sets errno accordingly.

Notes

The utime function will call the C library utimes function if available, which permits microsecond accuracy. Otherwise, it will truncate the time arguments to integers and call the utime function.

See Also

stat_file


Next Previous Contents