man3/opendir.3

   1 .\" Copyright (C) 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" References consulted:
  26 .\"     Linux libc source code
  27 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
  28 .\"     386BSD man pages
  29 .\" Modified Sat Jul 24 18:46:01 1993 by Rik Faith (faith@cs.unc.edu)
  30 .\" Modified 11 June 1995 by Andries Brouwer (aeb@cwi.nl)
  31 .\" 2007-07-30 Ulrich Drepper <drepper@redhat.com>: document fdopendir().
  32 .TH OPENDIR 3  2016-03-15 "GNU" "Linux Programmer's Manual"
  33 .SH NAME
  34 opendir, fdopendir \- open a directory
  35 .SH SYNOPSIS
  36 .nf
  37 .B #include <sys/types.h>
  38 .br
  39 .B #include <dirent.h>
  40 .PP
  41 .BI "DIR *opendir(const char *" name );
  42 .BI "DIR *fdopendir(int " fd );
  43 .fi
  44 .PP
  45 .in -4n
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .in
  49 .PP
  50 .BR fdopendir ():
  51 .PD 0
  52 .ad l
  53 .RS 4
  54 .TP 4
  55 Since glibc 2.10:
  56 _POSIX_C_SOURCE\ >=\ 200809L
  57 .TP
  58 Before glibc 2.10:
  59 _GNU_SOURCE
  60 .RE
  61 .ad
  62 .PD
  63 .SH DESCRIPTION
  64 The
  65 .BR opendir ()
  66 function opens a directory stream corresponding to the
  67 directory \fIname\fP, and returns a pointer to the directory stream.
  68 The stream is positioned at the first entry in the directory.
  69 .PP
  70 The
  71 .BR fdopendir ()
  72 function
  73 is like
  74 .BR opendir (),
  75 but returns a directory stream for the directory referred
  76 to by the open file descriptor
  77 .IR fd .
  78 After a successful call to
  79 .BR fdopendir (),
  80 .I fd
  81 is used internally by the implementation,
  82 and should not otherwise be used by the application.
  83 .SH RETURN VALUE
  84 The
  85 .BR opendir ()
  86 and
  87 .BR fdopendir ()
  88 functions return a pointer to the directory stream.
  89 On error, NULL is returned, and
  90 .I errno
  91 is set appropriately.
  92 .SH ERRORS
  93 .TP
  94 .B EACCES
  95 Permission denied.
  96 .TP
  97 .B EBADF
  98 .I fd
  99 is not a valid file descriptor opened for reading.
 100 .TP
 101 .B EMFILE
 102 The per-process limit on the number of open file descriptors has been reached.
 103 .TP
 104 .B ENFILE
 105 The system-wide limit on the total number of open files has been reached.
 106 .TP
 107 .B ENOENT
 108 Directory does not exist, or \fIname\fP is an empty string.
 109 .TP
 110 .B ENOMEM
 111 Insufficient memory to complete the operation.
 112 .TP
 113 .B ENOTDIR
 114 \fIname\fP is not a directory.
 115 .SH VERSIONS
 116 .BR fdopendir ()
 117 is available in glibc since version 2.4.
 118 .SH ATTRIBUTES
 119 For an explanation of the terms used in this section, see
 120 .BR attributes (7).
 121 .TS
 122 allbox;
 123 lbw22 lb lb
 124 l l l.
 125 Interface       Attribute       Value
 126 T{
 127 .BR opendir (),
 128 .BR fdopendir ()
 129 T}      Thread safety   MT-Safe
 130 .TE
 131 .SH CONFORMING TO
 132 .BR opendir ()
 133 is present on SVr4, 4.3BSD, and specified in POSIX.1-2001.
 134 .BR fdopendir ()
 135 is specified in POSIX.1-2008.
 136 .SH NOTES
 137 Filename entries can be read from a directory stream using
 138 .BR readdir (3).
 139 .PP
 140 The underlying file descriptor of the directory stream can be obtained using
 141 .BR dirfd (3).
 142 .PP
 143 The
 144 .BR opendir ()
 145 function sets the close-on-exec flag for the file descriptor underlying the
 146 .IR "DIR *" .
 147 The
 148 .BR fdopendir ()
 149 function leaves the setting of the close-on-exec
 150 flag unchanged for the file descriptor,
 151 .IR fd .
 152 POSIX.1-200x leaves it unspecified whether a successful call to
 153 .BR fdopendir ()
 154 will set the close-on-exec flag for the file descriptor,
 155 .IR fd .
 156 .SH SEE ALSO
 157 .BR open (2),
 158 .BR closedir (3),
 159 .BR dirfd (3),
 160 .BR readdir (3),
 161 .BR rewinddir (3),
 162 .BR scandir (3),
 163 .BR seekdir (3),
 164 .BR telldir (3)