readdir(3ucb) [opensolaris man page]

readdir(3UCB)					     SunOS/BSD Compatibility Library Functions					     readdir(3UCB)

NAME

       readdir - read a directory entry

SYNOPSIS

       /usr/ucb/cc [ flag ... ] file ...
       #include <sys/types.h>
       #include <sys/dir.h>

       struct direct *readdir(dirp)
       DIR *dirp;

DESCRIPTION

       The readdir() function returns a pointer to a structure representing the directory entry at the current position in the directory stream to
       which dirp refers, and positions the directory stream at the next entry, except on read-only file systems. It returns a NULL  pointer  upon
       reaching  the end of the directory stream, or upon detecting an invalid location in the directory.  The readdir() function shall not return
       directory entries containing empty names.  It is unspecified whether entries are returned   for	dot  (.)  or  dot-dot  (..).  The  pointer
       returned by readdir() points to data that may be overwritten by another call to readdir() on the same directory stream. This data shall not
       be  overwritten by another call to  readdir() on a different directory stream. The readdir() function may buffer several directory  entries
       per  actual  read operation.  The readdir() function marks for update the  st_atime field of the directory each time the directory is actu-
       ally read.

RETURN VALUES

       The readdir() function returns NULL on failure and sets	errno to indicate the error.

ERRORS

       The readdir() function will fail if one or more of the following are true:

       EAGAIN	    Mandatory file/record locking was set, O_NDELAY or O_NONBLOCK was set, and there was a blocking record lock.

       EAGAIN	    Total amount of system memory available when reading using raw I/O is temporarily insufficient.

       EAGAIN	    No data is waiting to be read on a file associated with a tty device and  O_NONBLOCK was set.

       EAGAIN	    No message is waiting to be read on a stream and  O_NDELAY or  O_NONBLOCK was set.

       EBADF	    The file descriptor determined by the DIR stream is no longer valid. This results if the DIR stream has been closed.

       EBADMSG	    Message waiting to be read on a stream is not a data message.

       EDEADLK	    The read() was going to go to sleep and cause a deadlock to occur.

       EFAULT	    buf points to an illegal address.

       EINTR	    A signal was caught during the read() or readv() function.

       EINVAL	    Attempted to read from a stream linked to a multiplexor.

       EIO	    A physical I/O error has occurred, or the process is in a background process group and is attempting to read from its control-
		    ling  terminal,  and  either  the  process	is  ignoring or blocking the SIGTTIN signal or the process group of the process is
		    orphaned.

       ENOENT	    The current file pointer for the directory is not located at a valid entry.

       ENOLCK	    The system record lock table was full, so the read() or readv() could not go to sleep  until  the  blocking  record  lock  was
		    removed.

       ENOLINK	    fildes is on a remote machine and the link to that machine is no longer active.

       ENXIO	    The  device  associated  with  fildes is a block special or character special file and the value of the file pointer is out of
		    range.

       EOVERFLOW    The value of the direct structure member d_ino cannot be represented in an ino_t.

USAGE

       The readdir() function has a transitional interface for 64-bit file offsets. See lf64(5).

SEE ALSO

       cc(1B), getdents(2), readdir(3C), scandir(3UCB), lf64(5)

NOTES

       Use of these interfaces should be restricted to only applications written on  BSD platforms.  Use of these interfaces with any of the  sys-
       tem libraries or in multi-thread applications is unsupported.

SunOS 5.11							    30 Oct 2007 						     readdir(3UCB)

Check Out this Related Man Page

DIRECTORY(3)						     Library Functions Manual						      DIRECTORY(3)

NAME

       opendir, readdir, telldir, seekdir, rewinddir, closedir - directory operations

SYNOPSIS

       #include <sys/types.h>
       #include <sys/dir.h>

       DIR *opendir(filename)
       char *filename;

       struct direct *readdir(dirp)
       DIR *dirp;

       long telldir(dirp)
       DIR *dirp;

       seekdir(dirp, loc)
       DIR *dirp;
       long loc;

       rewinddir(dirp)
       DIR *dirp;

       closedir(dirp)
       DIR *dirp;

DESCRIPTION

       Opendir	opens the directory named by filename and associates a directory stream with it.  Opendir returns a pointer to be used to identify
       the directory stream in subsequent operations.  The pointer NULL is returned if filename cannot be accessed,  or  if  it  cannot  malloc(3)
       enough memory to hold the whole thing.

       Readdir	returns  a  pointer  to  the next directory entry.  It returns NULL upon reaching the end of the directory or detecting an invalid
       seekdir operation.

       Telldir returns the current location associated with the named directory stream.

       Seekdir sets the position of the next readdir operation on the directory stream.  The new position reverts to the one associated  with  the
       directory  stream  when	the telldir operation was performed.  Values returned by telldir are good only for the lifetime of the DIR pointer
       from which they are derived.  If the directory is closed and then reopened, the telldir value may be invalidated due to	undetected  direc-
       tory compaction.  It is safe to use a previous telldir value immediately after a call to opendir and before any calls to readdir.

       Rewinddir resets the position of the named directory stream to the beginning of the directory.

       Closedir closes the named directory stream and frees the structure associated with the DIR pointer.

       Sample code which searchs a directory for entry ``name'' is:

	    len = strlen(name);
	    dirp = opendir(".");
	    for (dp = readdir(dirp); dp != NULL; dp = readdir(dirp))
		 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) {
		      closedir(dirp);
		      return FOUND;
		 }
	    closedir(dirp);
	    return NOT_FOUND;

SEE ALSO

       open(2), close(2), read(2), lseek(2), dir(5)

4.2 Berkeley Distribution					September 24, 1985						      DIRECTORY(3)

Linux and UNIX Man Pages

readdir(3ucb) [opensolaris man page]

Check Out this Related Man Page