'\" te
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
.\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH READDIR 3UCB "Oct 30, 2007"
.SH NAME
readdir \- read a directory entry
.SH SYNOPSIS
.LP
.nf
\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
#include <sys/types.h>
#include <sys/dir.h>

\fBstruct direct *\fR\fBreaddir\fR(\fIdirp\fR)
\fBDIR *\fR\fIdirp\fR;
.fi

.SH DESCRIPTION
.sp
.LP
The \fBreaddir()\fR function returns a pointer to a structure representing the
directory entry at the current position in the directory stream to which
\fIdirp\fR refers, and positions the directory stream at the next entry, except
on read-only file systems. It returns a \fINULL\fR pointer upon reaching the
end of the directory stream, or upon detecting an invalid location in the
directory.  The \fBreaddir()\fR function shall not return directory entries
containing empty names.  It is unspecified whether entries are returned  for
dot \fB(\fR.\fB)\fR or dot-dot \fB(\fR.\|.\fB)\fR. The pointer returned by
\fBreaddir()\fR points to data that may be overwritten by another call to
\fBreaddir()\fR on the same directory stream. This data shall not be
overwritten by another call to  \fBreaddir()\fR on a different directory
stream. The \fBreaddir()\fR function may buffer several directory entries per
actual read operation. The \fBreaddir()\fR function marks for update the
\fIst_atime\fR field of the directory each time the directory is actually read.
.SH RETURN VALUES
.sp
.LP
The \fBreaddir()\fR function returns \fINULL\fR on failure and sets \fBerrno\fR
to indicate the error.
.SH ERRORS
.sp
.LP
The \fBreaddir()\fR function will fail if one or more of the following are
true:
.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
Mandatory file/record locking was set, \fBO_NDELAY\fR or \fBO_NONBLOCK\fR was
set, and there was a blocking record lock.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
Total amount of system memory available when reading using raw I/O is
temporarily insufficient.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
No data is waiting to be read on a file associated with a tty device and
\fBO_NONBLOCK\fR was set.
.RE

.sp
.ne 2
.na
\fB\fBEAGAIN\fR\fR
.ad
.RS 13n
No message is waiting to be read on a stream and  \fBO_NDELAY\fR or
\fBO_NONBLOCK\fR was set.
.RE

.sp
.ne 2
.na
\fB\fBEBADF\fR\fR
.ad
.RS 13n
The file descriptor determined by the \fBDIR\fR stream is no longer valid. This
results if the \fBDIR\fR stream has been closed.
.RE

.sp
.ne 2
.na
\fB\fBEBADMSG\fR\fR
.ad
.RS 13n
Message waiting to be read on a stream is not a data message.
.RE

.sp
.ne 2
.na
\fB\fBEDEADLK\fR\fR
.ad
.RS 13n
The \fBread()\fR was going to go to sleep and cause a deadlock to occur.
.RE

.sp
.ne 2
.na
\fB\fBEFAULT\fR\fR
.ad
.RS 13n
\fIbuf\fR points to an illegal address.
.RE

.sp
.ne 2
.na
\fB\fBEINTR\fR\fR
.ad
.RS 13n
A signal was caught during the \fBread()\fR or \fBreadv()\fR function.
.RE

.sp
.ne 2
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 13n
Attempted to read from a stream linked to a multiplexor.
.RE

.sp
.ne 2
.na
\fB\fBEIO\fR\fR
.ad
.RS 13n
A physical I/O error has occurred, or the process is in a background process
group and is attempting to read from its controlling terminal, and either the
process is ignoring or blocking the \fBSIGTTIN\fR signal or the process group
of the process is orphaned.
.RE

.sp
.ne 2
.na
\fB\fBENOENT\fR\fR
.ad
.RS 13n
The current file pointer for the directory is not located at a valid entry.
.RE

.sp
.ne 2
.na
\fB\fBENOLCK\fR\fR
.ad
.RS 13n
The system record lock table was full, so the \fBread()\fR or \fBreadv()\fR
could not go to sleep until the blocking record lock was removed.
.RE

.sp
.ne 2
.na
\fB\fBENOLINK\fR\fR
.ad
.RS 13n
\fIfildes\fR is on a remote machine and the link to that machine is no longer
active.
.RE

.sp
.ne 2
.na
\fB\fBENXIO\fR\fR
.ad
.RS 13n
The device associated with  \fIfildes\fR is a block special or character
special file and the value of the file pointer is out of range.
.RE

.sp
.ne 2
.na
\fB\fBEOVERFLOW\fR\fR
.ad
.RS 13n
The value of the \fBdirect\fR structure member \fBd_ino\fR cannot be
represented in an \fBino_t\fR.
.RE

.SH USAGE
.sp
.LP
The \fBreaddir()\fR function has a transitional interface for 64-bit file
offsets. See \fBlf64\fR(5).
.SH SEE ALSO
.sp
.LP
\fBgetdents\fR(2), \fBreaddir\fR(3C), \fBscandir\fR(3UCB), \fBlf64\fR(5)
.SH NOTES
.sp
.LP
Use of these interfaces should be restricted to only applications written on
\fBBSD\fR platforms.  Use of these interfaces with any of the system libraries
or in multi-thread applications is unsupported.