<!-- This HTML file has been created by texi2html 1.27
     from library.texinfo on 3 March 1994 -->

<TITLE>The GNU C Library - File System Interface</TITLE>
<P>Go to the <A HREF="library_12.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html">previous</A>, <A HREF="library_14.html" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_14.html">next</A> section.<P>
<H1><A NAME="SEC187" HREF="library_toc.html#SEC187" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC187">File System Interface</A></H1>
<P>
This chapter describes the GNU C library's functions for manipulating
files.  Unlike the input and output functions described in
section <A HREF="library_11.html#SEC117" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC117">Input/Output on Streams</A> and section <A HREF="library_12.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC171">Low-Level Input/Output</A>, these
functions are concerned with operating on the files themselves, rather
than on their contents.
<P>
Among the facilities described in this chapter are functions for
examining or modifying directories, functions for renaming and deleting
files, and functions for examining and setting file attributes such as
access permissions and modification times.
<P>
<H2><A NAME="SEC188" HREF="library_toc.html#SEC188" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC188">Working Directory</A></H2>
<A NAME="IDX724"></A>
<A NAME="IDX725"></A>
<A NAME="IDX726"></A>
<P>
Each process has associated with it a directory, called its <DFN>current
working directory</DFN> or simply <DFN>working directory</DFN>, that is used in
the resolution of relative file names (see section <A HREF="library_10.html#SEC114" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC114">File Name Resolution</A>).
<P>
When you log in and begin a new session, your working directory is
initially set to the home directory associated with your login account
in the system user database.  You can find any user's home directory
using the <CODE>getpwuid</CODE> or <CODE>getpwnam</CODE> functions; see section <A HREF="library_25.html#SEC441" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_25.html#SEC441">User Database</A>.
<P>
Users can change the working directory using shell commands like
<CODE>cd</CODE>.  The functions described in this section are the primitives
used by those commands and by other programs for examining and changing
the working directory.
<A NAME="IDX727"></A>
<P>
Prototypes for these functions are declared in the header file
<TT>`unistd.h'</TT>.
<A NAME="IDX728"></A>
<P>
<A NAME="IDX729"></A>
<U>Function:</U> char * <B>getcwd</B> <I>(char *<VAR>buffer</VAR>, size_t <VAR>size</VAR>)</I><P>
The <CODE>getcwd</CODE> function returns an absolute file name representing
the current working directory, storing it in the character array
<VAR>buffer</VAR> that you provide.  The <VAR>size</VAR> argument is how you tell
the system the allocation size of <VAR>buffer</VAR>.
<P>
The GNU library version of this function also permits you to specify a
null pointer for the <VAR>buffer</VAR> argument.  Then <CODE>getcwd</CODE>
allocates a buffer automatically, as with <CODE>malloc</CODE>
(see section <A HREF="library_3.html#SEC21" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC21">Unconstrained Allocation</A>).  If the <VAR>size</VAR> is greater than
zero, then the buffer is that large; otherwise, the buffer is as large
as necessary to hold the result.
<P>
The return value is <VAR>buffer</VAR> on success and a null pointer on failure.
The following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EINVAL</CODE>
<DD>The <VAR>size</VAR> argument is zero and <VAR>buffer</VAR> is not a null pointer.
<P>
<DT><CODE>ERANGE</CODE>
<DD>The <VAR>size</VAR> argument is less than the length of the working directory
name.  You need to allocate a bigger array and try again.
<P>
<DT><CODE>EACCES</CODE>
<DD>Permission to read or search a component of the file name was denied.
</DL>
<P>
Here is an example showing how you could implement the behavior of GNU's
<CODE>getcwd (NULL, 0)</CODE> using only the standard behavior of
<CODE>getcwd</CODE>:
<P>
<PRE>
char *
gnu_getcwd ()
{
  int size = 100;
  char *buffer = (char *) xmalloc (size);

  while (1)
    {
      char *value = getcwd (buffer, size);
      if (value != 0)
        return buffer;
      size *= 2;
      free (buffer);
      buffer = (char *) xmalloc (size);
    }
}
</PRE>
<P>
See section <A HREF="library_3.html#SEC23" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_3.html#SEC23">Examples of <CODE>malloc</CODE></A>, for information about <CODE>xmalloc</CODE>, which is
not a library function but is a customary name used in most GNU
software.
<P>
<A NAME="IDX730"></A>
<U>Function:</U> char * <B>getwd</B> <I>(char *<VAR>buffer</VAR>)</I><P>
This is similar to <CODE>getcwd</CODE>.  The GNU library provides <CODE>getwd</CODE>
for backwards compatibility with BSD.  The <VAR>buffer</VAR> should be a
pointer to an array at least <CODE>PATH_MAX</CODE> bytes long.
<P>
<A NAME="IDX731"></A>
<U>Function:</U> int <B>chdir</B> <I>(const char *<VAR>filename</VAR>)</I><P>
This function is used to set the process's working directory to
<VAR>filename</VAR>.
<P>
The normal, successful return value from <CODE>chdir</CODE> is <CODE>0</CODE>.  A
value of <CODE>-1</CODE> is returned to indicate an error.  The <CODE>errno</CODE>
error conditions defined for this function are the usual file name
syntax errors (see section <A HREF="library_10.html#SEC115" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC115">File Name Errors</A>), plus <CODE>ENOTDIR</CODE> if the
file <VAR>filename</VAR> is not a directory.
<P>
<A NAME="IDX732"></A>
<A NAME="IDX733"></A>
<A NAME="IDX734"></A>
<H2><A NAME="SEC189" HREF="library_toc.html#SEC189" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC189">Accessing Directories</A></H2>
<P>
The facilities described in this section let you read the contents of a
directory file.  This is useful if you want your program to list all the
files in a directory, perhaps as part of a menu.
<A NAME="IDX735"></A>
<P>
The <CODE>opendir</CODE> function opens a <DFN>directory stream</DFN> whose
elements are directory entries.  You use the <CODE>readdir</CODE> function on
the directory stream to retrieve these entries, represented as
<CODE>struct dirent</CODE> objects.  The name of the file for each entry is
stored in the <CODE>d_name</CODE> member of this structure.  There are obvious
parallels here to the stream facilities for ordinary files, described in
section <A HREF="library_11.html#SEC117" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_11.html#SEC117">Input/Output on Streams</A>.
<P>
<H3><A NAME="SEC190" HREF="library_toc.html#SEC190" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC190">Format of a Directory Entry</A></H3>
<A NAME="IDX736"></A>
<P>
This section describes what you find in a single directory entry, as you
might obtain it from a directory stream.  All the symbols are declared
in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX737"></A>
<U>Data Type:</U> <B>struct dirent</B><P>
This is a structure type used to return information about directory
entries.  It contains the following fields:
<P>
<DL COMPACT>
<DT><CODE>char *d_name</CODE>
<DD>This is the null-terminated file name component.  This is the only
field you can count on in all POSIX systems.
<P>
<DT><CODE>ino_t d_fileno</CODE>
<DD>This is the file serial number.  For BSD compatibility, you can also
refer to this member as <CODE>d_ino</CODE>.
<P>
<DT><CODE>size_t d_namlen</CODE>
<DD>This is the length of the file name, not including the terminating null
character.
</DL>
<P>
This structure may contain additional members in the future.
<P>
When a file has multiple names, each name has its own directory entry.
The only way you can tell that the directory entries belong to a
single file is that they have the same value for the <CODE>d_fileno</CODE>
field.
<P>
File attributes such as size, modification times, and the like are part
of the file itself, not any particular directory entry.  See section <A HREF="library_13.html#SEC200" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_13.html#SEC200">File Attributes</A>.
<P>
<H3><A NAME="SEC191" HREF="library_toc.html#SEC191" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC191">Opening a Directory Stream</A></H3>
<A NAME="IDX738"></A>
<P>
This section describes how to open a directory stream.  All the symbols
are declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX739"></A>
<U>Data Type:</U> <B>DIR</B><P>
The <CODE>DIR</CODE> data type represents a directory stream.  
<P>
You shouldn't ever allocate objects of the <CODE>struct dirent</CODE> or
<CODE>DIR</CODE> data types, since the directory access functions do that for
you.  Instead, you refer to these objects using the pointers returned by
the following functions.
<P>
<A NAME="IDX740"></A>
<U>Function:</U> DIR * <B>opendir</B> <I>(const char *<VAR>dirname</VAR>)</I><P>
The <CODE>opendir</CODE> function opens and returns a directory stream for
reading the directory whose file name is <VAR>dirname</VAR>.  The stream has
type <CODE>DIR *</CODE>.
<P>
If unsuccessful, <CODE>opendir</CODE> returns a null pointer.  In addition to
the usual file name syntax errors (see section <A HREF="library_10.html#SEC115" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC115">File Name Errors</A>), the
following <CODE>errno</CODE> error conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EACCES</CODE>
<DD>Read permission is denied for the directory named by <CODE>dirname</CODE>.
<P>
<DT><CODE>EMFILE</CODE>
<DD>The process has too many files open.
<P>
<DT><CODE>ENFILE</CODE>
<DD>The entire system, or perhaps the file system which contains the
directory, cannot support any additional open files at the moment.
(This problem cannot happen on the GNU system.)
</DL>
<P>
The <CODE>DIR</CODE> type is typically implemented using a file descriptor,
and the <CODE>opendir</CODE> function in terms of the <CODE>open</CODE> function.
See section <A HREF="library_12.html#SEC171" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_12.html#SEC171">Low-Level Input/Output</A>.  Directory streams and the underlying
file descriptors are closed on <CODE>exec</CODE> (see section <A HREF="library_23.html#SEC406" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_23.html#SEC406">Executing a File</A>).
<P>
<H3><A NAME="SEC192" HREF="library_toc.html#SEC192" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC192">Reading and Closing a Directory Stream</A></H3>
<A NAME="IDX741"></A>
<P>
This section describes how to read directory entries from a directory
stream, and how to close the stream when you are done with it.  All the
symbols are declared in the header file <TT>`dirent.h'</TT>.
<P>
<A NAME="IDX742"></A>
<U>Function:</U> struct dirent * <B>readdir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
This function reads the next entry from the directory.  It normally
returns a pointer to a structure containing information about the file.
This structure is statically allocated and can be rewritten by a
subsequent call.
<P>
<STRONG>Portability Note:</STRONG> On some systems, <CODE>readdir</CODE> may not
return entries for <TT>`.'</TT> and <TT>`..'</TT>.  See section <A HREF="library_10.html#SEC114" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_10.html#SEC114">File Name Resolution</A>.
<P>
If there are no more entries in the directory or an error is detected,
<CODE>readdir</CODE> returns a null pointer.  The following <CODE>errno</CODE> error
conditions are defined for this function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>dirstream</VAR> argument is not valid.
</DL>
<P>
<A NAME="IDX743"></A>
<U>Function:</U> int <B>closedir</B> <I>(DIR *<VAR>dirstream</VAR>)</I><P>
This function closes the directory stream <VAR>dirstream</VAR>.  It returns
<CODE>0</CODE> on success and <CODE>-1</CODE> on failure.  
<P>
The following <CODE>errno</CODE> error conditions are defined for this
function:
<P>
<DL COMPACT>
<DT><CODE>EBADF</CODE>
<DD>The <VAR>dirstream</VAR> argument is not valid.
</DL>
<P>
<H3><A NAME="SEC193" HREF="library_toc.html#SEC193" tppabs="http://www.cs.utah.edu/dept/old/texinfo/glibc-manual-0.02/library_toc.html#SEC193">Simple Program to List a Directory</A></H3>
<P>
Here's a simple program that prints the names of the files in
the current working directory:
<P>
<PRE>
#include &#60;stddef.h&#62;
#include &#60;stdio.h&#62;
#include &#60;sys/types.h&#62;
#include &#60;dirent.h&#62;

int
main (void)
{
  DIR *dp;
  struct dirent *ep;

  dp = opendir ("./");
  if (dp != NULL)
    {
      while (ep = readdir (dp))
	puts (ep-&#62;d_name);
      (void) closedir (dp);