1*bac379f5Sbostic.\" Copyright (c) 1983, 1991, 1993 2*bac379f5Sbostic.\" The Regents of the University of California. All rights reserved. 390d38a43Smckusick.\" 45af5d383Strent.\" %sccs.include.redist.man% 5e17d9b00Sbostic.\" 6*bac379f5Sbostic.\" @(#)directory.3 8.1 (Berkeley) 06/04/93 790d38a43Smckusick.\" 8140d3953Scael.Dd 9140d3953Scael.Dt DIRECTORY 3 10140d3953Scael.Os BSD 4.2 11140d3953Scael.Sh NAME 12140d3953Scael.Nm opendir , 13140d3953Scael.Nm readdir , 14140d3953Scael.Nm telldir , 15140d3953Scael.Nm seekdir , 16140d3953Scael.Nm rewinddir , 17140d3953Scael.Nm closedir , 18140d3953Scael.Nm dirfd 19140d3953Scael.Nd directory operations 20140d3953Scael.Sh SYNOPSIS 21140d3953Scael.Fd #include <sys/types.h> 22140d3953Scael.Fd #include <dirent.h> 23140d3953Scael.Ft DIR * 24140d3953Scael.Fn opendir "const char *filename" 25c3e73fb3Sbostic.Ft struct dirent * 26140d3953Scael.Fn readdir "DIR *dirp" 27140d3953Scael.Ft long 28140d3953Scael.Fn telldir "const DIR *dirp" 29140d3953Scael.Ft void 30140d3953Scael.Fn seekdir "DIR *dirp" "long loc" 31140d3953Scael.Ft void 32140d3953Scael.Fn rewinddir "DIR *dirp" 33140d3953Scael.Ft int 34140d3953Scael.Fn closedir "DIR *dirp" 35140d3953Scael.Ft int 36140d3953Scael.Fn dirfd "DIR *dirp" 37140d3953Scael.Sh DESCRIPTION 38140d3953ScaelThe 39140d3953Scael.Fn opendir 40140d3953Scaelfunction 4190d38a43Smckusickopens the directory named by 42140d3953Scael.Fa filename , 43140d3953Scaelassociates a 44140d3953Scael.Em directory stream 45140d3953Scaelwith it 46140d3953Scaeland 4790d38a43Smckusickreturns a pointer to be used to identify the 48140d3953Scael.Em directory stream 4990d38a43Smckusickin subsequent operations. The pointer 50140d3953Scael.Dv NULL 5190d38a43Smckusickis returned if 52140d3953Scael.Fa filename 5390d38a43Smckusickcannot be accessed, or if it cannot 54140d3953Scael.Xr malloc 3 5590d38a43Smckusickenough memory to hold the whole thing. 56140d3953Scael.Pp 57140d3953ScaelThe 58140d3953Scael.Fn readdir 59140d3953Scaelfunction 6090d38a43Smckusickreturns a pointer to the next directory entry. It returns 61140d3953Scael.Dv NULL 6290d38a43Smckusickupon reaching the end of the directory or detecting an invalid 63140d3953Scael.Fn seekdir 6490d38a43Smckusickoperation. 65140d3953Scael.Pp 66140d3953ScaelThe 67140d3953Scael.Fn telldir 68140d3953Scaelfunction 6990d38a43Smckusickreturns the current location associated with the named 70140d3953Scael.Em directory stream . 71140d3953Scael.Pp 72140d3953ScaelThe 73140d3953Scael.Fn seekdir 74140d3953Scaelfunction 7590d38a43Smckusicksets the position of the next 76140d3953Scael.Fn readdir 7790d38a43Smckusickoperation on the 78140d3953Scael.Em directory stream . 7990d38a43SmckusickThe new position reverts to the one associated with the 80140d3953Scael.Em directory stream 8190d38a43Smckusickwhen the 82140d3953Scael.Fn telldir 8390d38a43Smckusickoperation was performed. Values returned by 84140d3953Scael.Fn telldir 85140d3953Scaelare good only for the lifetime of the 86140d3953Scael.Dv DIR 87140d3953Scaelpointer, 88140d3953Scael.Fa dirp , 89140d3953Scaelfrom which they are derived. 9090d38a43SmckusickIf the directory is closed and then reopened, the 91140d3953Scael.Fn telldir 9290d38a43Smckusickvalue may be invalidated due to undetected directory compaction. 9390d38a43SmckusickIt is safe to use a previous 94140d3953Scael.Fn telldir 9590d38a43Smckusickvalue immediately after a call to 96140d3953Scael.Fn opendir 9790d38a43Smckusickand before any calls to 98140d3953Scael.Fn readdir . 99140d3953Scael.Pp 100140d3953ScaelThe 101140d3953Scael.Fn rewinddir 102140d3953Scaelfunction 10390d38a43Smckusickresets the position of the named 104140d3953Scael.Em directory stream 10590d38a43Smckusickto the beginning of the directory. 106140d3953Scael.Pp 107140d3953ScaelThe 108140d3953Scael.Fn closedir 109140d3953Scaelfunction 11090d38a43Smckusickcloses the named 111140d3953Scael.Em directory stream 112140d3953Scaeland frees the structure associated with the 113140d3953Scael.Fa dirp 114140d3953Scaelpointer, 11529f6e5f0Sbosticreturning 0 on success. 116140d3953ScaelOn failure, \-1 is returned and the global variable 117140d3953Scael.Va errno 118140d3953Scaelis set to indicate the error. 119140d3953Scael.Pp 120140d3953ScaelThe 121140d3953Scael.Fn dirfd 122140d3953Scaelfunction 1230b32651dSbosticreturns the integer file descriptor associated with the named 124140d3953Scael.Em directory stream , 125140d3953Scaelsee 126140d3953Scael.Xr open 2 . 127140d3953Scael.Pp 12890d38a43SmckusickSample code which searchs a directory for entry ``name'' is: 129140d3953Scael.Bd -literal -offset indent 13090d38a43Smckusicklen = strlen(name); 13190d38a43Smckusickdirp = opendir("."); 132c4601917Sbosticwhile ((dp = readdir(dirp)) != NULL) 13390d38a43Smckusick if (dp->d_namlen == len && !strcmp(dp->d_name, name)) { 13429f6e5f0Sbostic (void)closedir(dirp); 13590d38a43Smckusick return FOUND; 13690d38a43Smckusick } 13729f6e5f0Sbostic(void)closedir(dirp); 13890d38a43Smckusickreturn NOT_FOUND; 139140d3953Scael.Ed 140140d3953Scael.Sh SEE ALSO 141140d3953Scael.Xr open 2 , 142140d3953Scael.Xr close 2 , 143140d3953Scael.Xr read 2 , 144140d3953Scael.Xr lseek 2 , 145140d3953Scael.Xr dir 5 146140d3953Scael.Sh HISTORY 147140d3953ScaelThe 148140d3953Scael.Fn opendir , 149140d3953Scael.Fn readdir , 150140d3953Scael.Fn telldir , 151140d3953Scael.Fn seekdir , 152140d3953Scael.Fn rewinddir , 153140d3953Scael.Fn closedir , 154140d3953Scaeland 155140d3953Scael.Fn dirfd 156140d3953Scaelfunctions appeared in 157140d3953Scael.Bx 4.2 . 158