\function{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 \exmp{mode} parameter determines the type of desired access. Its value is given by the bitwise-or of one or more of the following constants: #v+ R_OK Check for read permission W_OK Check for write permission X_OK Check for execute permission F_OK Check for existence #v- The function will return 0 if process has the requested access permissions to the file, otherwise it will return -1 and set \ivar{errno} accordingly. Access to a file depends 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. \seealso{stat_file} \done \function{chdir} \synopsis{Change the current working directory} \usage{Int_Type chdir (String_Type dir)} \description The \ifun{chdir} function may be used to change the current working directory to the directory specified by \exmp{dir}. Upon success it returns zero. Upon failure it returns \exmp{-1} and sets \ivar{errno} accordingly. \seealso{mkdir, stat_file} \done \function{chmod} \synopsis{Change the mode of a file} \usage{Int_Type chmod (String_Type file, Int_Type mode)} \description The \ifun{chmod} function changes the permissions of the specified file to those given by \exmp{mode}. It returns \exmp{0} upon success, or \exmp{-1} upon failure setting \ivar{errno} accordingly. See the system specific documentation for the C library function \ifun{chmod} for a discussion of the \exmp{mode} parameter. \seealso{chown, stat_file} \done \function{chown} \synopsis{Change the owner of a file} \usage{Int_Type chown (String_Type file, Int_Type uid, Int_Type gid)} \description The \ifun{chown} function is used to change the user-id and group-id of \exmp{file} to \exmp{uid} and \exmp{gid}, respectively. It returns 0 upon success and -1 upon failure, with \ivar{errno} set accordingly. \notes On most systems, only the superuser can change the ownership of a file. Some systems do not support this function. \seealso{lchown, chmod, stat_file} \done \function{getcwd} \synopsis{Get the current working directory} \usage{String_Type getcwd ()} \description The \ifun{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 \ivar{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. \seealso{mkdir, chdir, errno} \done \function{hardlink} \synopsis{Create a hard-link} \usage{Int_Type hardlink (String_Type oldpath, String_Type newpath)} \description The \ifun{hardlink} function creates a hard-link called \exmp{newpath} to the existing file \exmp{oldpath}. If the link was successfully created, the function will return 0. Upon error, the function returns -1 and sets \ivar{errno} accordingly. \notes Not all systems support the concept of a hard-link. \seealso{symlink} \done \function{lchown} \synopsis{Change the owner of a file} \usage{Int_Type lchown (String_Type file, Int_Type uid, Int_Type gid)} \description The \ifun{lchown} function is like \ifun{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 \ifun{chown} function for more details. \seealso{chown, chmod, stat_file} \done \function{listdir} \synopsis{Get a list of the files in a directory} \usage{String_Type[] listdir (String_Type dir)} \description The \ifun{listdir} function returns the directory listing of all the files in the specified directory \exmp{dir} as an array of strings. It does not return the special files \exmp{".."} and \exmp{"."} as part of the list. \seealso{stat_file, stat_is, length} \done \function{lstat_file} \synopsis{Get information about a symbolic link} \usage{Struct_Type lstat_file (String_Type file)} \description The \ifun{lstat_file} function behaves identically to \ifun{stat_file} but if \exmp{file} is a symbolic link, \ifun{lstat_file} returns information about the link itself, and not the file that it references. See the documentation for \ifun{stat_file} for more information. \notes On systems that do not support symbolic links, there is no difference between this function and the \ifun{stat_file} function. \seealso{stat_file, stat_is, stat_mode_to_string, readlink} \done \function{mkdir} \synopsis{Create a new directory} \usage{Int_Type mkdir (String_Type dir [,Int_Type mode])} \description The \ifun{mkdir} function creates a directory whose name is specified by the \exmp{dir} parameter with permissions given by the optional \exmp{mode} parameter. Upon success \ifun{mkdir} returns 0, or it returns \exmp{-1} upon failure setting \ivar{errno} accordingly. In particular, if the directory already exists, the function will fail and set errno to \icon{EEXIST}. \example The following function creates a new directory, if it does not already exist (indicated by \exmp{errno==EEXIST}). #v+ define my_mkdir (dir) { if (0 == mkdir (dir)) return; if (errno == EEXIST) return; throw IOError, sprintf ("mkdir %s failed: %s", dir, errno_string (errno)); } #v- \notes The \exmp{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. \seealso{rmdir, getcwd, chdir, fopen, errno} \done \function{readlink} \synopsis{String_Type readlink (String_Type path)} \usage{Get the value of a symbolic link} \description The \ifun{readlink} function returns the value of a symbolic link. Upon failure, \NULL is returned and \ivar{errno} set accordingly. \notes Not all systems support this function. \seealso{symlink, lstat_file, stat_file, stat_is} \done \function{remove} \synopsis{Delete a file} \usage{Int_Type remove (String_Type file)} \description The \ifun{remove} function deletes a file. It returns 0 upon success, or -1 upon error and sets \ivar{errno} accordingly. \seealso{rename, rmdir} \done \function{rename} \synopsis{Rename a file} \usage{Int_Type rename (String_Type old, String_Type new)} \description The \ifun{rename} function renames a file from \exmp{old} to \exmp{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 \ivar{errno} accordingly. \seealso{remove, errno} \done \function{rmdir} \synopsis{Remove a directory} \usage{Int_Type rmdir (String_Type dir)} \description The \ifun{rmdir} function deletes the specified directory. It returns 0 upon success or -1 upon error and sets \ivar{errno} accordingly. \notes The directory must be empty before it can be removed. \seealso{rename, remove, mkdir} \done \function{stat_file} \synopsis{Get information about a file} \usage{Struct_Type stat_file (String_Type file)} \description The \ifun{stat_file} function returns information about \exmp{file} through the use of the system \cfun{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: #v+ st_dev st_ino st_mode st_nlink st_uid st_gid st_rdev st_size st_atime st_mtime st_ctime #v- See the C library documentation of \cfun{stat} for a discussion of the meanings of these fields. \example The following example shows how the \ifun{stat_file} function may be used to get the size of a file: #v+ define file_size (file) { variable st; st = stat_file(file); if (st == NULL) throw IOError, "Unable to stat $file"$; return st.st_size; } #v- \seealso{lstat_file, stat_is, stat_mode_to_string, utime} \done \function{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 \ifun{stat_is} function returns a boolean value according to whether or not the \exmp{st_mode} parameter is of the specified type. Specifically, \exmp{type} must be one of the strings: #v+ "sock" (socket) "fifo" (fifo) "blk" (block device) "chr" (character device) "reg" (regular file) "lnk" (link) "dir" (dir) #v- It returns a non-zero value if \exmp{st_mode} corresponds to \exmp{type}. \example The following example illustrates how to use the \ifun{stat_is} function to determine whether or not a file is a directory: #v+ define is_directory (file) { variable st; st = stat_file (file); if (st == NULL) return 0; return stat_is ("dir", st.st_mode); } #v- \seealso{stat_file, lstat_file, stat_mode_to_string} \done \function{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 \ifun{stat_mode_to_string} function returns a 10 characters string that indicates the type and permissions of a file as represented by the \var{st_mode} parameter. The returned string consists of the following characters: #v+ "s" (socket) "p" (fifo) "b" (block device) "c" (character device) "-" (regular file) "l" (link) "d" (dir) #v- The access permission bit is one of the following characters: #v+ "s" (set-user-id) "w" (writable) "x" (executable) "r" (readable) #v- \notes This function is an \slsh intrinsic. As such, it is not part of \slang proper. \seealso{stat_file, lstat_file, stat_is} \done \function{symlink} \synopsis{Create a symbolic link} \usage{Int_Type symlink (String_Type oldpath, String_Type new_path)} \description The \ifun{symlink} function may be used to create a symbolic link named \exmp{new_path} for \exmp{oldpath}. If successful, the function returns 0, otherwise it returns -1 and sets \ivar{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. \seealso{readlink, hardlink} \done \function{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 successful, the function returns 0; otherwise it returns -1 and sets \ivar{errno} accordingly. \notes The \ifun{utime} function will call the C library \cfun{utimes} function if available, which permits microsecond accuracy. Otherwise, it will truncate the time arguments to integers and call the \cfun{utime} function. \seealso{stat_file} \done