man3/opendir.3

   1 '\" t
   2 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" References consulted:
   7 .\"     Linux libc source code
   8 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   9 .\"     386BSD man pages
  10 .\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu)
  11 .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
  12 .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>: document fdopendir().
  13 .TH opendir 3 (date) "Linux man-pages (unreleased)"
  14 .SH NAME
  15 opendir, fdopendir \- open a directory
  16 .SH LIBRARY
  17 Standard C library
  18 .RI ( libc ", " \-lc )
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <sys/types.h>
  22 .B #include <dirent.h>
  23 .PP
  24 .BI "DIR *opendir(const char *" name );
  25 .BI "DIR *fdopendir(int " fd );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 .BR fdopendir ():
  34 .nf
  35     Since glibc 2.10:
  36         _POSIX_C_SOURCE >= 200809L
  37     Before glibc 2.10:
  38         _GNU_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 The
  42 .BR opendir ()
  43 function opens a directory stream corresponding to the
  44 directory \fIname\fP, and returns a pointer to the directory stream.
  45 The stream is positioned at the first entry in the directory.
  46 .PP
  47 The
  48 .BR fdopendir ()
  49 function
  50 is like
  51 .BR opendir (),
  52 but returns a directory stream for the directory referred
  53 to by the open file descriptor
  54 .IR fd .
  55 After a successful call to
  56 .BR fdopendir (),
  57 .I fd
  58 is used internally by the implementation,
  59 and should not otherwise be used by the application.
  60 .SH RETURN VALUE
  61 The
  62 .BR opendir ()
  63 and
  64 .BR fdopendir ()
  65 functions return a pointer to the directory stream.
  66 On error, NULL is returned, and
  67 .I errno
  68 is set to indicate the error.
  69 .SH ERRORS
  70 .TP
  71 .B EACCES
  72 Permission denied.
  73 .TP
  74 .B EBADF
  75 .I fd
  76 is not a valid file descriptor opened for reading.
  77 .TP
  78 .B EMFILE
  79 The per-process limit on the number of open file descriptors has been reached.
  80 .TP
  81 .B ENFILE
  82 The system-wide limit on the total number of open files has been reached.
  83 .TP
  84 .B ENOENT
  85 Directory does not exist, or \fIname\fP is an empty string.
  86 .TP
  87 .B ENOMEM
  88 Insufficient memory to complete the operation.
  89 .TP
  90 .B ENOTDIR
  91 \fIname\fP is not a directory.
  92 .SH ATTRIBUTES
  93 For an explanation of the terms used in this section, see
  94 .BR attributes (7).
  95 .TS
  96 allbox;
  97 lbx lb lb
  98 l l l.
  99 Interface       Attribute       Value
 100 T{
 101 .na
 102 .nh
 103 .BR opendir (),
 104 .BR fdopendir ()
 105 T}      Thread safety   MT-Safe
 106 .TE
 107 .sp 1
 108 .SH STANDARDS
 109 POSIX.1-2008.
 110 .SH STANDARDS
 111 .TP
 112 .BR opendir ()
 113 SVr4, 4.3BSD, POSIX.1-2001.
 114 .TP
 115 .BR fdopendir ()
 116 POSIX.1-2008.
 117 glibc 2.4.
 118 .SH NOTES
 119 Filename entries can be read from a directory stream using
 120 .BR readdir (3).
 121 .PP
 122 The underlying file descriptor of the directory stream can be obtained using
 123 .BR dirfd (3).
 124 .PP
 125 The
 126 .BR opendir ()
 127 function sets the close-on-exec flag for the file descriptor underlying the
 128 .IR "DIR *" .
 129 The
 130 .BR fdopendir ()
 131 function leaves the setting of the close-on-exec
 132 flag unchanged for the file descriptor,
 133 .IR fd .
 134 POSIX.1-200x leaves it unspecified whether a successful call to
 135 .BR fdopendir ()
 136 will set the close-on-exec flag for the file descriptor,
 137 .IR fd .
 138 .SH SEE ALSO
 139 .BR open (2),
 140 .BR closedir (3),
 141 .BR dirfd (3),
 142 .BR readdir (3),
 143 .BR rewinddir (3),
 144 .BR scandir (3),
 145 .BR seekdir (3),
 146 .BR telldir (3)