147208Scael.\" Copyright (c) 1989, 1991 The Regents of the University of California. 238242Smckusick.\" All rights reserved. 338242Smckusick.\" 450487Scael.\" %sccs.include.redist.roff% 538242Smckusick.\" 6*62898Sbostic.\" @(#)getdirentries.2 6.6 (Berkeley) 06/09/93 738242Smckusick.\" 847208Scael.Dd 947208Scael.Dt GETDIRENTRIES 2 1050487Scael.Os 1147208Scael.Sh NAME 1247208Scael.Nm getdirentries 1347208Scael.Nd "get directory entries in a filesystem independent format" 1447208Scael.Sh SYNOPSIS 1547208Scael.Fd #include <sys/dirent.h> 1647208Scael.Ft int 1747208Scael.Fn getdirentries "int fd" "char *buf" "int nbytes" "long *basep" 1847208Scael.Sh DESCRIPTION 1947208Scael.Fn Getdirentries 2038242Smckusickreads directory entries from the directory 2138242Smckusickreferenced by the file descriptor 2247208Scael.Fa fd 2338242Smckusickinto the buffer pointed to by 2447208Scael.Fa buf , 2538242Smckusickin a filesystem independent format. 2638242SmckusickUp to 2747208Scael.Fa nbytes 2838242Smckusickof data will be transferred. 2947208Scael.Fa Nbytes 3038242Smckusickmust be greater than or equal to the 3138242Smckusickblock size associated with the file, 3238242Smckusicksee 3347208Scael.Xr stat 2 . 3438242SmckusickSome filesystems may not support 3547208Scael.Fn getdirentries 3638242Smckusickwith buffers smaller than this size. 3747208Scael.Pp 3838242SmckusickThe data in the buffer is a series of 3947208Scael.Em dirent 4038242Smckusickstructures each containing the following entries: 4147208Scael.Bd -literal -offset indent 4238242Smckusickunsigned long d_fileno; 4338242Smckusickunsigned short d_reclen; 4438242Smckusickunsigned short d_namlen; 4547208Scaelchar d_name[MAXNAMELEN + 1]; /* see below */ 4647208Scael.Ed 4747208Scael.Pp 4838242SmckusickThe 4947208Scael.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 5347208Scael.Xr link 2 ) 5438242Smckusickhave the same 5547208Scael.Fa d_fileno . 5638242SmckusickThe 5747208Scael.Fa d_reclen 5838242Smckusickentry is the length, in bytes, of the directory record. 5938242SmckusickThe 6047208Scael.Fa d_name 6138242Smckusickentry contains a null terminated file name. 6238242SmckusickThe 6347208Scael.Fa d_namlen 6438242Smckusickentry specifies the length of the file name excluding the null byte. 6538242SmckusickThus the actual size of 6647208Scael.Fa d_name 6747208Scaelmay vary from 1 to 6847208Scael.Dv MAXNAMELEN 6947208Scael\&+ 1. 7047208Scael.Pp 7138242SmckusickEntries may be separated by extra space. 7238242SmckusickThe 7347208Scael.Fa d_reclen 7438242Smckusickentry may be used as an offset from the start of a 7547208Scael.Fa dirent 7638242Smckusickstructure to the next structure, if any. 7747208Scael.Pp 7838242SmckusickThe actual number of bytes transferred is returned. 7938242SmckusickThe current position pointer associated with 8047208Scael.Fa fd 8138242Smckusickis set to point to the next block of entries. 8238242SmckusickThe pointer may not advance by the number of bytes returned by 8347208Scael.Fn getdirentries . 8438242SmckusickA value of zero is returned when 8538242Smckusickthe end of the directory has been reached. 8647208Scael.Pp 8747208Scael.Fn Getdirentries 8838242Smckusickwrites the position of the block read into the location pointed to by 8947208Scael.Fa basep . 9038242SmckusickAlternatively, the current position pointer may be set and retrieved by 9147208Scael.Xr lseek 2 . 9238242SmckusickThe current position pointer should only be set to a value returned by 9347208Scael.Xr lseek 2 , 9438242Smckusicka value returned in the location pointed to by 9547208Scael.Fa basep , 9638242Smckusickor zero. 9747208Scael.Sh RETURN VALUES 9838242SmckusickIf successful, the number of bytes actually transferred is returned. 9947208ScaelOtherwise, -1 is returned and the global variable 10047208Scael.Va errno 10138242Smckusickis set to indicate the error. 10247208Scael.Sh ERRORS 10347208Scael.Fn Getdirentries 10447208Scaelwill fail if: 10547208Scael.Bl -tag -width [EFAULT] 10647208Scael.It EBADF 10747208Scael.Fa fd 10847208Scaelis not a valid file descriptor open for reading. 10947208Scael.It EFAULT 11047208ScaelEither 11147208Scael.Fa buf 11247208Scaelor 11347208Scael.Fa basep 11447208Scaelpoint outside the allocated address space. 11547208Scael.It EIO 11650487ScaelAn 11750487Scael.Tn I/O 11850487Scaelerror occurred while reading from or writing to the file system. 11947208Scael.El 12047208Scael.Sh SEE ALSO 12147208Scael.Xr open 2 , 12247208Scael.Xr lseek 2 12347208Scael.Sh HISTORY 12447208ScaelThe 12550487Scael.Nm getdirentries 126*62898Sbosticfunction first appeared in 4.4BSD. 127