logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

dirfd.3p (3585B)

    

  1. '\" et
  2. .TH DIRFD "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. dirfd
  12. \(em extract the file descriptor used by a DIR stream
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <dirent.h>
  17. .P
  18. int dirfd(DIR *\fIdirp\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIdirfd\fR()
  23. function shall return a file descriptor referring to the same directory
  24. as the
  25. .IR dirp
  26. argument. This file descriptor shall be closed by a call to
  27. \fIclosedir\fR().
  28. If any attempt is made to close the file descriptor, or to modify the
  29. state of the associated description, other than by means of
  30. \fIclosedir\fR(),
  31. \fIreaddir\fR(),
  32. \fIreaddir_r\fR(),
  33. \fIrewinddir\fR(),
  34. or
  35. \fIseekdir\fR(),
  36. the behavior is undefined.
  37. .SH "RETURN VALUE"
  38. Upon successful completion, the
  39. \fIdirfd\fR()
  40. function shall return an integer which contains a file descriptor for
  41. the stream pointed to by
  42. .IR dirp .
  43. Otherwise, it shall return \-1 and shall set
  44. .IR errno
  45. to indicate the error.
  46. .SH ERRORS
  47. The
  48. \fIdirfd\fR()
  49. function may fail if:
  50. .TP
  51. .BR EINVAL
  52. The
  53. .IR dirp
  54. argument does not refer to a valid directory stream.
  55. .LP
  56. .IR "The following sections are informative."
  57. .SH EXAMPLES
  58. None.
  59. .SH "APPLICATION USAGE"
  60. The
  61. \fIdirfd\fR()
  62. function is intended to be a mechanism by which an application may
  63. obtain a file descriptor to use for the
  64. \fIfchdir\fR()
  65. function.
  66. .SH RATIONALE
  67. This interface was introduced because the Base Definitions volume of POSIX.1\(hy2017 does not make public
  68. the
  69. .BR DIR
  70. data structure. Applications tend to use the
  71. \fIfchdir\fR()
  72. function on the file descriptor returned by this interface, and this
  73. has proven useful for security reasons; in particular, it is a better
  74. technique than others where directory names might change.
  75. .P
  76. The description uses the term ``a file descriptor'' rather than ``the
  77. file descriptor''. The implication intended is that an implementation
  78. that does not use an
  79. .IR fd
  80. for
  81. \fIopendir\fR()
  82. could still
  83. \fIopen\fR()
  84. the directory to implement the
  85. \fIdirfd\fR()
  86. function. Such a descriptor must be closed later during a call to
  87. \fIclosedir\fR().
  88. .P
  89. If it is necessary to allocate an
  90. .IR fd
  91. to be returned by
  92. \fIdirfd\fR(),
  93. it should be done at the time of a call to
  94. \fIopendir\fR().
  95. .SH "FUTURE DIRECTIONS"
  96. None.
  97. .SH "SEE ALSO"
  98. .IR "\fIclosedir\fR\^(\|)",
  99. .IR "\fIfchdir\fR\^(\|)",
  100. .IR "\fIfdopendir\fR\^(\|)",
  101. .IR "\fIfileno\fR\^(\|)",
  102. .IR "\fIopen\fR\^(\|)",
  103. .IR "\fIreaddir\fR\^(\|)"
  104. .P
  105. The Base Definitions volume of POSIX.1\(hy2017,
  106. .IR "\fB<dirent.h>\fP"
  107. .\"
  108. .SH COPYRIGHT
  109. Portions of this text are reprinted and reproduced in electronic form
  110. from IEEE Std 1003.1-2017, Standard for Information Technology
  111. -- Portable Operating System Interface (POSIX), The Open Group Base
  112. Specifications Issue 7, 2018 Edition,
  113. Copyright (C) 2018 by the Institute of
  114. Electrical and Electronics Engineers, Inc and The Open Group.
  115. In the event of any discrepancy between this version and the original IEEE and
  116. The Open Group Standard, the original IEEE and The Open Group Standard
  117. is the referee document. The original Standard can be obtained online at
  118. http://www.opengroup.org/unix/online.html .
  119. .PP
  120. Any typographical or formatting errors that appear
  121. in this page are most likely
  122. to have been introduced during the conversion of the source files to
  123. man page format. To report such errors, see
  124. https://www.kernel.org/doc/man-pages/reporting_bugs.html .