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

expr.1p (12259B)


  1. '\" et
  2. .TH EXPR "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. expr
  12. \(em evaluate arguments as an expression
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. expr \fIoperand\fR...
  17. .fi
  18. .SH DESCRIPTION
  19. The
  20. .IR expr
  21. utility shall evaluate an expression and write the result to standard
  22. output.
  23. .SH OPTIONS
  24. None.
  25. .SH OPERANDS
  26. The single expression evaluated by
  27. .IR expr
  28. shall be formed from the
  29. .IR operand
  30. operands, as described in the EXTENDED DESCRIPTION section. The
  31. application shall ensure that each of the expression operator symbols:
  32. .sp
  33. .RS 4
  34. .nf
  35. ( ) | & = > >= < <= != + - * / % :
  36. .fi
  37. .P
  38. .RE
  39. .P
  40. and the symbols
  41. .IR integer
  42. and
  43. .IR string
  44. in the table are provided as separate arguments to
  45. .IR expr .
  46. .SH STDIN
  47. Not used.
  48. .SH "INPUT FILES"
  49. None.
  50. .SH "ENVIRONMENT VARIABLES"
  51. The following environment variables shall affect the execution of
  52. .IR expr :
  53. .IP "\fILANG\fP" 10
  54. Provide a default value for the internationalization variables that are
  55. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  56. .IR "Section 8.2" ", " "Internationalization Variables"
  57. for the precedence of internationalization variables used to determine
  58. the values of locale categories.)
  59. .IP "\fILC_ALL\fP" 10
  60. If set to a non-empty string value, override the values of all the
  61. other internationalization variables.
  62. .IP "\fILC_COLLATE\fP" 10
  63. .br
  64. Determine the locale for the behavior of ranges, equivalence classes,
  65. and multi-character collating elements within regular expressions and
  66. by the string comparison operators.
  67. .IP "\fILC_CTYPE\fP" 10
  68. Determine the locale for the interpretation of sequences of bytes of
  69. text data as characters (for example, single-byte as opposed to
  70. multi-byte characters in arguments) and the behavior of character
  71. classes within regular expressions.
  72. .IP "\fILC_MESSAGES\fP" 10
  73. .br
  74. Determine the locale that should be used to affect the format and
  75. contents of diagnostic messages written to standard error.
  76. .IP "\fINLSPATH\fP" 10
  77. Determine the location of message catalogs for the processing of
  78. .IR LC_MESSAGES .
  79. .SH "ASYNCHRONOUS EVENTS"
  80. Default.
  81. .SH STDOUT
  82. The
  83. .IR expr
  84. utility shall evaluate the expression and write the result, followed by
  85. a
  86. <newline>,
  87. to standard output.
  88. .SH STDERR
  89. The standard error shall be used only for diagnostic messages.
  90. .SH "OUTPUT FILES"
  91. None.
  92. .SH "EXTENDED DESCRIPTION"
  93. The formation of the expression to be evaluated is shown in the
  94. following table. The symbols
  95. .IR expr ,
  96. .IR expr1 ,
  97. and
  98. .IR expr2
  99. represent expressions formed from
  100. .IR integer
  101. and
  102. .IR string
  103. symbols and the expression operator symbols (all separate arguments) by
  104. recursive application of the constructs described in the table. The
  105. expressions are listed in order of decreasing precedence, with
  106. equal-precedence operators grouped between horizontal lines. All of
  107. the operators shall be left-associative.
  108. .TS
  109. center tab(@) box;
  110. cB | cB
  111. l | lw(4i).
  112. Expression@Description
  113. _
  114. \fIinteger\fP@T{
  115. An argument consisting only of an (optional) unary minus followed
  116. by digits.
  117. T}
  118. \fIstring\fP@T{
  119. A string argument; see below.
  120. T}
  121. _
  122. (\ \fIexpr\fR\ )@T{
  123. Grouping symbols. Any expression can be placed within parentheses.
  124. Parentheses can be nested to a depth of
  125. {EXPR_NEST_MAX}.
  126. T}
  127. _
  128. \fIexpr1\fP\ :\ \fIexpr2\fP@T{
  129. Matching expression; see below.
  130. T}
  131. _
  132. \fIexpr1\fP\ *\ \fIexpr2\fP@T{
  133. Multiplication of decimal integer-valued arguments.
  134. T}
  135. \fIexpr1\fP\ /\ \fIexpr2\fP@T{
  136. Integer division of decimal integer-valued arguments, producing
  137. an integer result.
  138. T}
  139. \fIexpr1\fP\ %\ \fIexpr2\fP@T{
  140. Remainder of integer division of decimal integer-valued arguments.
  141. T}
  142. _
  143. \fIexpr1\fP\ +\ \fIexpr2\fP@T{
  144. Addition of decimal integer-valued arguments.
  145. T}
  146. \fIexpr1\fP\ \-\ \fIexpr2\fP@T{
  147. Subtraction of decimal integer-valued arguments.
  148. T}
  149. _
  150. @T{
  151. Returns the result of a decimal integer comparison if both arguments
  152. are integers; otherwise, returns the result of a string comparison
  153. using the locale-specific collation sequence. The result of each
  154. comparison is 1 if the specified relationship is true, or 0 if the
  155. relationship is false.
  156. T}
  157. \fIexpr1\fP\ =\ \fIexpr2\fR@Equal.
  158. \fIexpr1\fP\ >\ \fIexpr2\fR@Greater than.
  159. \fIexpr1\fP\ >=\ \fIexpr2\fR@Greater than or equal.
  160. \fIexpr1\fP\ <\ \fIexpr2\fR@Less than.
  161. \fIexpr1\fP\ <=\ \fIexpr2\fR@Less than or equal.
  162. \fIexpr1\fP\ !=\ \fIexpr2\fR@Not equal.
  163. _
  164. \fIexpr1\fP\ &\ \fIexpr2\fP@T{
  165. Returns the evaluation of
  166. .IR expr1
  167. if neither expression evaluates to null or zero; otherwise, returns zero.
  168. T}
  169. _
  170. \fIexpr1\fP\ |\ \fIexpr2\fP@T{
  171. Returns the evaluation of
  172. .IR expr1
  173. if it is neither null nor zero; otherwise, returns the evaluation of
  174. .IR expr2
  175. if it is not null; otherwise, zero.
  176. T}
  177. .TE
  178. .SS "Matching Expression"
  179. .P
  180. The
  181. .BR ':'
  182. matching operator shall compare the string resulting from the
  183. evaluation of
  184. .IR expr1
  185. with the regular expression pattern resulting from the evaluation of
  186. .IR expr2 .
  187. Regular expression syntax shall be that defined in the Base Definitions volume of POSIX.1\(hy2017,
  188. .IR "Section 9.3" ", " "Basic Regular Expressions",
  189. except that all patterns are anchored to the beginning of the string (that
  190. is, only sequences starting at the first character of a string are matched
  191. by the regular expression) and, therefore, it is unspecified whether
  192. .BR '\(ha'
  193. is a special character in that context. Usually, the matching operator
  194. shall return a string representing the number of characters matched (\c
  195. .BR '0'
  196. on failure). Alternatively, if the pattern contains at least one
  197. regular expression subexpression
  198. .BR \(dq[\e(...\e)]\(dq ,
  199. the string matched by the back-reference expression
  200. .BR \(dq\e1\(dq
  201. shall be returned. If the back-reference expression
  202. .BR \(dq\e1\(dq
  203. does not match, then the null string shall be returned.
  204. .SS "Identification as Integer or String"
  205. .P
  206. An argument or the value of a subexpression that consists only of an
  207. optional unary minus followed by digits is a candidate for treatment
  208. as an integer if it is used as the left argument to the
  209. .IR |
  210. operator or as either argument to any of the following operators:
  211. .IR "& = > >= < <= != + - * / %" .
  212. Otherwise, the argument or subexpression value shall be treated as a string.
  213. .P
  214. The use of string arguments
  215. .BR length ,
  216. .BR substr ,
  217. .BR index ,
  218. or
  219. .BR match
  220. produces unspecified results.
  221. .SH "EXIT STATUS"
  222. The following exit values shall be returned:
  223. .IP "\00" 6
  224. The
  225. .IR expression
  226. evaluates to neither null nor zero.
  227. .IP "\01" 6
  228. The
  229. .IR expression
  230. evaluates to null or zero.
  231. .IP "\02" 6
  232. Invalid
  233. .IR expression .
  234. .IP >2 6
  235. An error occurred.
  236. .SH "CONSEQUENCES OF ERRORS"
  237. Default.
  238. .LP
  239. .IR "The following sections are informative."
  240. .SH "APPLICATION USAGE"
  241. The
  242. .IR expr
  243. utility has a rather difficult syntax:
  244. .IP " *" 4
  245. Many of the operators are also shell control operators or reserved
  246. words, so they have to be escaped on the command line.
  247. .IP " *" 4
  248. Each part of the expression is composed of separate arguments, so
  249. liberal usage of
  250. <blank>
  251. characters is required. For example:
  252. .TS
  253. center tab(@) box;
  254. cB | cB
  255. lf5 | lf5.
  256. Invalid@Valid
  257. _
  258. \fIexpr\fR 1+2@\fIexpr\fR 1 + 2
  259. \fIexpr\fR "1 + 2"@\fIexpr\fR 1 + 2
  260. \fIexpr\fR 1 + (2 * 3)@\fIexpr\fR 1 + \e( 2 \e* 3 \e)\fR
  261. .TE
  262. .P
  263. In many cases, the arithmetic and string features provided as part of
  264. the shell command language are easier to use than their equivalents in
  265. .IR expr .
  266. Newly written scripts should avoid
  267. .IR expr
  268. in favor of the new features within the shell; see
  269. .IR "Section 2.5" ", " "Parameters and Variables"
  270. and
  271. .IR "Section 2.6.4" ", " "Arithmetic Expansion".
  272. .P
  273. After argument processing by the shell,
  274. .IR expr
  275. is not required to be able to tell the difference between an operator
  276. and an operand except by the value. If
  277. .BR \(dq$a\(dq
  278. is
  279. .BR '=' ,
  280. the command:
  281. .sp
  282. .RS 4
  283. .nf
  284. expr "$a" = \(aq=\(aq
  285. .fi
  286. .P
  287. .RE
  288. .P
  289. looks like:
  290. .sp
  291. .RS 4
  292. .nf
  293. expr = = =
  294. .fi
  295. .P
  296. .RE
  297. .P
  298. as the arguments are passed to
  299. .IR expr
  300. (and they all may be taken as the
  301. .BR '='
  302. operator). The following works reliably:
  303. .sp
  304. .RS 4
  305. .nf
  306. expr "X$a" = X=
  307. .fi
  308. .P
  309. .RE
  310. .P
  311. Also note that this volume of POSIX.1\(hy2017 permits implementations to extend utilities. The
  312. .IR expr
  313. utility permits the integer arguments to be preceded with a unary
  314. minus. This means that an integer argument could look like an option.
  315. Therefore, the conforming application must employ the
  316. .BR \(dq--\(dq
  317. construct of Guideline 10 of the Base Definitions volume of POSIX.1\(hy2017,
  318. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  319. to protect its operands if there is any chance the first operand might
  320. be a negative integer (or any string with a leading minus).
  321. .P
  322. For testing string equality the
  323. .IR test
  324. utility is preferred over
  325. .IR expr ,
  326. as it is usually implemented as a shell built-in. However, the
  327. functionality is not quite the same because the
  328. .IR expr
  329. .IR =
  330. and
  331. .IR !=
  332. operators check whether strings collate equally, whereas
  333. .IR test
  334. checks whether they are identical. Therefore, they can produce
  335. different results in locales where the collation sequence does not
  336. have a total ordering of all characters (see the Base Definitions volume of POSIX.1\(hy2017,
  337. .IR "Section 7.3.2" ", " "LC_COLLATE").
  338. .br
  339. .SH EXAMPLES
  340. The following command:
  341. .sp
  342. .RS 4
  343. .nf
  344. a=$(expr "$a" + 1)
  345. .fi
  346. .P
  347. .RE
  348. .P
  349. adds 1 to the variable
  350. .IR a .
  351. .P
  352. The following command, for
  353. .BR \(dq$a\(dq
  354. equal to either
  355. .BR /usr/abc/file
  356. or just
  357. .BR file :
  358. .sp
  359. .RS 4
  360. .nf
  361. expr $a : \(aq.*/\e(.*\e)\(aq \e| $a
  362. .fi
  363. .P
  364. .RE
  365. .P
  366. returns the last segment of a pathname (that is,
  367. .BR file ).
  368. Applications should avoid the character
  369. .BR '/'
  370. used alone as an argument;
  371. .IR expr
  372. may interpret it as the division operator.
  373. .P
  374. The following command:
  375. .sp
  376. .RS 4
  377. .nf
  378. expr "//$a" : \(aq.*/\e(.*\e)\(aq
  379. .fi
  380. .P
  381. .RE
  382. .P
  383. is a better representation of the previous example. The addition of
  384. the
  385. .BR \(dq//\(dq
  386. characters eliminates any ambiguity about the division operator and
  387. simplifies the whole expression. Also note that pathnames may contain
  388. characters contained in the
  389. .IR IFS
  390. variable and should be quoted to avoid having
  391. .BR \(dq$a\(dq
  392. expand into multiple arguments.
  393. .P
  394. The following command:
  395. .sp
  396. .RS 4
  397. .nf
  398. expr "X$VAR" : \(aq.*\(aq - 1
  399. .fi
  400. .P
  401. .RE
  402. .P
  403. returns the number of characters in
  404. .IR VAR .
  405. .SH RATIONALE
  406. In an early proposal, EREs were used in the matching expression syntax.
  407. This was changed to BREs to avoid breaking historical applications.
  408. .P
  409. The use of a leading
  410. <circumflex>
  411. in the BRE is unspecified because many historical implementations have
  412. treated it as a special character, despite their system documentation. For
  413. example:
  414. .sp
  415. .RS 4
  416. .nf
  417. expr foo : \(hafoo expr \(hafoo : \(hafoo
  418. .fi
  419. .P
  420. .RE
  421. .P
  422. return 3 and 0, respectively, on those systems; their documentation
  423. would imply the reverse. Thus, the anchoring condition is left
  424. unspecified to avoid breaking historical scripts relying on this
  425. undocumented feature.
  426. .SH "FUTURE DIRECTIONS"
  427. None.
  428. .SH "SEE ALSO"
  429. .IR "Section 2.5" ", " "Parameters and Variables",
  430. .IR "Section 2.6.4" ", " "Arithmetic Expansion"
  431. .P
  432. The Base Definitions volume of POSIX.1\(hy2017,
  433. .IR "Section 7.3.2" ", " "LC_COLLATE",
  434. .IR "Chapter 8" ", " "Environment Variables",
  435. .IR "Section 9.3" ", " "Basic Regular Expressions",
  436. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  437. .\"
  438. .SH COPYRIGHT
  439. Portions of this text are reprinted and reproduced in electronic form
  440. from IEEE Std 1003.1-2017, Standard for Information Technology
  441. -- Portable Operating System Interface (POSIX), The Open Group Base
  442. Specifications Issue 7, 2018 Edition,
  443. Copyright (C) 2018 by the Institute of
  444. Electrical and Electronics Engineers, Inc and The Open Group.
  445. In the event of any discrepancy between this version and the original IEEE and
  446. The Open Group Standard, the original IEEE and The Open Group Standard
  447. is the referee document. The original Standard can be obtained online at
  448. http://www.opengroup.org/unix/online.html .
  449. .PP
  450. Any typographical or formatting errors that appear
  451. in this page are most likely
  452. to have been introduced during the conversion of the source files to
  453. man page format. To report such errors, see
  454. https://www.kernel.org/doc/man-pages/reporting_bugs.html .