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.2 (Berkeley) 05/03/95 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 char d_type; 45unsigned char d_namlen; 46char d_name[MAXNAMELEN + 1]; /* see below */ 47.Ed 48.Pp 49The 50.Fa d_fileno 51entry is a number which is unique for each 52distinct file in the filesystem. 53Files that are linked by hard links (see 54.Xr link 2 ) 55have the same 56.Fa d_fileno . 57The 58.Fa d_reclen 59entry is the length, in bytes, of the directory record. 60The 61.Fa d_type 62entry is the type of the file pointed to by the directory record. 63The file type values are defined in 64.Fa <sys/dirent.h> . 65The 66.Fa d_name 67entry contains a null terminated file name. 68The 69.Fa d_namlen 70entry specifies the length of the file name excluding the null byte. 71Thus the actual size of 72.Fa d_name 73may vary from 1 to 74.Dv MAXNAMELEN 75\&+ 1. 76.Pp 77Entries may be separated by extra space. 78The 79.Fa d_reclen 80entry may be used as an offset from the start of a 81.Fa dirent 82structure to the next structure, if any. 83.Pp 84The actual number of bytes transferred is returned. 85The current position pointer associated with 86.Fa fd 87is set to point to the next block of entries. 88The pointer may not advance by the number of bytes returned by 89.Fn getdirentries . 90A value of zero is returned when 91the end of the directory has been reached. 92.Pp 93.Fn Getdirentries 94writes the position of the block read into the location pointed to by 95.Fa basep . 96Alternatively, the current position pointer may be set and retrieved by 97.Xr lseek 2 . 98The current position pointer should only be set to a value returned by 99.Xr lseek 2 , 100a value returned in the location pointed to by 101.Fa basep , 102or zero. 103.Sh RETURN VALUES 104If successful, the number of bytes actually transferred is returned. 105Otherwise, -1 is returned and the global variable 106.Va errno 107is set to indicate the error. 108.Sh ERRORS 109.Fn Getdirentries 110will fail if: 111.Bl -tag -width [EFAULT] 112.It EBADF 113.Fa fd 114is not a valid file descriptor open for reading. 115.It EFAULT 116Either 117.Fa buf 118or 119.Fa basep 120point outside the allocated address space. 121.It EIO 122An 123.Tn I/O 124error occurred while reading from or writing to the file system. 125.El 126.Sh SEE ALSO 127.Xr open 2 , 128.Xr lseek 2 129.Sh HISTORY 130The 131.Nm getdirentries 132function first appeared in 4.4BSD. 133