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.1p (6352B)


  1. '\" et
  2. .TH DIRNAME "1P" 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 return the directory portion of a pathname
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. dirname \fIstring\fR
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR string
  21. operand shall be treated as a pathname, as defined in the Base Definitions volume of POSIX.1\(hy2017,
  22. .IR "Section 3.271" ", " "Pathname".
  23. The string
  24. .IR string
  25. shall be converted to the name of the directory containing the
  26. filename corresponding to the last pathname component in
  27. .IR string ,
  28. performing actions equivalent to the following steps in order:
  29. .IP " 1." 4
  30. If
  31. .IR string
  32. is
  33. .BR // ,
  34. skip steps 2 to 5.
  35. .IP " 2." 4
  36. If
  37. .IR string
  38. consists entirely of
  39. <slash>
  40. characters,
  41. .IR string
  42. shall be set to a single
  43. <slash>
  44. character. In this case, skip steps 3 to 8.
  45. .IP " 3." 4
  46. If there are any trailing
  47. <slash>
  48. characters in
  49. .IR string ,
  50. they shall be removed.
  51. .IP " 4." 4
  52. If there are no
  53. <slash>
  54. characters remaining in
  55. .IR string ,
  56. .IR string
  57. shall be set to a single
  58. <period>
  59. character. In this case, skip steps 5 to 8.
  60. .IP " 5." 4
  61. If there are any trailing non-\c
  62. <slash>
  63. characters in
  64. .IR string ,
  65. they shall be removed.
  66. .IP " 6." 4
  67. If the remaining
  68. .IR string
  69. is
  70. .BR // ,
  71. it is implementation-defined whether steps 7 and 8 are skipped or
  72. processed.
  73. .IP " 7." 4
  74. If there are any trailing
  75. <slash>
  76. characters in
  77. .IR string ,
  78. they shall be removed.
  79. .IP " 8." 4
  80. If the remaining
  81. .IR string
  82. is empty,
  83. .IR string
  84. shall be set to a single
  85. <slash>
  86. character.
  87. .P
  88. The resulting string shall be written to standard output.
  89. .SH OPTIONS
  90. None.
  91. .SH OPERANDS
  92. The following operand shall be supported:
  93. .IP "\fIstring\fR" 10
  94. A string.
  95. .SH STDIN
  96. Not used.
  97. .SH "INPUT FILES"
  98. None.
  99. .SH "ENVIRONMENT VARIABLES"
  100. The following environment variables shall affect the execution of
  101. .IR dirname :
  102. .IP "\fILANG\fP" 10
  103. Provide a default value for the internationalization variables that are
  104. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  105. .IR "Section 8.2" ", " "Internationalization Variables"
  106. for the precedence of internationalization variables used to determine
  107. the values of locale categories.)
  108. .IP "\fILC_ALL\fP" 10
  109. If set to a non-empty string value, override the values of all the
  110. other internationalization variables.
  111. .IP "\fILC_CTYPE\fP" 10
  112. Determine the locale for the interpretation of sequences of bytes of
  113. text data as characters (for example, single-byte as opposed to
  114. multi-byte characters in arguments).
  115. .IP "\fILC_MESSAGES\fP" 10
  116. .br
  117. Determine the locale that should be used to affect the format and
  118. contents of diagnostic messages written to standard error.
  119. .IP "\fINLSPATH\fP" 10
  120. Determine the location of message catalogs for the processing of
  121. .IR LC_MESSAGES .
  122. .SH "ASYNCHRONOUS EVENTS"
  123. Default.
  124. .SH STDOUT
  125. The
  126. .IR dirname
  127. utility shall write a line to the standard output in the following
  128. format:
  129. .sp
  130. .RS 4
  131. .nf
  132. "%s\en", <\fIresulting string\fR>
  133. .fi
  134. .P
  135. .RE
  136. .SH STDERR
  137. The standard error shall be used only for diagnostic messages.
  138. .SH "OUTPUT FILES"
  139. None.
  140. .SH "EXTENDED DESCRIPTION"
  141. None.
  142. .SH "EXIT STATUS"
  143. The following exit values shall be returned:
  144. .IP "\00" 6
  145. Successful completion.
  146. .IP >0 6
  147. An error occurred.
  148. .SH "CONSEQUENCES OF ERRORS"
  149. Default.
  150. .LP
  151. .IR "The following sections are informative."
  152. .SH "APPLICATION USAGE"
  153. The definition of
  154. .IR pathname
  155. specifies implementation-defined behavior for pathnames starting with
  156. two
  157. <slash>
  158. characters. Therefore, applications shall not arbitrarily add
  159. <slash>
  160. characters to the beginning of a pathname unless they can ensure
  161. that there are more or less than two or are prepared to deal with the
  162. implementation-defined consequences.
  163. .SH EXAMPLES
  164. The EXAMPLES section of the
  165. \fIbasename\fR()
  166. function (see the System Interfaces volume of POSIX.1\(hy2017,
  167. .IR "\fIbasename\fR\^(\|)")
  168. includes a table showing examples of the results of processing several
  169. sample pathnames by the
  170. \fIbasename\fR()
  171. and
  172. \fIdirname\fR()
  173. functions and by the
  174. .IR basename
  175. and
  176. .IR dirname
  177. utilities.
  178. .P
  179. See also the examples for the
  180. .IR basename
  181. utility.
  182. .SH RATIONALE
  183. The behaviors of
  184. .IR basename
  185. and
  186. .IR dirname
  187. in this volume of POSIX.1\(hy2017 have been coordinated so that when
  188. .IR string
  189. is a valid pathname:
  190. .sp
  191. .RS 4
  192. .nf
  193. $(basename -- "\fIstring\fP")
  194. .fi
  195. .P
  196. .RE
  197. .P
  198. would be a valid filename for the file in the directory:
  199. .sp
  200. .RS 4
  201. .nf
  202. $(dirname -- "\fIstring\fP")
  203. .fi
  204. .P
  205. .RE
  206. .P
  207. This would not work for the versions of these utilities in early proposals
  208. due to the way processing of trailing
  209. <slash>
  210. characters was specified. Consideration was given to leaving processing
  211. unspecified if there were trailing
  212. <slash>
  213. characters, but this cannot be done; the Base Definitions volume of POSIX.1\(hy2017,
  214. .IR "Section 3.271" ", " "Pathname"
  215. allows trailing
  216. <slash>
  217. characters. The
  218. .IR basename
  219. and
  220. .IR dirname
  221. utilities have to specify consistent handling for all valid pathnames.
  222. .SH "FUTURE DIRECTIONS"
  223. None.
  224. .SH "SEE ALSO"
  225. .IR "Section 2.5" ", " "Parameters and Variables",
  226. .IR "\fIbasename\fR\^"
  227. .P
  228. The Base Definitions volume of POSIX.1\(hy2017,
  229. .IR "Section 3.271" ", " "Pathname",
  230. .IR "Chapter 8" ", " "Environment Variables"
  231. .P
  232. The System Interfaces volume of POSIX.1\(hy2017,
  233. .IR "\fIbasename\fR\^(\|)",
  234. .IR "\fIdirname\fR\^(\|)"
  235. .\"
  236. .SH COPYRIGHT
  237. Portions of this text are reprinted and reproduced in electronic form
  238. from IEEE Std 1003.1-2017, Standard for Information Technology
  239. -- Portable Operating System Interface (POSIX), The Open Group Base
  240. Specifications Issue 7, 2018 Edition,
  241. Copyright (C) 2018 by the Institute of
  242. Electrical and Electronics Engineers, Inc and The Open Group.
  243. In the event of any discrepancy between this version and the original IEEE and
  244. The Open Group Standard, the original IEEE and The Open Group Standard
  245. is the referee document. The original Standard can be obtained online at
  246. http://www.opengroup.org/unix/online.html .
  247. .PP
  248. Any typographical or formatting errors that appear
  249. in this page are most likely
  250. to have been introduced during the conversion of the source files to
  251. man page format. To report such errors, see
  252. https://www.kernel.org/doc/man-pages/reporting_bugs.html .