my previous version was wrong; this one is right

[unix-history] / usr / src / lib / libc / sys / getdirentries.2

diff --git a/usr/src/lib/libc/sys/getdirentries.2 b/usr/src/lib/libc/sys/getdirentries.2
index 9fa7401..c971b36 100644 (file)
--- a/usr/src/lib/libc/sys/getdirentries.2
+++ b/usr/src/lib/libc/sys/getdirentries.2
@@ -1,123 +1,124 @@
-.\" Copyright (c) 1989 The Regents of the University of California.
+.\" Copyright (c) 1989, 1991 The Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"
 .\" All rights reserved.
 .\"
 .\" %sccs.include.redist.man%
 .\"

-.\"    @(#)getdirentries.2     6.2 (Berkeley) %G%
+.\"     @(#)getdirentries.2    6.4 (Berkeley) %G%

 .\"
 .\"

-.TH GETDIRENTRIES 2 ""
-.UC 7
-.SH NAME
-getdirentries \- get directory entries in a filesystem independent format
-.SH SYNOPSIS
-.nf
-.ft B
-#include <sys/dirent.h>
-.LP
-.ft B
-cc = getdirentries(fd, buf, nbytes, basep)
-int cc, fd;
-char *buf;
-int nbytes;
-long *basep;
-.fi
-.SH DESCRIPTION
-.I Getdirentries
+.Dd 
+.Dt GETDIRENTRIES 2
+.Os BSD 4.4
+.Sh NAME
+.Nm getdirentries
+.Nd "get directory entries in a filesystem independent format"
+.Sh SYNOPSIS
+.Fd #include <sys/dirent.h>
+.Ft int
+.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep"
+.Sh DESCRIPTION
+.Fn Getdirentries

 reads directory entries from the directory
 referenced by the file descriptor
 reads directory entries from the directory
 referenced by the file descriptor

-.I fd
+.Fa fd

 into the buffer pointed to by
 into the buffer pointed to by

-.IR buf ,
+.Fa buf ,

 in a filesystem independent format.
 Up to
 in a filesystem independent format.
 Up to

-.I nbytes
+.Fa nbytes

 of data will be transferred.
 of data will be transferred.

-.I Nbytes
+.Fa Nbytes

 must be greater than or equal to the
 block size associated with the file,
 see
 must be greater than or equal to the
 block size associated with the file,
 see

-.IR stat(2) .
+.Xr stat 2 .

 Some filesystems may not support
 Some filesystems may not support

-.I getdirentries
+.Fn getdirentries

 with buffers smaller than this size.
 with buffers smaller than this size.

-.PP
+.Pp

 The data in the buffer is a series of
 The data in the buffer is a series of

-.I dirent
+.Em dirent

 structures each containing the following entries:
 structures each containing the following entries:

-.PP
-.RS
-.ta +\w'unsigned\0short\0'u +\w'd_name[MAXNAMELEN + 1];\0'u
-.nf
+.Bd -literal -offset indent

 unsigned long  d_fileno;
 unsigned short d_reclen;
 unsigned short d_namlen;
 unsigned long  d_fileno;
 unsigned short d_reclen;
 unsigned short d_namlen;

-char           d_name[MAXNAMELEN + 1]; /* see below */
-.fi
-.RE
-.PP
+char           d_name[MAXNAMELEN + 1]; /* see below */
+.Ed
+.Pp

 The
 The

-.I d_fileno
+.Fa d_fileno

 entry is a number which is unique for each
 distinct file in the filesystem.
 Files that are linked by hard links (see
 entry is a number which is unique for each
 distinct file in the filesystem.
 Files that are linked by hard links (see

-.IR link(2) )
+.Xr link 2 )

 have the same
 have the same

-.IR d_fileno .
+.Fa d_fileno .

 The
 The

-.I d_reclen
+.Fa d_reclen

 entry is the length, in bytes, of the directory record.
 The
 entry is the length, in bytes, of the directory record.
 The

-.I d_name
+.Fa d_name

 entry contains a null terminated file name.
 The
 entry contains a null terminated file name.
 The

-.I d_namlen
+.Fa d_namlen

 entry specifies the length of the file name excluding the null byte.
 Thus the actual size of
 entry specifies the length of the file name excluding the null byte.
 Thus the actual size of

-.I d_name
-may vary from 1 to \fBMAXNAMELEN + 1\fP.
-.PP
+.Fa d_name
+may vary from 1 to
+.Dv MAXNAMELEN
+\&+ 1.
+.Pp

 Entries may be separated by extra space.
 The
 Entries may be separated by extra space.
 The

-.I d_reclen
+.Fa d_reclen

 entry may be used as an offset from the start of a
 entry may be used as an offset from the start of a

-.I dirent
+.Fa dirent

 structure to the next structure, if any.
 structure to the next structure, if any.

-.PP
+.Pp

 The actual number of bytes transferred is returned.
 The current position pointer associated with
 The actual number of bytes transferred is returned.
 The current position pointer associated with

-.I fd
+.Fa fd

 is set to point to the next block of entries.
 The pointer may not advance by the number of bytes returned by
 is set to point to the next block of entries.
 The pointer may not advance by the number of bytes returned by

-.IR getdirentries .
+.Fn getdirentries .

 A value of zero is returned when
 the end of the directory has been reached.
 A value of zero is returned when
 the end of the directory has been reached.

-.PP
-.I Getdirentries
+.Pp
+.Fn Getdirentries

 writes the position of the block read into the location pointed to by
 writes the position of the block read into the location pointed to by

-.IR basep .
+.Fa basep .

 Alternatively, the current position pointer may be set and retrieved by
 Alternatively, the current position pointer may be set and retrieved by

-.IR lseek(2) .
+.Xr lseek 2 .

 The current position pointer should only be set to a value returned by
 The current position pointer should only be set to a value returned by

-.I lseek(2) ,
+.Xr lseek 2 ,

 a value returned in the location pointed to by
 a value returned in the location pointed to by

-.I basep ,
+.Fa basep ,

 or zero.
 or zero.

-.SH RETURN VALUE
+.Sh RETURN VALUES

 If successful, the number of bytes actually transferred is returned.
 If successful, the number of bytes actually transferred is returned.

-Otherwise, a \-1 is returned and the global variable
-.I errno
+Otherwise, -1 is returned and the global variable
+.Va errno

 is set to indicate the error.
 is set to indicate the error.

-.SH ERRORS
-.I Getdirentries
-will fail if one or more of the following are true:
-.TP 15
-EBADF
-\fIfd\fP is not a valid file descriptor open for reading.
-.TP 15
-EFAULT
-Either \fIbuf\fP or \fIbasep\fP point outside the allocated address space.
-.TP 15
-EIO
+.Sh ERRORS
+.Fn Getdirentries
+will fail if:
+.Bl -tag -width [EFAULT]
+.It EBADF
+.Fa fd
+is not a valid file descriptor open for reading.
+.It EFAULT
+Either
+.Fa buf
+or
+.Fa basep
+point outside the allocated address space.
+.It EIO

 An I/O error occurred while reading from or writing to the file system.
 An I/O error occurred while reading from or writing to the file system.

-.SH "SEE ALSO"
-open(2), lseek(2)
+.El
+.Sh SEE ALSO
+.Xr open 2 ,
+.Xr lseek 2
+.Sh HISTORY
+The
+.Nm
+function call is currently under development.