1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.roff% 5.\" 6.\" @(#)getdirentries.2 8.1 (Berkeley) 06/09/93 7.\" 8.Dd 9.Dt GETDIRENTRIES 2 10.Os 11.Sh NAME 12.Nm getdirentries 13.Nd "get directory entries in a filesystem independent format" 14.Sh SYNOPSIS 15.Fd #include <sys/dirent.h> 16.Ft int 17.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" 18.Sh DESCRIPTION 19.Fn Getdirentries 20reads directory entries from the directory 21referenced by the file descriptor 22.Fa fd 23into the buffer pointed to by 24.Fa buf , 25in a filesystem independent format. 26Up to 27.Fa nbytes 28of data will be transferred. 29.Fa Nbytes 30must be greater than or equal to the 31block size associated with the file, 32see 33.Xr stat 2 . 34Some filesystems may not support 35.Fn getdirentries 36with buffers smaller than this size. 37.Pp 38The data in the buffer is a series of 39.Em dirent 40structures each containing the following entries: 41.Bd -literal -offset indent 42unsigned long d_fileno; 43unsigned short d_reclen; 44unsigned short d_namlen; 45char d_name[MAXNAMELEN + 1]; /* see below */ 46.Ed 47.Pp 48The 49.Fa d_fileno 50entry is a number which is unique for each 51distinct file in the filesystem. 52Files that are linked by hard links (see 53.Xr link 2 ) 54have the same 55.Fa d_fileno . 56The 57.Fa d_reclen 58entry is the length, in bytes, of the directory record. 59The 60.Fa d_name 61entry contains a null terminated file name. 62The 63.Fa d_namlen 64entry specifies the length of the file name excluding the null byte. 65Thus the actual size of 66.Fa d_name 67may vary from 1 to 68.Dv MAXNAMELEN 69\&+ 1. 70.Pp 71Entries may be separated by extra space. 72The 73.Fa d_reclen 74entry may be used as an offset from the start of a 75.Fa dirent 76structure to the next structure, if any. 77.Pp 78The actual number of bytes transferred is returned. 79The current position pointer associated with 80.Fa fd 81is set to point to the next block of entries. 82The pointer may not advance by the number of bytes returned by 83.Fn getdirentries . 84A value of zero is returned when 85the end of the directory has been reached. 86.Pp 87.Fn Getdirentries 88writes the position of the block read into the location pointed to by 89.Fa basep . 90Alternatively, the current position pointer may be set and retrieved by 91.Xr lseek 2 . 92The current position pointer should only be set to a value returned by 93.Xr lseek 2 , 94a value returned in the location pointed to by 95.Fa basep , 96or zero. 97.Sh RETURN VALUES 98If successful, the number of bytes actually transferred is returned. 99Otherwise, -1 is returned and the global variable 100.Va errno 101is set to indicate the error. 102.Sh ERRORS 103.Fn Getdirentries 104will fail if: 105.Bl -tag -width [EFAULT] 106.It EBADF 107.Fa fd 108is not a valid file descriptor open for reading. 109.It EFAULT 110Either 111.Fa buf 112or 113.Fa basep 114point outside the allocated address space. 115.It EIO 116An 117.Tn I/O 118error occurred while reading from or writing to the file system. 119.El 120.Sh SEE ALSO 121.Xr open 2 , 122.Xr lseek 2 123.Sh HISTORY 124The 125.Nm getdirentries 126function first appeared in 4.4BSD. 127