1DIRFD(3P)                  POSIX Programmer's Manual                 DIRFD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       dirfd — extract the file descriptor used by a DIR stream
13

SYNOPSIS

15       #include <dirent.h>
16
17       int dirfd(DIR *dirp);
18

DESCRIPTION

20       The dirfd() function shall return a file descriptor  referring  to  the
21       same  directory  as  the  dirp  argument. This file descriptor shall be
22       closed by a call to closedir().  If any attempt is made  to  close  the
23       file  descriptor, or to modify the state of the associated description,
24       other than by means of closedir(), readdir(), readdir_r(), rewinddir(),
25       or seekdir(), the behavior is undefined.
26

RETURN VALUE

28       Upon  successful completion, the dirfd() function shall return an inte‐
29       ger which contains a file descriptor for the stream pointed to by dirp.
30       Otherwise,  it  shall  return  -1  and  shall set errno to indicate the
31       error.
32

ERRORS

34       The dirfd() function may fail if:
35
36       EINVAL The dirp argument does not refer to a valid directory stream.
37
38       The following sections are informative.
39

EXAMPLES

41       None.
42

APPLICATION USAGE

44       The dirfd() function is intended to be a mechanism by which an applica‐
45       tion may obtain a file descriptor to use for the fchdir() function.
46

RATIONALE

48       This  interface  was  introduced because the Base Definitions volume of
49       POSIX.1‐2017 does not make public the DIR data structure.  Applications
50       tend  to  use  the fchdir() function on the file descriptor returned by
51       this interface, and this has proven useful  for  security  reasons;  in
52       particular,  it is a better technique than others where directory names
53       might change.
54
55       The description uses the term ``a file descriptor'' rather  than  ``the
56       file  descriptor''.  The implication intended is that an implementation
57       that does not use an fd for opendir() could still open() the  directory
58       to  implement  the  dirfd()  function. Such a descriptor must be closed
59       later during a call to closedir().
60
61       If it is necessary to allocate an fd to  be  returned  by  dirfd(),  it
62       should be done at the time of a call to opendir().
63

FUTURE DIRECTIONS

65       None.
66

SEE ALSO

68       closedir(), fchdir(), fdopendir(), fileno(), open(), readdir()
69
70       The Base Definitions volume of POSIX.1‐2017, <dirent.h>
71

73       Portions  of  this text are reprinted and reproduced in electronic form
74       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
75       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
76       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
77       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
78       event of any discrepancy between this version and the original IEEE and
79       The  Open Group Standard, the original IEEE and The Open Group Standard
80       is the referee document. The original Standard can be  obtained  online
81       at http://www.opengroup.org/unix/online.html .
82
83       Any  typographical  or  formatting  errors that appear in this page are
84       most likely to have been introduced during the conversion of the source
85       files  to  man page format. To report such errors, see https://www.ker‐
86       nel.org/doc/man-pages/reporting_bugs.html .
87
88
89
90IEEE/The Open Group                  2017                            DIRFD(3P)
Impressum