1.\" 2.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for 3.\" permission to reproduce portions of its copyrighted documentation. 4.\" Original documentation from The Open Group can be obtained online at 5.\" http://www.opengroup.org/bookstore/. 6.\" 7.\" The Institute of Electrical and Electronics Engineers and The Open 8.\" Group, have given us permission to reprint portions of their 9.\" documentation. 10.\" 11.\" In the following statement, the phrase ``this text'' refers to portions 12.\" of the system documentation. 13.\" 14.\" Portions of this text are reprinted and reproduced in electronic form 15.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition, 16.\" Standard for Information Technology -- Portable Operating System 17.\" Interface (POSIX), The Open Group Base Specifications Issue 6, 18.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics 19.\" Engineers, Inc and The Open Group. In the event of any discrepancy 20.\" between these versions and the original IEEE and The Open Group 21.\" Standard, the original IEEE and The Open Group Standard is the referee 22.\" document. The original Standard can be obtained online at 23.\" http://www.opengroup.org/unix/online.html. 24.\" 25.\" This notice shall appear on any product containing this material. 26.\" 27.\" The contents of this file are subject to the terms of the 28.\" Common Development and Distribution License (the "License"). 29.\" You may not use this file except in compliance with the License. 30.\" 31.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE 32.\" or http://www.opensolaris.org/os/licensing. 33.\" See the License for the specific language governing permissions 34.\" and limitations under the License. 35.\" 36.\" When distributing Covered Code, include this CDDL HEADER in each 37.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE. 38.\" If applicable, add the following below this CDDL HEADER, with the 39.\" fields enclosed by brackets "[]" replaced with your own identifying 40.\" information: Portions Copyright [yyyy] [name of copyright owner] 41.\" 42.\" 43.\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved. 44.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved. 45.\" Copyright 2021 Oxide Computer Company 46.\" 47.Dd February 25, 2021 48.Dt OPENDIR 3C 49.Os 50.Sh NAME 51.Nm opendir , 52.Nm fdopendir 53.Nd open directory stream 54.Sh SYNOPSIS 55.In sys/types.h 56.In dirent.h 57.Ft "DIR *" 58.Fo opendir 59.Fa "dirname" 60.Fc 61.Ft "DIR *" 62.Fo fdopendir 63.Fa "int filedes" 64.Fc 65.Sh DESCRIPTION 66The 67.Fn opendir 68and 69.Fn fdopendir 70functions are used to create seekable directory streams that can be used 71to iterate over the contents of a directory, most commonly with 72.Xr readdir 3C . 73One can traverse and seek the stream with functions such as 74.Xr seekdir 3C , 75.Xr telldir 3C , 76and 77.Xr rewinddir 3C . 78.Pp 79The 80.Fn opendir 81function creates a directory stream from the path named by 82.Fa dirname . 83The 84.Fn fdopendir 85function creates a directory stream from an already opened file 86descriptor, 87.Fa filedes , 88that refers to a directory. 89After successfully calling 90.Fn fdopendir , 91.Fa filedes 92belongs to the system and the application must not modify or close it in 93any way. 94.Pp 95The new directory stream is positioned at the first entry. 96When finished with the directory stream, the caller is responsible for 97releasing its resources by calling the 98.Xr closedir 3C 99function. 100This will close the directory stream's underlying file descriptor, 101including 102.Fa filedes 103if 104.Fn fdopendir 105was used to create it. 106In addition, memory associated with the directory stream, such as the 107.Ft struct dirent 108returned from 109.Xr readdir 3C 110will be invalid once a call to 111.Xr closedir 3C 112is completed. 113.Pp 114All directory streams are closed upon a successful call to any of the 115.Xr exec 2 116family of functions. 117The underlying file descriptors behave as though the 118.Dv FD_CLOEXEC 119flag was set upon them. 120.Pp 121Directory streams created by the 122.Fn opendir 123function require an underlying file descriptor. 124As a result, applications are only able to open up to a total of 125.Brq Dv OPEN_MAX 126files and directories. 127.Sh RETURN VALUES 128Upon successful completion, the 129.Fn opendir 130and 131.Fn fdopendir 132functions return a pointer to an object of type 133Ft DIR . 134Otherwise, a null pointer is returned and 135.Va errno 136is set to indicate the error. 137.Sh ERRORS 138The 139.Fn opendir 140function will fail if: 141.Bl -tag -width Er 142.It Er EACCES 143Search permission is denied for any component of the path prefix of 144.Fa dirname 145or read permission is denied for 146.Fa Idirname . 147.It Er ELOOP 148Too many symbolic links were encountered in resolving 149.Fa path . 150.It Er ENAMETOOLONG 151The length of the 152.Fa dirname 153argument exceeds 154.Brq Dv PATH_MAX , 155or a path name component is longer than 156.Brq Dv NAME_MAX 157while 158.Brq Dv _POSIX_NO_TRUNC 159is in effect. 160.It Er ENOENT 161A component of 162.Fa dirname 163does not name an existing directory or 164.Fa dirname 165is an empty string. 166.It Er ENOTDIR 167A component of 168.Fa dirname 169is not a directory. 170.El 171.Pp 172The 173.Fn fdopendir 174function will fail if: 175.Bl -tag -width Er 176.It Er ENOTDIR 177The file descriptor 178.Fa filedes 179does not reference a directory. 180.El 181.Pp 182The 183.Fn opendir 184function may fail if: 185.Bl -tag -width Er 186.It Er EMFILE 187There are already 188.Brq Dv OPEN_MAX 189file descriptors currently open in the calling process. 190.It Er ENAMETOOLONG 191Pathname resolution of a symbolic link produced an intermediate result whose 192length exceeds 193.Dv PATH_MAX . 194.It Er ENFILE 195Too many files are currently open on the system. 196.El 197.Sh INTERFACE STABILITY 198.Sy Committed 199.Sh MT-LEVEL 200.Sy Safe 201.Sh SEE ALSO 202.Xr lstat 2 , 203.Xr symlink 2 , 204.Xr closedir 3C , 205.Xr readdir 3C , 206.Xr rewinddir 3C , 207.Xr seekdir 3C , 208.Xr telldir 3C , 209.Xr attributes 5 210