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

dirname.3p (4333B)

    

  1. '\" et
  2. .TH DIRNAME "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. dirname
  12. \(em report the parent directory name of a file pathname
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <libgen.h>
  17. .P
  18. char *dirname(char *\fIpath\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIdirname\fR()
  23. function shall take a pointer to a character string that contains a
  24. pathname, and return a pointer to a string that is a pathname of the
  25. parent directory of that file. The
  26. \fIdirname\fR()
  27. function shall not perform pathname resolution; the result shall not be
  28. affected by whether or not
  29. .IR path
  30. exists or by its file type. Trailing
  31. .BR '/' 
  32. characters in the path that are not also leading
  33. .BR '/' 
  34. characters shall not be counted as part of the path.
  35. .P
  36. If
  37. .IR path
  38. does not contain a
  39. .BR '/' ,
  40. then
  41. \fIdirname\fR()
  42. shall return a pointer to the string
  43. .BR \(dq.\(dq .
  44. If
  45. .IR path
  46. is a null pointer or points to an empty string,
  47. \fIdirname\fR()
  48. shall return a pointer to the string
  49. .BR \(dq.\(dq .
  50. .P
  51. The
  52. \fIdirname\fR()
  53. function may modify the string pointed to by
  54. .IR path ,
  55. and may return a pointer to static storage that may then be
  56. overwritten by a subsequent call to
  57. \fIdirname\fR().
  58. .P
  59. The
  60. \fIdirname\fR()
  61. function need not be thread-safe.
  62. .SH "RETURN VALUE"
  63. The
  64. \fIdirname\fR()
  65. function shall return a pointer to a string as described above.
  66. .P
  67. The
  68. \fIdirname\fR()
  69. function may modify the string pointed to by
  70. .IR path ,
  71. and may return a pointer to internal storage. The returned pointer
  72. might be invalidated or the storage might be overwritten by a
  73. subsequent call to
  74. \fIdirname\fR().
  75. The returned pointer might also be invalidated if the calling
  76. thread is terminated.
  77. .SH ERRORS
  78. No errors are defined.
  79. .LP
  80. .IR "The following sections are informative."
  81. .SH EXAMPLES
  82. The following code fragment reads a pathname, changes the current
  83. working directory to the parent directory, and opens the file.
  84. .sp
  85. .RS 4
  86. .nf
  88. char *path = NULL, *pathcopy;
  89. size_t buflen = 0;
  90. ssize_t linelen = 0;
  91. int fd;
  92. .P
  93. linelen = getline(&path, &buflen, stdin);
  94. .P
  95. path[linelen-1] = 0;
  96. pathcopy = strdup(path);
  97. if (chdir(dirname(pathcopy)) < 0) {
  98.     ...
  99. }
  100. if ((fd = open(basename(path), O_RDONLY)) >= 0) {
  101.     ...
  102.     close (fd);
  103. }
  104. \&...
  105. free (pathcopy);
  106. free (path);
  107. .fi
  108. .P
  109. .RE
  110. .P
  111. The EXAMPLES section of the
  112. \fIbasename\fR()
  113. function (see
  114. .IR "\fIbasename\fR\^(\|)")
  115. includes a table showing examples of the results of processing
  116. several sample pathnames by the
  117. \fIbasename\fR()
  118. and
  119. \fIdirname\fR()
  120. functions and by the
  121. .IR basename
  122. and
  123. .IR dirname
  124. utilities.
  125. .SH "APPLICATION USAGE"
  126. The
  127. \fIdirname\fR()
  128. and
  129. \fIbasename\fR()
  130. functions together yield a complete pathname. The expression
  131. \fIdirname\fP\^(\fIpath\fP) obtains the pathname of the directory where
  132. \fIbasename\fP\^(\fIpath\fP) is found.
  133. .P
  134. Since the meaning of the leading
  135. .BR \(dq//\(dq 
  136. is implementation-defined,
  137. .IR dirname ("\c
  138. .BR //foo ")
  139. may return either
  140. .BR \(dq//\(dq 
  141. or
  142. .BR '/' 
  143. (but nothing else).
  144. .SH RATIONALE
  145. None.
  146. .SH "FUTURE DIRECTIONS"
  147. None.
  148. .SH "SEE ALSO"
  149. .IR "\fIbasename\fR\^(\|)"
  150. .P
  151. The Base Definitions volume of POSIX.1\(hy2017,
  152. .IR "\fB<libgen.h>\fP"
  153. .P
  154. The Shell and Utilities volume of POSIX.1\(hy2017,
  155. .IR "\fIbasename\fR\^",
  156. .IR "\fIdirname\fR\^"
  157. .\"
  158. .SH COPYRIGHT
  159. Portions of this text are reprinted and reproduced in electronic form
  160. from IEEE Std 1003.1-2017, Standard for Information Technology
  161. -- Portable Operating System Interface (POSIX), The Open Group Base
  162. Specifications Issue 7, 2018 Edition,
  163. Copyright (C) 2018 by the Institute of
  164. Electrical and Electronics Engineers, Inc and The Open Group.
  165. In the event of any discrepancy between this version and the original IEEE and
  166. The Open Group Standard, the original IEEE and The Open Group Standard
  167. is the referee document. The original Standard can be obtained online at
  168. http://www.opengroup.org/unix/online.html .
  169. .PP
  170. Any typographical or formatting errors that appear
  171. in this page are most likely
  172. to have been introduced during the conversion of the source files to
  173. man page format. To report such errors, see
  174. https://www.kernel.org/doc/man-pages/reporting_bugs.html .