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.\" 3. 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 February 14, 2021 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 ssize_t 44.Fn getdirentries "int fd" "char *buf" "size_t nbytes" "off_t *basep" 45.Ft ssize_t 46.Fn getdents "int fd" "char *buf" "size_t 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 74ino_t d_fileno; 75off_t d_off; 76uint16_t d_reclen; 77uint8_t d_type; 78uint16_t d_namlen; 79char d_name[MAXNAMLEN + 1]; /* see below */ 80.Ed 81.Pp 82The 83.Fa d_fileno 84entry is a number which is unique for each 85distinct file in the file system. 86Files that are linked by hard links (see 87.Xr link 2 ) 88have the same 89.Fa d_fileno . 90The 91.Fa d_off 92field returns a cookie which, if non-zero, can be used with 93.Xr lseek 2 94to position the directory descriptor to the next entry. 95The 96.Fa d_reclen 97entry is the length, in bytes, of the directory record. 98The 99.Fa d_type 100entry is the type of the file pointed to by the directory record. 101The file type values are defined in 102.Fa <sys/dirent.h> . 103The 104.Fa d_name 105entry contains a null terminated file name. 106The 107.Fa d_namlen 108entry specifies the length of the file name excluding the null byte. 109Thus the actual size of 110.Fa d_name 111may vary from 1 to 112.Dv MAXNAMLEN 113\&+ 1. 114.Pp 115Entries may be separated by extra space. 116The 117.Fa d_reclen 118entry may be used as an offset from the start of a 119.Fa dirent 120structure to the next structure, if any. 121.Pp 122The actual number of bytes transferred is returned. 123The current position pointer associated with 124.Fa fd 125is set to point to the next block of entries. 126The pointer may not advance by the number of bytes returned by 127.Fn getdirentries 128or 129.Fn getdents . 130A value of zero is returned when 131the end of the directory has been reached. 132.Pp 133If the 134.Fa basep 135pointer value is non-NULL, 136the 137.Fn getdirentries 138system call writes the position of the block read into the location pointed to by 139.Fa basep . 140Alternatively, the current position pointer may be set and retrieved by 141.Xr lseek 2 . 142The current position pointer should only be set to a value returned by 143.Xr lseek 2 , 144a value returned in the location pointed to by 145.Fa basep 146.Po Fn getdirentries 147only 148.Pc , 149a value returned in the 150.Fa d_off 151field if it is non-zero, 152or zero. 153.Sh IMPLEMENTATION NOTES 154The 155.Fa d_off 156field is currently set to 0 by the NFS client, since the 157directory offset cookies returned by an NFS server cannot 158be used by 159.Xr lseek 2 160at this time. 161.Sh RETURN VALUES 162If successful, the number of bytes actually transferred is returned. 163Otherwise, -1 is returned and the global variable 164.Va errno 165is set to indicate the error. 166.Sh ERRORS 167The 168.Fn getdirentries 169system call 170will fail if: 171.Bl -tag -width Er 172.It Bq Er EBADF 173The 174.Fa fd 175argument 176is not a valid file descriptor open for reading. 177.It Bq Er EFAULT 178Either 179.Fa buf 180or non-NULL 181.Fa basep 182point outside the allocated address space. 183.It Bq Er EINVAL 184The file referenced by 185.Fa fd 186is not a directory, or 187.Fa nbytes 188is too small for returning a directory entry or block of entries, 189or the current position pointer is invalid. 190.It Bq Er EIO 191An 192.Tn I/O 193error occurred while reading from or writing to the file system. 194.It Bq Er EINTEGRITY 195Corrupted data was detected while reading from the file system. 196.El 197.Sh SEE ALSO 198.Xr lseek 2 , 199.Xr open 2 200.Sh HISTORY 201The 202.Fn getdirentries 203system call first appeared in 204.Bx 4.4 . 205The 206.Fn getdents 207system call first appeared in 208.Fx 3.0 . 209