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