From 03610e3c14210b573cb5c6c7ba9d9daf37ca2e1a Mon Sep 17 00:00:00 2001 From: mpp Date: Fri, 30 Jul 1999 11:32:08 +0000 Subject: Document the getdents(2) system call. The documentation was added to the getdirentries(2) man page because 95%+ of that man page comprised the text of the getdents(2) man page I obtained from NetBSD. --- lib/libc/sys/Makefile.inc | 3 +- lib/libc/sys/getdents.2 | 151 ------------------------------------------- lib/libc/sys/getdirentries.2 | 40 ++++++++---- 3 files changed, 29 insertions(+), 165 deletions(-) delete mode 100644 lib/libc/sys/getdents.2 (limited to 'lib') diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc index 342fbed..e91b651 100644 --- a/lib/libc/sys/Makefile.inc +++ b/lib/libc/sys/Makefile.inc @@ -1,5 +1,5 @@ # @(#)Makefile.inc 8.3 (Berkeley) 10/24/94 -# $Id: Makefile.inc,v 1.63 1999/07/30 09:01:45 mpp Exp $ +# $Id: Makefile.inc,v 1.64 1999/07/30 10:08:21 mpp Exp $ # sys sources .PATH: ${.CURDIR}/../libc/${MACHINE_ARCH}/sys ${.CURDIR}/../libc/sys @@ -109,6 +109,7 @@ MLINKS+=chflags.2 fchflags.2 MLINKS+=chmod.2 fchmod.2 chmod.2 lchmod.2 MLINKS+=chown.2 fchown.2 chown.2 lchown.2 MLINKS+=clock_gettime.2 clock_getres.2 clock_gettime.2 clock_settime.2 +MLINKS+=getdirentries.2 getdents.2 MLINKS+=getgid.2 getegid.2 MLINKS+=getitimer.2 setitimer.2 MLINKS+=getlogin.2 setlogin.2 diff --git a/lib/libc/sys/getdents.2 b/lib/libc/sys/getdents.2 deleted file mode 100644 index f347b63..0000000 --- a/lib/libc/sys/getdents.2 +++ /dev/null @@ -1,151 +0,0 @@ -.\" $NetBSD: getdents.2,v 1.4 1999/04/17 10:15:34 kleink Exp $ -.\" -.\" Copyright (c) 1989, 1991, 1993 -.\" The Regents of the University of California. All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, this list of conditions and the following disclaimer. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. All advertising materials mentioning features or use of this software -.\" must display the following acknowledgement: -.\" This product includes software developed by the University of -.\" California, Berkeley and its contributors. -.\" 4. Neither the name of the University nor the names of its contributors -.\" may be used to endorse or promote products derived from this software -.\" without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND -.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE -.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE -.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE -.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL -.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS -.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT -.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY -.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF -.\" SUCH DAMAGE. -.\" -.\" @(#)getdirentries.2 8.1 (Berkeley) 6/9/93 -.\" -.Dd June 9, 1993 -.Dt GETDENTS 2 -.Os -.Sh NAME -.Nm getdents -.Nd "get directory entries in a filesystem independent format" -.Sh SYNOPSIS -.Fd #include -.Ft int -.Fn getdents "int fd" "char *buf" "size_t nbytes" -.Sh DESCRIPTION -.Fn getdents -reads directory entries from the directory -referenced by the file descriptor -.Fa fd -into the buffer pointed to by -.Fa buf , -in a filesystem independent format. -Up to -.Fa nbytes -of data will be transferred. -.Fa nbytes -must be greater than or equal to the -block size associated with the file, -see -.Xr stat 2 . -Some filesystems may not support -.Fn getdents -with buffers smaller than this size. -.Pp -The data in the buffer is a series of -.Em dirent -structures each containing the following entries: -.Bd -literal -offset indent -unsigned long d_fileno; -unsigned short d_reclen; -unsigned short d_namlen; -char d_name[MAXNAMELEN + 1]; /* see below */ -.Ed -.Pp -The -.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 -.Xr link 2 ) -have the same -.Fa d_fileno . -The -.Fa d_reclen -entry is the length, in bytes, of the directory record. -The -.Fa d_name -entry contains a null terminated file name. -The -.Fa d_namlen -entry specifies the length of the file name excluding the null byte. -Thus the actual size of -.Fa d_name -may vary from 1 to -.Dv MAXNAMELEN -\&+ 1. -.Pp -Entries may be separated by extra space. -The -.Fa d_reclen -entry may be used as an offset from the start of a -.Fa dirent -structure to the next structure, if any. -.Pp -The actual number of bytes transferred is returned. -The current position pointer associated with -.Fa fd -is set to point to the next block of entries. -The pointer may not advance by the number of bytes returned by -.Fn getdents . -A value of zero is returned when -the end of the directory has been reached. -.Pp -The current position pointer may be set and retrieved by -.Xr lseek 2 . -The current position pointer should only be set to a value returned by -.Xr lseek 2 , -or zero. -.Sh RETURN VALUES -If successful, the number of bytes actually transferred is returned. -Otherwise, -1 is returned and the global variable -.Va errno -is set to indicate the error. -.Sh ERRORS -.Fn gtdents -will fail if: -.Bl -tag -width Er -.It Bq Er EBADF -.Fa fd -is not a valid file descriptor open for reading. -.It Bq Er EFAULT -Either -.Fa buf -points outside the allocated address space. -.It Bq Er EIO -An -.Tn I/O -error occurred while reading from or writing to the file system. -.It Bq Er EINVAL -A directory was being read on NFS, but it was modified on the server while -it was being read. -.El -.Sh SEE ALSO -.Xr open 2 , -.Xr lseek 2 -.Sh HISTORY -The -.Fn getdents -function first appeared in -.Nx 1.3 . diff --git a/lib/libc/sys/getdirentries.2 b/lib/libc/sys/getdirentries.2 index 4a17664..f9e5795 100644 --- a/lib/libc/sys/getdirentries.2 +++ b/lib/libc/sys/getdirentries.2 @@ -30,22 +30,28 @@ .\" SUCH DAMAGE. .\" .\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 -.\" $Id$ +.\" $Id: getdirentries.2,v 1.10 1999/07/12 20:48:23 nik Exp $ .\" .Dd May 3, 1995 .Dt GETDIRENTRIES 2 .Os .Sh NAME -.Nm getdirentries +.Nm getdirentries , +.Nm getdents .Nd "get directory entries in a filesystem independent format" .Sh SYNOPSIS .Fd #include .Fd #include .Ft int .Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" +.Ft int +.Fn getdents "int fd" "char *buf" "int nbytes" .Sh DESCRIPTION -.Fn Getdirentries -reads directory entries from the directory +The +.Fn getdirentries +and +.Fn getdents +functions read directory entries from the directory referenced by the file descriptor .Fa fd into the buffer pointed to by @@ -54,13 +60,13 @@ in a filesystem independent format. Up to .Fa nbytes of data will be transferred. -.Fa Nbytes -must be greater than or equal to the +The +.Fa nbytes +argument must be greater than or equal to the block size associated with the file, see .Xr stat 2 . -Some filesystems may not support -.Fn getdirentries +Some filesystems may not support these functions with buffers smaller than this size. .Pp The data in the buffer is a series of @@ -114,19 +120,23 @@ The current position pointer associated with .Fa fd is set to point to the next block of entries. The pointer may not advance by the number of bytes returned by -.Fn getdirentries . +.Fn getdirentries +or +.Fn getdents . A value of zero is returned when the end of the directory has been reached. .Pp -.Fn Getdirentries -writes the position of the block read into the location pointed to by +The +.Fn getdirentries +function writes the position of the block read into the location pointed to by .Fa basep . Alternatively, the current position pointer may be set and retrieved by .Xr lseek 2 . The current position pointer should only be set to a value returned by .Xr lseek 2 , a value returned in the location pointed to by -.Fa basep , +.Fa basep ( Ns Fn getdirentries +only) or zero. .Sh IMPLEMENTATION NOTES .Pp @@ -158,7 +168,7 @@ is set to indicate the error. .Sh ERRORS .Fn Getdirentries will fail if: -.Bl -tag -width [EFAULT] +.Bl -tag -width Er .It Bq Er EBADF .Fa fd is not a valid file descriptor open for reading. @@ -188,3 +198,7 @@ The .Fn getdirentries function first appeared in .Bx 4.4 . +The +.Fn getdents +function first appeared in +.Fx 3.0 . -- cgit v1.1