xref: /illumos-gate/usr/src/man/man3c/opendir.3c (revision bbf21555)
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 7
210