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

basename.1p (7379B)


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