162899Sbostic.\" Copyright (c) 1989, 1991, 1993 262899Sbostic.\" The Regents of the University of California. All rights reserved. 338242Smckusick.\" 450487Scael.\" %sccs.include.redist.roff% 538242Smckusick.\" 6*69188Smckusick.\" @(#)getdirentries.2 8.2 (Berkeley) 05/03/95 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; 44*69188Smckusickunsigned char d_type; 45*69188Smckusickunsigned char d_namlen; 4647208Scaelchar d_name[MAXNAMELEN + 1]; /* see below */ 4747208Scael.Ed 4847208Scael.Pp 4938242SmckusickThe 5047208Scael.Fa d_fileno 5138242Smckusickentry is a number which is unique for each 5238242Smckusickdistinct file in the filesystem. 5338242SmckusickFiles that are linked by hard links (see 5447208Scael.Xr link 2 ) 5538242Smckusickhave the same 5647208Scael.Fa d_fileno . 5738242SmckusickThe 5847208Scael.Fa d_reclen 5938242Smckusickentry is the length, in bytes, of the directory record. 6038242SmckusickThe 61*69188Smckusick.Fa d_type 62*69188Smckusickentry is the type of the file pointed to by the directory record. 63*69188SmckusickThe file type values are defined in 64*69188Smckusick.Fa <sys/dirent.h> . 65*69188SmckusickThe 6647208Scael.Fa d_name 6738242Smckusickentry contains a null terminated file name. 6838242SmckusickThe 6947208Scael.Fa d_namlen 7038242Smckusickentry specifies the length of the file name excluding the null byte. 7138242SmckusickThus the actual size of 7247208Scael.Fa d_name 7347208Scaelmay vary from 1 to 7447208Scael.Dv MAXNAMELEN 7547208Scael\&+ 1. 7647208Scael.Pp 7738242SmckusickEntries may be separated by extra space. 7838242SmckusickThe 7947208Scael.Fa d_reclen 8038242Smckusickentry may be used as an offset from the start of a 8147208Scael.Fa dirent 8238242Smckusickstructure to the next structure, if any. 8347208Scael.Pp 8438242SmckusickThe actual number of bytes transferred is returned. 8538242SmckusickThe current position pointer associated with 8647208Scael.Fa fd 8738242Smckusickis set to point to the next block of entries. 8838242SmckusickThe pointer may not advance by the number of bytes returned by 8947208Scael.Fn getdirentries . 9038242SmckusickA value of zero is returned when 9138242Smckusickthe end of the directory has been reached. 9247208Scael.Pp 9347208Scael.Fn Getdirentries 9438242Smckusickwrites the position of the block read into the location pointed to by 9547208Scael.Fa basep . 9638242SmckusickAlternatively, the current position pointer may be set and retrieved by 9747208Scael.Xr lseek 2 . 9838242SmckusickThe current position pointer should only be set to a value returned by 9947208Scael.Xr lseek 2 , 10038242Smckusicka value returned in the location pointed to by 10147208Scael.Fa basep , 10238242Smckusickor zero. 10347208Scael.Sh RETURN VALUES 10438242SmckusickIf successful, the number of bytes actually transferred is returned. 10547208ScaelOtherwise, -1 is returned and the global variable 10647208Scael.Va errno 10738242Smckusickis set to indicate the error. 10847208Scael.Sh ERRORS 10947208Scael.Fn Getdirentries 11047208Scaelwill fail if: 11147208Scael.Bl -tag -width [EFAULT] 11247208Scael.It EBADF 11347208Scael.Fa fd 11447208Scaelis not a valid file descriptor open for reading. 11547208Scael.It EFAULT 11647208ScaelEither 11747208Scael.Fa buf 11847208Scaelor 11947208Scael.Fa basep 12047208Scaelpoint outside the allocated address space. 12147208Scael.It EIO 12250487ScaelAn 12350487Scael.Tn I/O 12450487Scaelerror occurred while reading from or writing to the file system. 12547208Scael.El 12647208Scael.Sh SEE ALSO 12747208Scael.Xr open 2 , 12847208Scael.Xr lseek 2 12947208Scael.Sh HISTORY 13047208ScaelThe 13150487Scael.Nm getdirentries 13262898Sbosticfunction first appeared in 4.4BSD. 133