1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 4. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)getdirentries.2 8.2 (Berkeley) 5/3/95 29.\" $FreeBSD$ 30.\" 31.Dd May 3, 1995 32.Dt GETDIRENTRIES 2 33.Os 34.Sh NAME 35.Nm getdirentries , 36.Nm getdents 37.Nd "get directory entries in a file system independent format" 38.Sh LIBRARY 39.Lb libc 40.Sh SYNOPSIS 41.In sys/types.h 42.In dirent.h 43.Ft int 44.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" 45.Ft int 46.Fn getdents "int fd" "char *buf" "int nbytes" 47.Sh DESCRIPTION 48The 49.Fn getdirentries 50and 51.Fn getdents 52system calls read directory entries from the directory 53referenced by the file descriptor 54.Fa fd 55into the buffer pointed to by 56.Fa buf , 57in a file system independent format. 58Up to 59.Fa nbytes 60of data will be transferred. 61The 62.Fa nbytes 63argument must be greater than or equal to the 64block size associated with the file, 65see 66.Xr stat 2 . 67Some file systems may not support these system calls 68with buffers smaller than this size. 69.Pp 70The data in the buffer is a series of 71.Vt dirent 72structures each containing the following entries: 73.Bd -literal -offset indent 74uint32_t d_fileno; 75uint16_t d_reclen; 76uint8_t d_type; 77uint8_t d_namlen; 78char d_name[MAXNAMELEN + 1]; /* see below */ 79.Ed 80.Pp 81The 82.Fa d_fileno 83entry is a number which is unique for each 84distinct file in the file system. 85Files that are linked by hard links (see 86.Xr link 2 ) 87have the same 88.Fa d_fileno . 89The 90.Fa d_reclen 91entry is the length, in bytes, of the directory record. 92The 93.Fa d_type 94entry is the type of the file pointed to by the directory record. 95The file type values are defined in 96.Fa <sys/dirent.h> . 97The 98.Fa d_name 99entry contains a null terminated file name. 100The 101.Fa d_namlen 102entry specifies the length of the file name excluding the null byte. 103Thus the actual size of 104.Fa d_name 105may vary from 1 to 106.Dv MAXNAMELEN 107\&+ 1. 108.Pp 109Entries may be separated by extra space. 110The 111.Fa d_reclen 112entry may be used as an offset from the start of a 113.Fa dirent 114structure to the next structure, if any. 115.Pp 116The actual number of bytes transferred is returned. 117The current position pointer associated with 118.Fa fd 119is set to point to the next block of entries. 120The pointer may not advance by the number of bytes returned by 121.Fn getdirentries 122or 123.Fn getdents . 124A value of zero is returned when 125the end of the directory has been reached. 126.Pp 127The 128.Fn getdirentries 129system call writes the position of the block read into the location pointed to by 130.Fa basep . 131Alternatively, the current position pointer may be set and retrieved by 132.Xr lseek 2 . 133The current position pointer should only be set to a value returned by 134.Xr lseek 2 , 135a value returned in the location pointed to by 136.Fa basep 137.Fn ( getdirentries 138only) 139or zero. 140.Sh RETURN VALUES 141If successful, the number of bytes actually transferred is returned. 142Otherwise, -1 is returned and the global variable 143.Va errno 144is set to indicate the error. 145.Sh ERRORS 146The 147.Fn getdirentries 148system call 149will fail if: 150.Bl -tag -width Er 151.It Bq Er EBADF 152The 153.Fa fd 154argument 155is not a valid file descriptor open for reading. 156.It Bq Er EFAULT 157Either 158.Fa buf 159or 160.Fa basep 161point outside the allocated address space. 162.It Bq Er EINVAL 163The file referenced by 164.Fa fd 165is not a directory, or 166.Fa nbytes 167is too small for returning a directory entry or block of entries, 168or the current position pointer is invalid. 169.It Bq Er EIO 170An 171.Tn I/O 172error occurred while reading from or writing to the file system. 173.El 174.Sh SEE ALSO 175.Xr lseek 2 , 176.Xr open 2 177.Sh HISTORY 178The 179.Fn getdirentries 180system call first appeared in 181.Bx 4.4 . 182The 183.Fn getdents 184system call first appeared in 185.Fx 3.0 . 186