diff options
Diffstat (limited to 'libslang/doc/tm/rtl/dir.tm')
| -rw-r--r-- | libslang/doc/tm/rtl/dir.tm | 223 |
1 files changed, 223 insertions, 0 deletions
diff --git a/libslang/doc/tm/rtl/dir.tm b/libslang/doc/tm/rtl/dir.tm new file mode 100644 index 0000000..a25fc86 --- /dev/null +++ b/libslang/doc/tm/rtl/dir.tm @@ -0,0 +1,223 @@ +\function{chdir} +\synopsis{Change the current working directory.} +\usage{Integer_Type chdir (String_Type dir)} +\description + The \var{chdir} function may be used to changed the current working + directory to the directory specified by \var{dir}. Upon success it + returns zero; however, upon failure it returns \exmp{-1} and sets + \var{errno} accordingly. +\seealso{mkdir, stat_file} +\done + +\function{chmod} +\synopsis{Change the mode of a file} +\usage{Integer_Type chmod (String_Type file, Integer_Type mode)} +\description + The \var{chmod} function changes the permissions of \var{file} to those + specified by \var{mode}. It returns \exmp{0} upon success, or + \exmp{-1} upon failure setting \var{errno} accordingly. + + See the system specific documentation for the C library + function \var{chmod} for a discussion of the \var{mode} parameter. +\seealso{chown, stat_file} +\done + +\function{chown} +\synopsis{Change the owner of a file} +\usage{Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid)} +\description + The \var{chown} function is used to change the user-id and group-id of + \var{file} to \var{uid} and \var{gid}, respectively. It returns + \var{zero} upon success and \exmp{-1} upon failure, with \var{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. +\seealso{chmod, stat_file} +\done + +\function{getcwd} +\synopsis{Get the current working directory} +\usage{String_Type getcwd ()} +\description + The \var{getcwd} function returns the absolute pathname of the + current working directory. If an error occurs or it cannot + determine the working directory, it returns \var{NULL} and sets + \var{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. +\seealso{mkdir, chdir, errno} +\done + +\function{listdir} +\synopsis{Get a list of the files in a directory} +\usage{String_Type[] listdir (String_Type dir)} +\description + The \var{listdir} function returns the directory listing of all the + files in the specified directory \var{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 \var{lstat_file} function behaves identically to \var{stat_file} + but if \var{file} is a symbolic link, \var{lstat_file} returns + information about the link itself, and not the file that it + references. + + See the documentation for \var{stat_file} for more information. +\notes + On systems that do not support symbolic links, there is no + difference between this function and the \var{stat_file} function. +\seealso{stat_file, readlink} +\done + +\function{mkdir} +\synopsis{Create a new directory} +\usage{Integer_Type mkdir (String_Type dir, Integer_Type mode)} +\description + The \var{mkdir} function creates a directory whose name is specified + by the \var{dir} parameter with permissions specified by \var{mode}. + Upon success \var{mkdir} returns zero, or it returns \exmp{-1} and + sets \var{errno} accordingly. In particular, if the directory + already exists, the function will fail and set errno to + \var{EEXIST}. +\example +#v+ + define my_mkdir (dir) + { + if (0 == mkdir (dir, 0777)) return; + if (errno == EEXIST) return; + verror ("mkdir %s failed: %s", dir, errno_string (errno)); + } +#v- +\notes + The \var{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 \var{readlink} function returns the value of a symbolic link and + returns it as a string. Upon failure, \NULL is returned and + \var{errno} set accordingly. +\notes + Not all systems support this function. +\seealso{lstat_file, stat_file, stat_is} +\done + +\function{remove} +\synopsis{Delete a file} +\usage{Integer_Type remove (String_Type file)} +\description + The \var{remove} function deletes a file. It returns \0 upon + success, or \-1 upon error and sets \var{errno} accordingly. +\seealso{rename, rmdir} +\done + +\function{rename} +\synopsis{Rename a file} +\usage{Integer_Type rename (String_Type old, String_Type new)} +\description + The \var{rename} function renames a file from \var{old} to \var{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 \var{errno} accordingly. +\seealso{remove, errno} +\done + +\function{rmdir} +\synopsis{Remove a directory} +\usage{Integer_Type rmdir (String_Type dir)} +\description + The \var{rmdir} function deletes a specified directory. It returns + \0 upon success or \-1 upon error and sets \var{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 \var{stat_file} function returns information about \var{file} + through the use of the system \var{stat} call. If the stat call + fails, the function returns \var{NULL} and sets errno accordingly. + If it is successful, it returns a stat structure with the following + integer 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 man page for \var{stat} for a discussion of these fields. +\example + The following example shows how the \var{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) verror ("Unable to stat %s", file); + return st.st_size; + } +#v- +\seealso{lstat_file, stat_is} +\done + +\function{stat_is} +\synopsis{Parse the \var{st_mode} field of a stat structure} +\usage{Char_Type stat_is (String_Type type, Integer_Type st_mode)} +\description + The \var{stat_is} function returns a signed character value about + the type of file specified by \var{st_mode}. Specifically, + \var{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 \var{st_mode} corresponds to + \var{type}. +\example + The following example illustrates how to use the \var{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} +\done + |