original/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  2010-06-20 "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 .sp
  41 .BI "DIR *opendir(const char *" name );
  42 .BI "DIR *fdopendir(int " fd );
  43 .fi
  44 .sp
  45 .in -4n
  46 Feature Test Macro Requirements for glibc (see
  47 .BR feature_test_macros (7)):
  48 .in
  49 .sp
  50 .BR fdopendir ():
  51 .PD 0
  52 .ad l
  53 .RS 4
  54 .TP 4
  55 Since glibc 2.10:
  56 _XOPEN_SOURCE\ >=\ 700 || _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
  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 Too many file descriptors in use by process.
 103 .TP
 104 .B ENFILE
 105 Too many files are currently open in the system.
 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 CONFORMING TO
 119 .BR opendir ()
 120 is present on SVr4, 4.3BSD, and specified in POSIX.1-2001.
 121 .BR fdopendir ()
 122 is specified in POSIX.1-2008.
 123 .SH NOTES
 124 The underlying file descriptor of the directory stream can be obtained using
 125 .BR dirfd (3).
 126
 127 The
 128 .BR opendir ()
 129 function sets the close-on-exec flag for the file descriptor underlying the
 130 .IR "DIR *" .
 131 The
 132 .BR fdopendir ()
 133 function leaves the setting of the close-on-exec
 134 flag unchanged for the file descriptor,
 135 .IR fd .
 136 POSIX.1-200x leaves it unspecified whether a successful call to
 137 .BR fdopendir ()
 138 will set the close-on-exec flag for the file descriptor,
 139 .IR fd .
 140 .SH SEE ALSO
 141 .BR open (2),
 142 .BR closedir (3),
 143 .BR dirfd (3),
 144 .BR readdir (3),
 145 .BR rewinddir (3),
 146 .BR scandir (3),
 147 .BR seekdir (3),
 148 .BR telldir (3)
 149 .SH COLOPHON
 150 This page is part of release 3.79 of the Linux
 151 .I man-pages
 152 project.
 153 A description of the project,
 154 information about reporting bugs,
 155 and the latest version of this page,
 156 can be found at
 157 \%http://www.kernel.org/doc/man\-pages/.