1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)directory.3 8.1 (Berkeley) 06/04/93 7.\" 8.Dd 9.Dt DIRECTORY 3 10.Os BSD 4.2 11.Sh NAME 12.Nm opendir , 13.Nm readdir , 14.Nm telldir , 15.Nm seekdir , 16.Nm rewinddir , 17.Nm closedir , 18.Nm dirfd 19.Nd directory operations 20.Sh SYNOPSIS 21.Fd #include <sys/types.h> 22.Fd #include <dirent.h> 23.Ft DIR * 24.Fn opendir "const char *filename" 25.Ft struct dirent * 26.Fn readdir "DIR *dirp" 27.Ft long 28.Fn telldir "const DIR *dirp" 29.Ft void 30.Fn seekdir "DIR *dirp" "long loc" 31.Ft void 32.Fn rewinddir "DIR *dirp" 33.Ft int 34.Fn closedir "DIR *dirp" 35.Ft int 36.Fn dirfd "DIR *dirp" 37.Sh DESCRIPTION 38The 39.Fn opendir 40function 41opens the directory named by 42.Fa filename , 43associates a 44.Em directory stream 45with it 46and 47returns a pointer to be used to identify the 48.Em directory stream 49in subsequent operations. The pointer 50.Dv NULL 51is returned if 52.Fa filename 53cannot be accessed, or if it cannot 54.Xr malloc 3 55enough memory to hold the whole thing. 56.Pp 57The 58.Fn readdir 59function 60returns a pointer to the next directory entry. It returns 61.Dv NULL 62upon reaching the end of the directory or detecting an invalid 63.Fn seekdir 64operation. 65.Pp 66The 67.Fn telldir 68function 69returns the current location associated with the named 70.Em directory stream . 71.Pp 72The 73.Fn seekdir 74function 75sets the position of the next 76.Fn readdir 77operation on the 78.Em directory stream . 79The new position reverts to the one associated with the 80.Em directory stream 81when the 82.Fn telldir 83operation was performed. Values returned by 84.Fn telldir 85are good only for the lifetime of the 86.Dv DIR 87pointer, 88.Fa dirp , 89from which they are derived. 90If the directory is closed and then reopened, the 91.Fn telldir 92value may be invalidated due to undetected directory compaction. 93It is safe to use a previous 94.Fn telldir 95value immediately after a call to 96.Fn opendir 97and before any calls to 98.Fn readdir . 99.Pp 100The 101.Fn rewinddir 102function 103resets the position of the named 104.Em directory stream 105to the beginning of the directory. 106.Pp 107The 108.Fn closedir 109function 110closes the named 111.Em directory stream 112and frees the structure associated with the 113.Fa dirp 114pointer, 115returning 0 on success. 116On failure, \-1 is returned and the global variable 117.Va errno 118is set to indicate the error. 119.Pp 120The 121.Fn dirfd 122function 123returns the integer file descriptor associated with the named 124.Em directory stream , 125see 126.Xr open 2 . 127.Pp 128Sample code which searchs a directory for entry ``name'' is: 129.Bd -literal -offset indent 130len = strlen(name); 131dirp = opendir("."); 132while ((dp = readdir(dirp)) != NULL) 133 if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 134 (void)closedir(dirp); 135 return FOUND; 136 } 137(void)closedir(dirp); 138return NOT_FOUND; 139.Ed 140.Sh SEE ALSO 141.Xr open 2 , 142.Xr close 2 , 143.Xr read 2 , 144.Xr lseek 2 , 145.Xr dir 5 146.Sh HISTORY 147The 148.Fn opendir , 149.Fn readdir , 150.Fn telldir , 151.Fn seekdir , 152.Fn rewinddir , 153.Fn closedir , 154and 155.Fn dirfd 156functions appeared in 157.Bx 4.2 . 158