1*47208Scael.\" Copyright (c) 1989, 1991 The Regents of the University of California. 238242Smckusick.\" All rights reserved. 338242Smckusick.\" 443568Strent.\" %sccs.include.redist.man% 538242Smckusick.\" 6*47208Scael.\" @(#)getdirentries.2 6.4 (Berkeley) 03/10/91 738242Smckusick.\" 8*47208Scael.Dd 9*47208Scael.Dt GETDIRENTRIES 2 10*47208Scael.Os BSD 4.4 11*47208Scael.Sh NAME 12*47208Scael.Nm getdirentries 13*47208Scael.Nd "get directory entries in a filesystem independent format" 14*47208Scael.Sh SYNOPSIS 15*47208Scael.Fd #include <sys/dirent.h> 16*47208Scael.Ft int 17*47208Scael.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" 18*47208Scael.Sh DESCRIPTION 19*47208Scael.Fn Getdirentries 2038242Smckusickreads directory entries from the directory 2138242Smckusickreferenced by the file descriptor 22*47208Scael.Fa fd 2338242Smckusickinto the buffer pointed to by 24*47208Scael.Fa buf , 2538242Smckusickin a filesystem independent format. 2638242SmckusickUp to 27*47208Scael.Fa nbytes 2838242Smckusickof data will be transferred. 29*47208Scael.Fa Nbytes 3038242Smckusickmust be greater than or equal to the 3138242Smckusickblock size associated with the file, 3238242Smckusicksee 33*47208Scael.Xr stat 2 . 3438242SmckusickSome filesystems may not support 35*47208Scael.Fn getdirentries 3638242Smckusickwith buffers smaller than this size. 37*47208Scael.Pp 3838242SmckusickThe data in the buffer is a series of 39*47208Scael.Em dirent 4038242Smckusickstructures each containing the following entries: 41*47208Scael.Bd -literal -offset indent 4238242Smckusickunsigned long d_fileno; 4338242Smckusickunsigned short d_reclen; 4438242Smckusickunsigned short d_namlen; 45*47208Scaelchar d_name[MAXNAMELEN + 1]; /* see below */ 46*47208Scael.Ed 47*47208Scael.Pp 4838242SmckusickThe 49*47208Scael.Fa d_fileno 5038242Smckusickentry is a number which is unique for each 5138242Smckusickdistinct file in the filesystem. 5238242SmckusickFiles that are linked by hard links (see 53*47208Scael.Xr link 2 ) 5438242Smckusickhave the same 55*47208Scael.Fa d_fileno . 5638242SmckusickThe 57*47208Scael.Fa d_reclen 5838242Smckusickentry is the length, in bytes, of the directory record. 5938242SmckusickThe 60*47208Scael.Fa d_name 6138242Smckusickentry contains a null terminated file name. 6238242SmckusickThe 63*47208Scael.Fa d_namlen 6438242Smckusickentry specifies the length of the file name excluding the null byte. 6538242SmckusickThus the actual size of 66*47208Scael.Fa d_name 67*47208Scaelmay vary from 1 to 68*47208Scael.Dv MAXNAMELEN 69*47208Scael\&+ 1. 70*47208Scael.Pp 7138242SmckusickEntries may be separated by extra space. 7238242SmckusickThe 73*47208Scael.Fa d_reclen 7438242Smckusickentry may be used as an offset from the start of a 75*47208Scael.Fa dirent 7638242Smckusickstructure to the next structure, if any. 77*47208Scael.Pp 7838242SmckusickThe actual number of bytes transferred is returned. 7938242SmckusickThe current position pointer associated with 80*47208Scael.Fa fd 8138242Smckusickis set to point to the next block of entries. 8238242SmckusickThe pointer may not advance by the number of bytes returned by 83*47208Scael.Fn getdirentries . 8438242SmckusickA value of zero is returned when 8538242Smckusickthe end of the directory has been reached. 86*47208Scael.Pp 87*47208Scael.Fn Getdirentries 8838242Smckusickwrites the position of the block read into the location pointed to by 89*47208Scael.Fa basep . 9038242SmckusickAlternatively, the current position pointer may be set and retrieved by 91*47208Scael.Xr lseek 2 . 9238242SmckusickThe current position pointer should only be set to a value returned by 93*47208Scael.Xr lseek 2 , 9438242Smckusicka value returned in the location pointed to by 95*47208Scael.Fa basep , 9638242Smckusickor zero. 97*47208Scael.Sh RETURN VALUES 9838242SmckusickIf successful, the number of bytes actually transferred is returned. 99*47208ScaelOtherwise, -1 is returned and the global variable 100*47208Scael.Va errno 10138242Smckusickis set to indicate the error. 102*47208Scael.Sh ERRORS 103*47208Scael.Fn Getdirentries 104*47208Scaelwill fail if: 105*47208Scael.Bl -tag -width [EFAULT] 106*47208Scael.It EBADF 107*47208Scael.Fa fd 108*47208Scaelis not a valid file descriptor open for reading. 109*47208Scael.It EFAULT 110*47208ScaelEither 111*47208Scael.Fa buf 112*47208Scaelor 113*47208Scael.Fa basep 114*47208Scaelpoint outside the allocated address space. 115*47208Scael.It EIO 11638242SmckusickAn I/O error occurred while reading from or writing to the file system. 117*47208Scael.El 118*47208Scael.Sh SEE ALSO 119*47208Scael.Xr open 2 , 120*47208Scael.Xr lseek 2 121*47208Scael.Sh HISTORY 122*47208ScaelThe 123*47208Scael.Nm 124*47208Scaelfunction call is currently under development. 125