path: root/usr/src/man/man3c/opendir.3c

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions and the original IEEE and The Open Group
.\" Standard, the original IEEE and The Open Group Standard is the referee
.\" document.  The original Standard can be obtained online at
.\" http://www.opengroup.org/unix/online.html.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Portions Copyright (c) 1992, X/Open Company Limited.  All Rights Reserved.
.\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
.\" Copyright 2021 Oxide Computer Company
.\"
.Dd February 25, 2021
.Dt OPENDIR 3C
.Os
.Sh NAME
.Nm opendir ,
.Nm fdopendir
.Nd open directory stream
.Sh SYNOPSIS
.In sys/types.h
.In dirent.h
.Ft "DIR *"
.Fo opendir
.Fa "dirname"
.Fc
.Ft "DIR *"
.Fo fdopendir
.Fa "int filedes"
.Fc
.Sh DESCRIPTION
The
.Fn opendir
and
.Fn fdopendir
functions are used to create seekable directory streams that can be used
to iterate over the contents of a directory, most commonly with
.Xr readdir 3C .
One can traverse and seek the stream with functions such as
.Xr seekdir 3C ,
.Xr telldir 3C ,
and
.Xr rewinddir 3C .
.Pp
The
.Fn opendir
function creates a directory stream from the path named by
.Fa dirname .
The
.Fn fdopendir
function creates a directory stream from an already opened file
descriptor,
.Fa filedes ,
that refers to a directory.
After successfully calling
.Fn fdopendir ,
.Fa filedes
belongs to the system and the application must not modify or close it in
any way.
.Pp
The new directory stream is positioned at the first entry.
When finished with the directory stream, the caller is responsible for
releasing its resources by calling the
.Xr closedir 3C
function.
This will close the directory stream's underlying file descriptor,
including
.Fa filedes
if
.Fn fdopendir
was used to create it.
In addition, memory associated with the directory stream, such as the
.Ft struct dirent
returned from
.Xr readdir 3C
will be invalid once a call to
.Xr closedir 3C
is completed.
.Pp
All directory streams are closed upon a successful call to any of the
.Xr exec 2
family of functions.
The underlying file descriptors behave as though the
.Dv FD_CLOEXEC
flag was set upon them.
.Pp
Directory streams created by the
.Fn opendir
function require an underlying file descriptor.
As a result, applications are only able to open up to a total of
.Brq Dv OPEN_MAX
files and directories.
.Sh RETURN VALUES
Upon successful completion, the
.Fn opendir
and
.Fn fdopendir
functions return a pointer to an object of type
Ft DIR .
Otherwise, a null pointer is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
The
.Fn opendir
function will fail if:
.Bl -tag -width Er
.It Er EACCES
Search permission is denied for any component of the path prefix of
.Fa dirname
or read permission is denied for
.Fa Idirname .
.It Er ELOOP
Too many symbolic links were encountered in resolving
.Fa path .
.It Er ENAMETOOLONG
The length of the
.Fa dirname
argument exceeds
.Brq Dv PATH_MAX ,
or a path name component is longer than
.Brq Dv NAME_MAX
while
.Brq Dv _POSIX_NO_TRUNC
is in effect.
.It Er ENOENT
A component of
.Fa dirname
does not name an existing directory or
.Fa dirname
is an empty string.
.It Er ENOTDIR
A component of
.Fa dirname
is not a directory.
.El
.Pp
The
.Fn fdopendir
function will fail if:
.Bl -tag -width Er
.It Er ENOTDIR
The file descriptor
.Fa filedes
does not reference a directory.
.El
.Pp
The
.Fn opendir
function may fail if:
.Bl -tag -width Er
.It Er EMFILE
There are already
.Brq Dv OPEN_MAX
file descriptors currently open in the calling process.
.It Er ENAMETOOLONG
Pathname resolution of a symbolic link produced an intermediate result whose
length exceeds
.Dv PATH_MAX .
.It Er ENFILE
Too many files are currently open on the system.
.El
.Sh INTERFACE STABILITY
.Sy Committed
.Sh MT-LEVEL
.Sy Safe
.Sh SEE ALSO
.Xr lstat 2 ,
.Xr symlink 2 ,
.Xr closedir 3C ,
.Xr readdir 3C ,
.Xr rewinddir 3C ,
.Xr seekdir 3C ,
.Xr telldir 3C ,
.Xr attributes 7