13579 readdir(3C) and closedir(3C) should document dirent lifetime

Reviewed by: Peter Tribble <peter.tribble@gmail.com>
Reviewed by: Andy Fiddaman <andy@omniosce.org>
Approved by: Dan McDonald <danmcd@joyent.com>

3 files changed, 582 insertions, 479 deletions

diff --git a/usr/src/man/man3c/closedir.3c b/usr/src/man/man3c/closedir.3c
index 09e7d3e3f7..c88ecd707c 100644
--- a/usr/src/man/man3c/closedir.3c
+++ b/usr/src/man/man3c/closedir.3c
@@ -43,72 +43,79 @@
 .\" Copyright 1989 AT&T
 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
 .\" Copyright (c) 2002, Sun Microsystems, Inc. All Rights Reserved
+.\" Copyright 2021 Oxide Computer Company
 .\"
-.TH CLOSEDIR 3C "Jul 24, 2002"
-.SH NAME
-closedir \- close a directory stream
-.SH SYNOPSIS
-.LP
-.nf
-#include <sys/types.h>
-#include <dirent.h>
-
-\fBint\fR \fBclosedir\fR(\fBDIR *\fR\fIdirp\fR);
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The \fBclosedir()\fR function closes the directory stream referred to by the
-argument \fIdirp.\fR Upon return, the value of \fIdirp\fR may no longer point
-to an accessible object of the type \fBDIR\fR. If a file descriptor is used to
-implement type \fBDIR\fR, that file descriptor will be closed.
-.SH RETURN VALUES
-.sp
-.LP
-Upon successful completion, \fBclosedir()\fR returns \fB0\fR. Otherwise,
-\fB\(mi1\fR is returned and \fBerrno\fR is set to indicate the error.
-.SH ERRORS
-.sp
-.LP
-The \fBclosedir()\fR function may fail if:
-.sp
-.ne 2
-.na
-\fB\fBEBADF\fR\fR
-.ad
-.RS 9n
-The \fIdirp\fR argument does not refer to an open directory stream.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBEINTR\fR\fR
-.ad
-.RS 9n
-The \fBclosedir()\fR function was interrupted by a signal.
-.RE
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Interface Stability	Standard
-_
-MT-Level	Safe
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBopendir\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
+.Dd February 25, 2021
+.Dt CLOSEDIR 3C
+.Os
+.Sh NAME
+.Nm closedir
+.Nd close a directory stream
+.Sh SYNOPSIS
+.In sys/types.h
+.In dirent.h
+.Ft int
+.Fo closedir
+.Fa "DIR *dirp"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn closedir
+function closes the directory stream referred to by the argument
+.Fa dirp ,
+which generally came from calling
+.Xr opendir 3C
+or
+.Xr fdopendir 3C .
+Upon return, the value of
+.Fa dirp
+will no longer point to an accessible object of the type
+.Ft DIR .
+The underlying file descriptor for the directory stream will be closed.
+This includes a
+.Ft DIR
+created by passing a file descriptor to
+.Xr fdopendir 3C .
+.Pp
+When the directory stream is closed, any memory that is associated with
+the stream will no longer be valid.
+Most notably, the dirent structures returned from
+.Xr readdir 3C
+use memory associated with the corresponding
+.Ft "DIR *"
+argument.
+Each directory stream has its own independent memory.
+Closing one stream does not impact the validity of other streams.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn closedir
+function returns
+.Sy 0 .
+Otherwise,
+.Sy -1
+is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn closedir
+function may fail if:
+.Bl -tag -width Er
+.It Er EBADF
+The
+.Fa dirp
+argument does not refer to an open directory stream.
+.It Er EINTR
+The
+.Fn closedir
+function was interrupted by a signal.
+.El
+.Sh INTERFACE STABILITY
+.Sy Standard
+.Sh MT-LEVEL
+.Sy Safe
+.Sh SEE ALSO
+.Xr fdopendir 3C ,
+.Xr opendir 3C ,
+.Xr readdir 3C ,
+.Xr attributes 5
diff --git a/usr/src/man/man3c/opendir.3c b/usr/src/man/man3c/opendir.3c
index fa35c1aca9..a03928c9c7 100644
--- a/usr/src/man/man3c/opendir.3c
+++ b/usr/src/man/man3c/opendir.3c
@@ -42,175 +42,168 @@
 .\"
 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 2021 Oxide Computer Company
 .\"
-.TH OPENDIR 3C "Jun 26, 2007"
-.SH NAME
-opendir, fdopendir \- open directory
-.SH SYNOPSIS
-.LP
-.nf
-#include <sys/types.h>
-#include <dirent.h>
-
-\fBDIR *\fR\fBopendir\fR(\fBconst char *\fR\fIdirname\fR);
-.fi
-
-.LP
-.nf
-\fBDIR *\fR\fBfdopendir\fR(\fBint\fR \fIfildes\fR);
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The \fBopendir()\fR function opens a directory stream corresponding to the
-directory named by the \fIdirname\fR argument.
-.sp
-.LP
-The \fBfdopendir()\fR function opens a directory stream for the directory file
-descriptor \fIfildes\fR. The directory file descriptor should not be used or
-closed following a successful function call, as this might cause undefined
-results from future operations on the directory stream obtained from the call.
-Use \fBclosedir\fR(3C) to close a directory stream.
-.sp
-.LP
-The directory stream is positioned at the first entry. If the type \fBDIR\fR is
-implemented using a file descriptor, applications will only be able to open up
-to a total of {\fBOPEN_MAX\fR} files and directories. A successful call to any
-of the \fBexec\fR functions will close any directory streams that are open in
-the calling process.  See \fBexec\fR(2).
-.SH RETURN VALUES
-.sp
-.LP
-Upon successful completion, \fBopendir()\fR and \fBfdopendir()\fR return a
-pointer to an object of type \fBDIR\fR. Otherwise, a null pointer is returned
-and \fBerrno\fR is set to indicate the error.
-.SH ERRORS
-.sp
-.LP
-The \fBopendir()\fR function will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEACCES\fR\fR
-.ad
-.RS 16n
-Search permission is denied for the component of the path prefix of
-\fIdirname\fR or read permission is denied for \fIdirname\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBELOOP\fR\fR
-.ad
-.RS 16n
-Too many symbolic links were encountered in resolving \fIpath\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENAMETOOLONG\fR\fR
-.ad
-.RS 16n
-The length of the \fIdirname\fR argument exceeds {\fBPATH_MAX\fR}, or a path
-name component is longer than {\fBNAME_MAX\fR} while {\fB_POSIX_NO_TRUNC\fR} is
-in effect.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENOENT\fR\fR
-.ad
-.RS 16n
-A component of \fIdirname\fR does not name an existing directory or
-\fIdirname\fR is an empty string.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENOTDIR\fR\fR
-.ad
-.RS 16n
-A component of \fIdirname\fR is not a directory.
-.RE
-
-.sp
-.LP
-The \fBfdopendir()\fR function will fail if:
-.sp
-.ne 2
-.na
-\fB\fBENOTDIR\fR\fR
-.ad
-.RS 11n
-The file descriptor \fIfildes\fR does not reference a directory.
-.RE
-
-.sp
-.LP
-The \fBopendir()\fR function may fail if:
-.sp
-.ne 2
-.na
-\fB\fBEMFILE\fR\fR
-.ad
-.RS 16n
-There are {\fBOPEN_MAX\fR} file descriptors currently open in the calling
-process.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENAMETOOLONG\fR\fR
-.ad
-.RS 16n
+.Dd February 25, 2021
+.Dt OPENDIR 3C
+.Os
+.Sh NAME
+.Nm opendir ,
+.Nm fdopendir
+.Nd open directory stream
+.Sh SYNOPSIS
+.In sys/types.h
+.In dirent.h
+.Ft "DIR *"
+.Fo opendir
+.Fa "dirname"
+.Fc
+.Ft "DIR *"
+.Fo fdopendir
+.Fa "int filedes"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn opendir
+and
+.Fn fdopendir
+functions are used to create seekable directory streams that can be used
+to iterate over the contents of a directory, most commonly with
+.Xr readdir 3C .
+One can traverse and seek the stream with functions such as
+.Xr seekdir 3C ,
+.Xr telldir 3C ,
+and
+.Xr rewinddir 3C .
+.Pp
+The
+.Fn opendir
+function creates a directory stream from the path named by
+.Fa dirname .
+The
+.Fn fdopendir
+function creates a directory stream from an already opened file
+descriptor,
+.Fa filedes ,
+that refers to a directory.
+After successfully calling
+.Fn fdopendir ,
+.Fa filedes
+belongs to the system and the application must not modify or close it in
+any way.
+.Pp
+The new directory stream is positioned at the first entry.
+When finished with the directory stream, the caller is responsible for
+releasing its resources by calling the
+.Xr closedir 3C
+function.
+This will close the directory stream's underlying file descriptor,
+including
+.Fa filedes
+if
+.Fn fdopendir
+was used to create it.
+In addition, memory associated with the directory stream, such as the
+.Ft struct dirent
+returned from
+.Xr readdir 3C
+will be invalid once a call to
+.Xr closedir 3C
+is completed.
+.Pp
+All directory streams are closed upon a successful call to any of the
+.Xr exec 2
+family of functions.
+The underlying file descriptors behave as though the
+.Dv FD_CLOEXEC
+flag was set upon them.
+.Pp
+Directory streams created by the
+.Fn opendir
+function require an underlying file descriptor.
+As a result, applications are only able to open up to a total of
+.Brq Dv OPEN_MAX
+files and directories.
+.Sh RETURN VALUES
+Upon successful completion, the
+.Fn opendir
+and
+.Fn fdopendir
+functions return a pointer to an object of type
+Ft DIR .
+Otherwise, a null pointer is returned and
+.Va errno
+is set to indicate the error.
+.Sh ERRORS
+The
+.Fn opendir
+function will fail if:
+.Bl -tag -width Er
+.It Er EACCES
+Search permission is denied for any component of the path prefix of
+.Fa dirname
+or read permission is denied for
+.Fa Idirname .
+.It Er ELOOP
+Too many symbolic links were encountered in resolving
+.Fa path .
+.It Er ENAMETOOLONG
+The length of the
+.Fa dirname
+argument exceeds
+.Brq Dv PATH_MAX ,
+or a path name component is longer than
+.Brq Dv NAME_MAX
+while
+.Brq Dv _POSIX_NO_TRUNC
+is in effect.
+.It Er ENOENT
+A component of
+.Fa dirname
+does not name an existing directory or
+.Fa dirname
+is an empty string.
+.It Er ENOTDIR
+A component of
+.Fa dirname
+is not a directory.
+.El
+.Pp
+The
+.Fn fdopendir
+function will fail if:
+.Bl -tag -width Er
+.It Er ENOTDIR
+The file descriptor
+.Fa filedes
+does not reference a directory.
+.El
+.Pp
+The
+.Fn opendir
+function may fail if:
+.Bl -tag -width Er
+.It Er EMFILE
+There are already
+.Brq Dv OPEN_MAX
+file descriptors currently open in the calling process.
+.It Er ENAMETOOLONG
 Pathname resolution of a symbolic link produced an intermediate result whose
-length exceeds \fBPATH_MAX\fR.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENFILE\fR\fR
-.ad
-.RS 16n
+length exceeds
+.Dv PATH_MAX .
+.It Er ENFILE
 Too many files are currently open on the system.
-.RE
-
-.SH USAGE
-.sp
-.LP
-The \fBopendir()\fR and \fBfdopendir()\fR functions should be used in
-conjunction with \fBreaddir\fR(3C), \fBclosedir\fR(3C) and \fBrewinddir\fR(3C)
-to examine the contents of the directory (see the \fBEXAMPLES\fR section in
-\fBreaddir\fR(3C)). This method is recommended for portability.
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Interface Stability	T{
-\fBopendir()\fR is Standard; \fBfdopendir()\fR is Evolving
-T}
-_
-MT-Level	Safe
-.TE
-
-.SH SEE ALSO
-.sp
-.LP
-\fBlstat\fR(2), \fBsymlink\fR(2), \fBclosedir\fR(3C), \fBreaddir\fR(3C),
-\fBrewinddir\fR(3C), \fBscandir\fR(3C), \fBattributes\fR(5)
+.El
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-LEVEL
+.Sy Safe
+.Sh SEE ALSO
+.Xr lstat 2 ,
+.Xr symlink 2 ,
+.Xr closedir 3C ,
+.Xr readdir 3C ,
+.Xr rewinddir 3C ,
+.Xr seekdir 3C ,
+.Xr telldir 3C ,
+.Xr attributes 5
diff --git a/usr/src/man/man3c/readdir.3c b/usr/src/man/man3c/readdir.3c
index b7c55cf0e1..4d61797f25 100644
--- a/usr/src/man/man3c/readdir.3c
+++ b/usr/src/man/man3c/readdir.3c
@@ -42,211 +42,250 @@
 .\"
 .\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
+.\" Copyright 2021 Oxide Computer Company
 .\"
-.TH READDIR 3C "Jun 26, 2007"
-.SH NAME
-readdir, readdir_r \- read directory
-.SH SYNOPSIS
-.LP
-.nf
-#include <sys/types.h>
-#include <dirent.h>
-
-\fBstruct dirent *\fR\fBreaddir\fR(\fBDIR *\fR\fIdirp\fR);
-.fi
-
-.LP
-.nf
-\fBstruct dirent *\fR\fBreaddir_r\fR(\fBDIR *\fR\fIdirp\fR, \fBstruct dirent *\fR\fIentry\fR);
-.fi
-
-.SS "Standard conforming"
-.LP
-.nf
-cc [ \fIflag\fR... ] \fIfile\fR... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR... ]
-
-\fBint\fR \fBreaddir_r\fR(\fBDIR *restrict\fR \fIdirp\fR, \fBstruct dirent *restrict\fR \fIentry\fR,
-     \fBstruct dirent **restrict\fR \fIresult\fR);
-.fi
-
-.SH DESCRIPTION
-.sp
-.LP
-The type \fBDIR\fR, which is defined in the header <\fBdirent.h\fR>, represents
-a \fIdirectory stream\fR, which is an ordered sequence of all the directory
-entries in a particular directory. Directory entries represent files. Files can
-be removed from a directory or added to a directory asynchronously to the
-operation of \fBreaddir()\fR and \fBreaddir_r()\fR.
-.SS "\fBreaddir()\fR"
-.sp
-.LP
-The \fBreaddir()\fR function returns a pointer to a structure representing the
-directory entry at the current position in the directory stream specified by
-the argument \fIdirp\fR, and positions the directory stream at the next entry.
-It returns a null pointer upon reaching the end of the directory stream. The
-structure \fBdirent\fR defined by the \fB<dirent.h>\fR header describes a
-directory entry.
-.sp
-.LP
-The \fBreaddir()\fR function will not return directory entries containing empty
-names. If entries for . (dot) or .. (dot-dot) exist, one entry will be returned
-for dot and one entry will be returned for dot-dot; otherwise they will not be
-returned.
-.sp
-.LP
-The pointer returned by \fBreaddir()\fR points to data that can be overwritten
-by another call to \fBreaddir()\fR on the same directory stream. These data are
-not overwritten by another call to \fBreaddir()\fR on a different directory
-stream.
-.sp
-.LP
+.Dd February 25, 2021
+.Dt READDIR 3C
+.Os
+.Sh NAME
+.Nm readdir ,
+.Nm readdir_r
+.Nd read directory
+.Sh SYNOPSIS
+.In sys/types.h
+.In dirent.h
+.Ft "struct dirent *"
+.Fo readdir
+.Fa "DIR *dirp"
+.Fc
+.Ft "struct dirent *"
+.Fo readdir_r
+.Fa "DIR *dirp"
+.Fa "struct dirent *entry"
+.Fc
+.Ss Standard Conforming
+.Fd #define _POSIX_PTHREAD_SEMANTICS
+.Ft int
+.Fo readdir_r
+.Fa "DIR *restrict dirp"
+.Fa "struct dirent *restrict entry"
+.Fa "struct dirent **restrict result"
+.Fc
+.Sh DESCRIPTION
+The type
+.Ft DIR ,
+which is defined in the header
+.In dirent.h ,
+represents a
+.Em directory stream ,
+which is an ordered sequence of all the directory entries in a particular
+directory.
+Directory entries represent files.
+Files can be removed from a directory or added to a directory asynchronously
+to the operation of
+.Fn readdir
+and
+.Fn readdir_r .
+.Ss Fn readdir
+The
+.Fn readdir
+function returns a pointer to a structure representing the directory entry at
+the current position in the directory stream specified by the argument
+.Fa dirp ,
+and positions the directory stream at the next entry.
+It returns a null pointer upon reaching the end of the directory stream.
+The structure
+.Ft dirent
+defined by the
+.In dirent.h
+header describes a directory entry.
+.Pp
+The
+.Fn readdir
+function will not return directory entries containing empty names.
+If entries for
+.No \&.
+.Pq dot
+.No \&..
+.Pq dot-dot
+exist, one entry will be returned for dot and one entry will be returned for
+dot-dot; otherwise they will not be returned.
+.Pp
+The pointer returned by
+.Fn readdir
+points to data that can be overwritten by another call to
+.Fn readdir
+on the same directory stream.
+It will not be overwritten by another call to
+.Fn readdir
+on a different directory stream.
+The returned pointer will remain valid until the directory stream is
+freed with a call to
+.Xr closedir 3C .
+It is safe to use
+.Fn readdir
+in a threaded application, so long as only one thread reads from the directory
+stream at any given time.
+.Pp
 If a file is removed from or added to the directory after the most recent call
-to \fBopendir\fR(3C) or \fBrewinddir\fR(3C), whether a subsequent call to
-\fBreaddir()\fR returns an entry for that file is unspecified.
-.sp
-.LP
-The \fBreaddir()\fR function can buffer several directory entries per actual
-read operation. It marks for update the \fBst_atime\fR field of the directory
-each time the directory is actually read.
-.sp
-.LP
-After a call to \fBfork\fR(2), either the parent or child (but not both) can
-continue processing the directory stream using \fBreaddir()\fR,
-\fBrewinddir()\fR or \fBseekdir\fR(3C). If both the parent and child processes
-use these functions, the result is undefined.
-.sp
-.LP
-If the entry names a symbolic link, the value of the \fBd_ino\fR member is
-unspecified.
-.SS "\fBreaddir_r()\fR"
-.sp
-.LP
+to
+.Xr opendir 3C
+or
+.Xr rewinddir 3C ,
+whether a subsequent call to
+.Fn readdir
+returns an entry for that file is unspecified.
+.Pp
+The
+.Fn readdir
+function can buffer several directory entries per actual read operation.
+It marks for update the
+.Ft st_atime
+field of the directory each time the directory is actually read.
+.Pp
+After a call to
+.Xr fork 2 ,
+either the parent or child
+.Pq but not both
+can continue processing the directory stream using
+.Fn readdir ,
+.Xr rewinddir 3C ,
+or
+.Xr seekdir 3C .
+If both the parent and child processes use these functions, the result is
+undefined.
+.Pp
+If the entry names a symbolic link, the value of the
+.Ft d_ino
+member is unspecified.
+.Ss Fn readdir_r
 Unless the end of the directory stream has been reached or an error occurred,
-the \fBreaddir_r()\fR function initializes the \fBdirent\fR structure
-referenced by \fBentry\fR to represent the directory entry at the current
-position in the directory stream referred to by \fIdirp\fR,  and positions the
-directory stream at the next entry.
-.sp
-.LP
-The caller must allocate storage pointed to by \fIentry\fR to be large enough
-for a \fBdirent\fR structure with an array of \fBchar\fR \fBd_name\fR member
-containing at least \fBNAME_MAX\fR (that is, \fBpathconf(directory,
-_PC_NAME_MAX\fR)) plus one elements. (\fB_PC_NAME_MAX\fR is defined in
-<\fBunistd.h\fR>.)
-.sp
-.LP
-The \fBreaddir_r()\fR function will not return directory entries containing
-empty names. It is unspecified whether entries are returned for . (dot) or ..
-(dot-dot).
-.sp
-.LP
+the
+.Fn readdir_r
+function initializes the
+.Ft dirent
+structure referenced by
+.Fa entry
+to represent the directory entry at the current position in the directory
+stream referred to by
+.Fa dirp ,
+and positions the directory stream at the next entry.
+.Pp
+The caller must allocate storage pointed to by
+.Fa entry
+to be large enough for a
+.Ft dirent
+structure with an array of
+.Ft char
+.Fa d_name
+member containing at least
+.Dv NAME_MAX
+.Po
+that is,
+.Fo pathconf
+.Fa directory ,
+.Dv _PC_NAME_MAX
+.Fc
+plus one element.
+.Po
+.Dv _PC_NAME_MAX
+is defined in
+.In unistd.h
+.Pc
+.Pc
+.Pp
+While the
+.Fn readdir_r function was originally added as a re-entrant version of
+.Fn readdir ,
+it is not recommended that
+.Fn readdir_r
+be used in new applications and existing software should instead use
+.Fn readdir .
+The
+.Fn readdir_r
+function has been deprecated in many systems.
+Historically, the data returned from
+.Fn readdir
+was not specific to the directory stream making it unsafe in a multi-threaded
+environment; however, that is no longer the case.
+.Pp
+The
+.Fn readdir_r
+function will not return directory entries containing empty names.
+It is unspecified whether entries are returned for
+.No \&.
+.Pq dot
+or
+.No \&..
+.Pq dot-dot .
+.Pp
 If a file is removed from or added to the directory after the most recent call
-to \fBopendir()\fR or \fBrewinddir()\fR, whether a subsequent call to
-\fBreaddir_r()\fR returns an entry for that file is unspecified.
-.sp
-.LP
-The \fBreaddir_r()\fR function can buffer several directory entries per actual
-read operation. It marks for update the \fBst_atime\fR field of the directory
-each time the directory is actually read.
-.sp
-.LP
-The standard-conforming version (see \fBstandards\fR(5)) of the
-\fBreaddir_r()\fR function performs all of the actions described above and sets
-the pointer pointed to by \fIresult\fR. If a directory entry is returned, the
-pointer will be set to the same value as the \fIentry\fR argument; otherwise,
-it will be set to \fINULL\fR.
-.SH RETURN VALUES
-.sp
-.LP
-Upon successful completion, \fBreaddir()\fR and the default \fBreaddir_r()\fR
-return a pointer to an object of type \fBstruct dirent\fR. When an error is
-encountered, a null pointer is returned and \fBerrno\fR is set to indicate the
-error. When the end of the directory is encountered, a null pointer is returned
-and \fBerrno\fR is not changed.
-.sp
-.LP
-The standard-conforming \fBreaddir_r()\fR returns  \fB0\fR if the end of the
-directory is encountered or a directory entry is stored in the structure
-referenced by \fIentry\fR. Otherwise, an error number is returned to indicate
-the failure.
-.SH ERRORS
-.sp
-.LP
-The \fBreaddir()\fR and \fBreaddir_r()\fR functions will fail if:
-.sp
-.ne 2
-.na
-\fB\fBEOVERFLOW\fR\fR
-.ad
-.RS 13n
-One of the values in the structure to be returned cannot be represented
-correctly.
-.RE
-
-.sp
-.LP
-The \fBreaddir()\fR and \fBreaddir_r()\fR functions may fail if:
-.sp
-.ne 2
-.na
-\fB\fBEBADF\fR\fR
-.ad
-.RS 10n
-The \fIdirp\fR argument does not refer to an open directory stream.
-.RE
-
-.sp
-.ne 2
-.na
-\fB\fBENOENT\fR\fR
-.ad
-.RS 10n
-The current position of the directory stream is invalid.
-.RE
-
-.SH USAGE
-.sp
-.LP
-The \fBreaddir()\fR  and \fBreaddir_r()\fR functions should be used in
-conjunction with \fBopendir()\fR, \fBclosedir()\fR, and \fBrewinddir()\fR to
-examine the contents of the directory.  Since \fBreaddir()\fR and the default
-\fBreaddir_r()\fR return a null pointer both at the end of the directory and on
-error, an application wanting to check for error situations should set
-\fBerrno\fR to 0 before calling either of these functions. If \fBerrno\fR is
-set to non-zero on return, an error occurred.
-.sp
-.LP
-It is safe to use \fBreaddir()\fR in a threaded application, so long as only
-one thread reads from the directory stream at any given time. The
-\fBreaddir()\fR function is generally preferred over the \fBreaddir_r()\fR
-function.
-.sp
-.LP
-The standard-conforming \fBreaddir_r()\fR returns the error number if an error
-occurred. It returns 0 on success (including reaching the end of the directory
-stream).
-.sp
-.LP
-The \fBreaddir()\fR and \fBreaddir_r()\fR functions have transitional
-interfaces for 64-bit file offsets.  See \fBlf64\fR(5).
-.SH EXAMPLES
-.LP
-\fBExample 1 \fRSearch the current directory for the entry \fIname\fR.
-.sp
-.LP
+to
+.Xr opendir 3C or
+.Xr rewinddir 3C , whether a subsequent call to
+.Fn readdir_r
+returns an entry for that file is unspecified.
+.Pp
+The
+.Fn readdir_r
+function can buffer several directory entries per actual read operation.
+It marks for update the
+.Ft st_atime
+field of the directory each time the directory is actually read.
+.Pp
+The standard-conforming version
+.Po see
+.Xr standards 5
+.Pc
+of the
+.Fn readdir_r
+function performs all of the actions described above for
+.Fn readdir_r
+and sets the pointer pointed to by
+.Fa result .
+If a directory entry is returned, the pointer will be set to the same value
+as the
+.Fa entry
+argument; otherwise, it will be set to
+.Dv NULL .
+.Sh RETURN VALUES
+Upon successful completion,
+.Fn readdir
+and the default
+.Fn readdir_r
+return a pointer to an object of type
+.Ft struct dirent .
+When an error is encountered, a null pointer is returned and
+.Va errno
+is set to indicate the error.
+When the end of the directory is encountered, a null pointer is returned and
+.Va errno
+is not changed.
+.Pp
+The standard-conforming
+.Fn readdir_r
+returns
+.Sy 0
+if the end of the directory is encountered or a directory entry is stored in
+the structure referenced by
+.Fa entry .
+Otherwise, an error number is returned to indicate the failure.
+.Sh EXAMPLES
+.Sy Example 1
+Search the current directory for the entry
+.Fa name .
+.Pp
 The following sample program will search the current directory for each of the
 arguments supplied on the command line:
-
-.sp
-.in +2
-.nf
+.Bd -literal
 #include <sys/types.h>
 #include <dirent.h>
 #include <errno.h>
 #include <stdio.h>
 #include <strings.h>
 
-static void lookup(const char *arg)
+static void
+lookup(const char *arg)
 {
         DIR *dirp;
         struct dirent *dp;
@@ -273,60 +312,124 @@ static void lookup(const char *arg)
         else
                 (void) printf("failed to find %s\en", arg);
         (void) closedir(dirp);
-        return;
 }
 
-int main(int argc, char *argv[])
+int
+main(int argc, char *argv[])
 {
         int i;
         for (i = 1; i < argc; i++)
                 lookup(argv[i]);
         return (0);
 }
-.fi
-.in -2
-
-.SH ATTRIBUTES
-.sp
-.LP
-See \fBattributes\fR(5) for descriptions of the following attributes:
-.sp
-
-.sp
-.TS
-box;
-c | c
-l | l .
-ATTRIBUTE TYPE	ATTRIBUTE VALUE
-_
-Interface Stability	Standard
-_
-MT-Level	See below.
-.TE
-
-.sp
-.LP
-The \fBreaddir()\fR function is Unsafe. The \fBreaddir_r()\fR function is Safe.
-.SH SEE ALSO
-.sp
-.LP
-\fBfork\fR(2), \fBlstat\fR(2), \fBsymlink\fR(2), \fBIntro\fR(3),
-\fBclosedir\fR(3C), \fBopendir\fR(3C), \fBrewinddir\fR(3C), \fBscandir\fR(3C),
-\fBseekdir\fR(3C), \fBattributes\fR(5), \fBlf64\fR(5), \fBstandards\fR(5)
-.SH NOTES
-.sp
-.LP
-When compiling multithreaded programs, see the \fBMULTITHREADED APPLICATIONS\fR
-section of \fBIntro\fR(3).
-.sp
-.LP
-Solaris 2.4 and earlier releases provided a \fBreaddir_r()\fR interface as
-specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
-interface as described above. Support for the Draft 6 interface is provided for
-compatibility only and might not be supported in future releases. New
-applications and libraries should use the standard-conforming interface.
-.sp
-.LP
-For POSIX.1c-conforming applications, the \fB_POSIX_PTHREAD_SEMANTICS\fR and
-\fB_REENTRANT\fR flags are automatically turned on by defining the
-\fB_POSIX_C_SOURCE\fR flag with a value >= 199506L.
+.Ed
+.Sh ERRORS
+The
+.Fn readdir
+and
+.Fn readdir_r
+functions will fail if:
+.Bl -tag -width Er
+.It Er EOVERFLOW
+One of the values in the structure to be returned cannot be represented
+correctly.
+.El
+.Pp
+The
+.Fn readdir
+and
+.Fn readdir_r
+functions may fail if:
+.Bl -tag -width Er
+.It Er EBADF
+The
+.Fa dirp
+argument does not refer to an open directory stream.
+.It Er ENOENT
+The current position of the directory stream is invalid.
+.El
+.Sh USAGE
+The
+.Fn readdir
+and
+.Fn readdir_r
+functions should be used in conjunction with
+.Xr opendir 3C ,
+.Xr closedir 3C ,
+and
+.Xr rewinddir 3C
+to examine the contents of the directory.
+Since
+.Fn readdir
+and the default
+.Fn readdir_r
+return a null pointer both at the end of the directory and on error, an
+application wanting to check for error situations should set
+.Va errno
+to 0 before calling either of these functions.
+If
+.Va errno
+is set to non-zero on return, an error occurred.
+.Pp
+The standard-conforming
+.Fn readdir_r
+returns the error number if an error occurred.
+It returns 0 on success
+.Pq including reaching the end of the directory stream .
+.Pp
+The
+.Fn readdir
+and
+.Fn readdir_r
+functions have transitional interfaces for 64-bit file offsets.
+See
+.Xr lf64 5 .
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-LEVEL
+The
+.Fn readdir
+function is
+.Sy Unsafe ;
+however, it is
+.Sy Safe
+if different directory streams are used concurrently.
+The
+.Fn readdir_r
+function is
+.Sy Safe .
+.Sh SEE ALSO
+.Xr fork 2 ,
+.Xr lstat 2 ,
+.Xr symlink 2 ,
+.Xr Intro 3 ,
+.Xr closedir 3C ,
+.Xr opendir 3C ,
+.Xr rewinddir 3C ,
+.Xr scandir 3C ,
+.Xr seekdir 3C ,
+.Xr attributes 5 ,
+.Xr lf64 5 ,
+.Xr standards 5
+.Sh NOTES
+When compiling multithreaded programs, see the
+.Sy MULTITHREADED APPLICATIONS
+section of
+.Xr Intro 3 .
+.Pp
+Solaris 2.4 and earlier releases provided a
+.Fn readdir_r
+interface as specified in POSIX.1c Draft 6.
+The final POSIX.1c standard changed the interface as described above.
+Support for the Draft 6 interface is provided for compatibility only.
+New applications and libraries should use the standard-conforming interface,
+though preferably
+.Fn readdir .
+.Pp
+For POSIX.1c-conforming applications, the
+.Dv _POSIX_PTHREAD_SEMANTICS
+and
+.Dv _REENTRANT
+flags are automatically turned on by defining the
+.Dv _POSIX_C_SOURCE
+flag with a value >= 199506L.