<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META NAME="GENERATOR" CONTENT="SGML-Tools 1.0.9">
<TITLE> S-Lang Run-Time Library Reference: Version 1.4.0: Directory Functions</TITLE>
<LINK HREF="slangfun-13.html" REL=next>
<LINK HREF="slangfun-11.html" REL=previous>
<LINK HREF="slangfun.html#toc12" REL=contents>
</HEAD>
<BODY>
<A HREF="slangfun-13.html">Next</A>
<A HREF="slangfun-11.html">Previous</A>
<A HREF="slangfun.html#toc12">Contents</A>
<HR>
<H2><A NAME="s12">12. Directory Functions</A></H2>
<P>
<H2><A NAME="chdir"></A> <A NAME="ss12.1">12.1 <B>chdir</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Change the current working directory.
<DT><B> Usage </B><DD><P><CODE>Integer_Type chdir (String_Type dir)</CODE>
<DT><B> Description </B><DD><P>The <CODE>chdir</CODE> function may be used to changed the current working
directory to the directory specified by <CODE>dir</CODE>. Upon sucess it
returns zero; however, upon failure it returns <CODE>-1</CODE> and sets
<CODE>errno</CODE> accordingly.
<DT><B> See Also </B><DD><P><CODE>mkdir, stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="chmod"></A> <A NAME="ss12.2">12.2 <B>chmod</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Change the mode of a file
<DT><B> Usage </B><DD><P><CODE>Integer_Type chmod (String_Type file, Integer_Type mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>chmod</CODE> function changes the permissions of <CODE>file</CODE> to those
specified by <CODE>mode</CODE>. It returns <CODE>0</CODE> upon success, or
<CODE>-1</CODE> upon failure setting <CODE>errno</CODE> accordingly.
<P>See the system specific documentation for the C library
function <CODE>chmod</CODE> for a discussion of the <CODE>mode</CODE> parameter.
<DT><B> See Also </B><DD><P><CODE>chown, stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="chown"></A> <A NAME="ss12.3">12.3 <B>chown</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Change the owner of a file
<DT><B> Usage </B><DD><P><CODE>Integer_Type chown (String_Type file, Integer_Type uid, Integer_Type gid)</CODE>
<DT><B> Description </B><DD><P>The <CODE>chown</CODE> function is used to change the user-id and group-id of
<CODE>file</CODE> to <CODE>uid</CODE> and <CODE>gid</CODE>, respectively. It returns
<CODE>zero</CODE> upon success and <CODE>-1</CODE> upon failure, with <CODE>errno</CODE>
set accordingly.
<DT><B> Notes </B><DD><P>On most systems, only the super user can change the ownership of a
file.
<P>Some systems do not support this function.
<DT><B> See Also </B><DD><P><CODE>chmod, stat_file</CODE>
</DL>
<P>
<P>
<H2><A NAME="getcwd"></A> <A NAME="ss12.4">12.4 <B>getcwd</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get the current working directory
<DT><B> Usage </B><DD><P><CODE>String_Type getcwd ()</CODE>
<DT><B> Description </B><DD><P>The <CODE>getcwd</CODE> function returns the absolute pathname of the
current working directory. If an error occurs or it cannot
determine the working directory, it returns <CODE>NULL</CODE> and sets
<CODE>errno</CODE> accordingly.
<DT><B> Notes </B><DD><P>Under Unix, OS/2, and MSDOS, the pathname returned by this function
includes the trailing slash character. Some versions also include
the drive specifier.
<DT><B> See Also </B><DD><P><CODE>mkdir, chdir, errno</CODE>
</DL>
<P>
<P>
<H2><A NAME="listdir"></A> <A NAME="ss12.5">12.5 <B>listdir</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get a list of the files in a directory
<DT><B> Usage </B><DD><P><CODE>String_Type[] listdir (String_Type dir)</CODE>
<DT><B> Description </B><DD><P>The <CODE>listdir</CODE> function returns the directory listing of all the
files in the specified directory <CODE>dir</CODE> as an array of strings.
It does not return the special files <CODE>".."</CODE> and <CODE>"."</CODE> as
part of the list.
<DT><B> See Also </B><DD><P><CODE>stat_file, stat_is, length</CODE>
</DL>
<P>
<P>
<H2><A NAME="lstat_file"></A> <A NAME="ss12.6">12.6 <B>lstat_file</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get information about a symbolic link
<DT><B> Usage </B><DD><P><CODE>Struct_Type lstat_file (String_Type file)</CODE>
<DT><B> Description </B><DD><P>The <CODE>lstat_file</CODE> function behaves identically to <CODE>stat_file</CODE>
but if <CODE>file</CODE> is a symbolic link, <CODE>lstat_file</CODE> returns
information about the link itself, and not the file that it
references.
<P>See the documentation for <CODE>stat_file</CODE> for more information.
<DT><B> Notes </B><DD><P>On systems that do not support symbolic links, there is no
difference between this function and the <CODE>stat_file</CODE> function.
<DT><B> See Also </B><DD><P><CODE>stat_file, readlink</CODE>
</DL>
<P>
<P>
<H2><A NAME="mkdir"></A> <A NAME="ss12.7">12.7 <B>mkdir</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Create a new directory
<DT><B> Usage </B><DD><P><CODE>Integer_Type mkdir (String_Type dir, Integer_Type mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>mkdir</CODE> function creates a directory whose name is specified
by the <CODE>dir</CODE> parameter with permissions specified by <CODE>mode</CODE>.
Upon success <CODE>mkdir</CODE> returns zero, or it returns <CODE>-1</CODE> and
sets <CODE>errno</CODE> accordingly. In particular, if the directory
already exists, the function will fail and set errno to
<CODE>EEXIST</CODE>.
<DT><B> Example </B><DD><P>
<BLOCKQUOTE><CODE>
<PRE>
define my_mkdir (dir)
{
if (0 == mkdir (dir, 0777)) return;
if (errno == EEXIST) return;
verror ("mkdir %s failed: %s", dir, errno_string (errno));
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> Notes </B><DD><P>The <CODE>mode</CODE> 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.
<DT><B> See Also </B><DD><P><CODE>rmdir, getcwd, chdir, fopen, errno</CODE>
</DL>
<P>
<P>
<H2><A NAME="readlink"></A> <A NAME="ss12.8">12.8 <B>readlink</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>String_Type readlink (String_Type path)
<DT><B> Usage </B><DD><P><CODE>Get the value of a symbolic link</CODE>
<DT><B> Description </B><DD><P>The <CODE>readlink</CODE> function returns the value of a symbolic link and
returns it as a string. Upon failure, <CODE>NULL</CODE> is returned and
<CODE>errno</CODE> set accordingly.
<DT><B> Notes </B><DD><P>Not all systems support this function.
<DT><B> See Also </B><DD><P><CODE>lstat_file, stat_file, stat_is</CODE>
</DL>
<P>
<P>
<H2><A NAME="remove"></A> <A NAME="ss12.9">12.9 <B>remove</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Delete a file
<DT><B> Usage </B><DD><P><CODE>Integer_Type remove (String_Type file)</CODE>
<DT><B> Description </B><DD><P>The <CODE>remove</CODE> function deletes a file. It returns <CODE>0</CODE> upon
success, or <CODE>-1</CODE> upon error and sets <CODE>errno</CODE> accordingly.
<DT><B> See Also </B><DD><P><CODE>rename, rmdir</CODE>
</DL>
<P>
<P>
<H2><A NAME="rename"></A> <A NAME="ss12.10">12.10 <B>rename</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Rename a file
<DT><B> Usage </B><DD><P><CODE>Integer_Type rename (String_Type old, String_Type new)</CODE>
<DT><B> Description </B><DD><P>The <CODE>rename</CODE> function renames a file from <CODE>old</CODE> to <CODE>new</CODE>
moving it between directories if necessary. This function may fail
if the directories do not refer to the same file system. It returns
<CODE>0</CODE> upon success, or <CODE>-1</CODE> upon error and sets <CODE>errno</CODE> accordingly.
<DT><B> See Also </B><DD><P><CODE>remove, errno</CODE>
</DL>
<P>
<P>
<H2><A NAME="rmdir"></A> <A NAME="ss12.11">12.11 <B>rmdir</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Remove a directory
<DT><B> Usage </B><DD><P><CODE>Integer_Type rmdir (String_Type dir)</CODE>
<DT><B> Description </B><DD><P>The <CODE>rmdir</CODE> function deletes a specified directory. It returns
<CODE>0</CODE> upon success or <CODE>-1</CODE> upon error and sets <CODE>errno</CODE> accordingly.
<DT><B> Notes </B><DD><P>The directory must be empty before it can be removed.
<DT><B> See Also </B><DD><P><CODE>rename, remove, mkdir</CODE>
</DL>
<P>
<P>
<H2><A NAME="stat_file"></A> <A NAME="ss12.12">12.12 <B>stat_file</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Get information about a file
<DT><B> Usage </B><DD><P><CODE>Struct_Type stat_file (String_Type file)</CODE>
<DT><B> Description </B><DD><P>The <CODE>stat_file</CODE> function returns information about <CODE>file</CODE>
through the use of the system <CODE>stat</CODE> call. If the stat call
fails, the function returns <CODE>NULL</CODE> and sets errno accordingly.
If it is successful, it returns a stat structure with the following
integer fields:
<BLOCKQUOTE><CODE>
<PRE>
st_dev
st_ino
st_mode
st_nlink
st_uid
st_gid
st_rdev
st_size
st_atime
st_mtime
st_ctime
</PRE>
</CODE></BLOCKQUOTE>
See the man page for <CODE>stat</CODE> for a discussion of these fields.
<DT><B> Example </B><DD><P>The following example shows how the <CODE>stat_file</CODE> function may be
used to get the size of a file:
<BLOCKQUOTE><CODE>
<PRE>
define file_size (file)
{
variable st;
st = stat_file(file);
if (st == NULL) verror ("Unable to stat %s", file);
return st.st_size;
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>lstat_file, stat_is</CODE>
</DL>
<P>
<P>
<H2><A NAME="stat_is"></A> <A NAME="ss12.13">12.13 <B>stat_is</B></A>
</H2>
<P>
<DL>
<DT><B> Synopsis </B><DD><P>Parse the <CODE>st_mode</CODE> field of a stat structure
<DT><B> Usage </B><DD><P><CODE>Char_Type stat_is (String_Type type, Integer_Type st_mode)</CODE>
<DT><B> Description </B><DD><P>The <CODE>stat_is</CODE> function returns a signed character value about
the type of file specified by <CODE>st_mode</CODE>. Specifically,
<CODE>type</CODE> must be one of the strings:
<BLOCKQUOTE><CODE>
<PRE>
"sock" (socket)
"fifo" (fifo)
"blk" (block device)
"chr" (character device)
"reg" (regular file)
"lnk" (link)
"dir" (dir)
</PRE>
</CODE></BLOCKQUOTE>
It returns a non-zero value if <CODE>st_mode</CODE> corresponds to
<CODE>type</CODE>.
<DT><B> Example </B><DD><P>The following example illustrates how to use the <CODE>stat_is</CODE>
function to determine whether or not a file is a directory:
<BLOCKQUOTE><CODE>
<PRE>
define is_directory (file)
{
variable st;
st = stat_file (file);
if (st == NULL) return 0;
return stat_is ("dir", st.st_mode);
}
</PRE>
</CODE></BLOCKQUOTE>
<DT><B> See Also </B><DD><P><CODE>stat_file, lstat_file</CODE>
</DL>
<P>
<P>
<P>
<HR>
<A HREF="slangfun-13.html">Next</A>
<A HREF="slangfun-11.html">Previous</A>
<A HREF="slangfun.html#toc12">Contents</A>
</BODY>
</HTML>
