1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. Neither the name of the University nor the names of its contributors 13.\" may be used to endorse or promote products derived from this software 14.\" without specific prior written permission. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26.\" SUCH DAMAGE. 27.\" 28.\" @(#)directory.3 8.1 (Berkeley) 6/4/93 29.\" $FreeBSD$ 30.\" 31.Dd August 31, 2016 32.Dt DIRECTORY 3 33.Os 34.Sh NAME 35.Nm opendir , 36.Nm fdopendir , 37.Nm readdir , 38.Nm readdir_r , 39.Nm telldir , 40.Nm seekdir , 41.Nm rewinddir , 42.Nm closedir , 43.Nm fdclosedir , 44.Nm dirfd 45.Nd directory operations 46.Sh LIBRARY 47.Lb libc 48.Sh SYNOPSIS 49.In dirent.h 50.Ft DIR * 51.Fn opendir "const char *filename" 52.Ft DIR * 53.Fn fdopendir "int fd" 54.Ft struct dirent * 55.Fn readdir "DIR *dirp" 56.Ft int 57.Fn readdir_r "DIR *dirp" "struct dirent *entry" "struct dirent **result" 58.Ft long 59.Fn telldir "DIR *dirp" 60.Ft void 61.Fn seekdir "DIR *dirp" "long loc" 62.Ft void 63.Fn rewinddir "DIR *dirp" 64.Ft int 65.Fn closedir "DIR *dirp" 66.Ft int 67.Fn fdclosedir "DIR *dirp" 68.Ft int 69.Fn dirfd "DIR *dirp" 70.Sh DESCRIPTION 71.Bf -symbolic 72The 73.Fn readdir_r 74interface is deprecated 75because it cannot be used correctly unless 76.Brq Va NAME_MAX 77is a fixed value. 78.Ef 79.Pp 80The 81.Fn opendir 82function 83opens the directory named by 84.Fa filename , 85associates a 86.Em directory stream 87with it 88and 89returns a pointer to be used to identify the 90.Em directory stream 91in subsequent operations. 92The pointer 93.Dv NULL 94is returned if 95.Fa filename 96cannot be accessed, or if it cannot 97.Xr malloc 3 98enough memory to hold the whole thing. 99.Pp 100The 101.Fn fdopendir 102function is equivalent to the 103.Fn opendir 104function except that the directory is specified by a file descriptor 105.Fa fd 106rather than by a name. 107The file offset associated with the file descriptor at the time of the call 108determines which entries are returned. 109.Pp 110Upon successful return from 111.Fn fdopendir , 112the file descriptor is under the control of the system, 113and if any attempt is made to close the file descriptor, 114or to modify the state of the associated description other than by means 115of 116.Fn closedir , 117.Fn readdir , 118.Fn readdir_r , 119or 120.Fn rewinddir , 121the behavior is undefined. 122Upon calling 123.Fn closedir 124the file descriptor is closed. 125The 126.Dv FD_CLOEXEC 127flag is set on the file descriptor by a successful call to 128.Fn fdopendir . 129.Pp 130The 131.Fn readdir 132function 133returns a pointer to the next directory entry. 134The directory entry remains valid until the next call to 135.Fn readdir 136or 137.Fn closedir 138on the same 139.Em directory stream . 140The function returns 141.Dv NULL 142upon reaching the end of the directory or on error. 143In the event of an error, 144.Va errno 145may be set to any of the values documented for the 146.Xr getdirentries 2 147system call. 148.Pp 149The 150.Fn readdir_r 151function 152provides the same functionality as 153.Fn readdir , 154but the caller must provide a directory 155.Fa entry 156buffer to store the results in. 157The buffer must be large enough for a 158.Vt struct dirent 159with a 160.Va d_name 161array with 162.Brq Va NAME_MAX 163+ 1 elements. 164If the read succeeds, 165.Fa result 166is pointed at the 167.Fa entry ; 168upon reaching the end of the directory 169.Fa result 170is set to 171.Dv NULL . 172The 173.Fn readdir_r 174function 175returns 0 on success or an error number to indicate failure. 176.Pp 177The 178.Fn telldir 179function 180returns a token representing the current location associated with the named 181.Em directory stream . 182Values returned by 183.Fn telldir 184are good only for the lifetime of the 185.Dv DIR 186pointer, 187.Fa dirp , 188from which they are derived. 189If the directory is closed and then 190reopened, prior values returned by 191.Fn telldir 192will no longer be valid. 193Values returned by 194.Fn telldir 195are also invalidated by a call to 196.Fn rewinddir . 197.Pp 198The 199.Fn seekdir 200function 201sets the position of the next 202.Fn readdir 203operation on the 204.Em directory stream . 205The new position reverts to the one associated with the 206.Em directory stream 207when the 208.Fn telldir 209operation was performed. 210.Pp 211The 212.Fn rewinddir 213function 214resets the position of the named 215.Em directory stream 216to the beginning of the directory. 217.Pp 218The 219.Fn closedir 220function 221closes the named 222.Em directory stream 223and frees the structure associated with the 224.Fa dirp 225pointer, 226returning 0 on success. 227On failure, \-1 is returned and the global variable 228.Va errno 229is set to indicate the error. 230.Pp 231The 232.Fn fdclosedir 233function is equivalent to the 234.Fn closedir 235function except that this function returns directory file descriptor instead of 236closing it. 237.Pp 238The 239.Fn dirfd 240function 241returns the integer file descriptor associated with the named 242.Em directory stream , 243see 244.Xr open 2 . 245.Pp 246Sample code which searches a directory for entry ``name'' is: 247.Bd -literal -offset indent 248dirp = opendir("."); 249if (dirp == NULL) 250 return (ERROR); 251len = strlen(name); 252while ((dp = readdir(dirp)) != NULL) { 253 if (dp->d_namlen == len && strcmp(dp->d_name, name) == 0) { 254 (void)closedir(dirp); 255 return (FOUND); 256 } 257} 258(void)closedir(dirp); 259return (NOT_FOUND); 260.Ed 261.Sh SEE ALSO 262.Xr close 2 , 263.Xr lseek 2 , 264.Xr open 2 , 265.Xr read 2 , 266.Xr dir 5 267.Sh HISTORY 268The 269.Fn opendir , 270.Fn readdir , 271.Fn telldir , 272.Fn seekdir , 273.Fn rewinddir , 274.Fn closedir , 275and 276.Fn dirfd 277functions appeared in 278.Bx 4.2 . 279The 280.Fn fdopendir 281function appeared in 282.Fx 8.0 . 283.Fn fdclosedir 284function appeared in 285.Fx 10.0 . 286.Sh BUGS 287The behaviour of 288.Fn telldir 289and 290.Fn seekdir 291is likely to be wrong if there are parallel unlinks happening 292and the directory is larger than one page. 293There is code to ensure that a 294.Fn seekdir 295to the location given by a 296.Fn telldir 297immediately before the last 298.Fn readdir 299will always set the correct location to return the same value as that last 300.Fn readdir 301performed. 302This is enough for some applications which want to "push back the last entry read" E.g. Samba. 303Seeks back to any other location, 304other than the beginning of the directory, 305may result in unexpected behaviour if deletes are present. 306It is hoped that this situation will be resolved with changes to 307.Fn getdirentries 308and the VFS. 309