Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1 | .\" $MirOS: src/bin/mksh/mksh.1,v 1.388 2016/01/20 22:04:54 tg Exp $ |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2 | .\" $OpenBSD: ksh.1,v 1.160 2015/07/04 13:27:04 feinerer Exp $ |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3 | .\"- |
| 4 | .\" Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 5 | .\" 2010, 2011, 2012, 2013, 2014, 2015, 2016 |
| 6 | .\" mirabilos <m@mirbsd.org> |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 7 | .\" |
| 8 | .\" Provided that these terms and disclaimer and all copyright notices |
| 9 | .\" are retained or reproduced in an accompanying document, permission |
| 10 | .\" is granted to deal in this work without restriction, including un‐ |
| 11 | .\" limited rights to use, publicly perform, distribute, sell, modify, |
| 12 | .\" merge, give away, or sublicence. |
| 13 | .\" |
| 14 | .\" This work is provided “AS IS” and WITHOUT WARRANTY of any kind, to |
| 15 | .\" the utmost extent permitted by applicable law, neither express nor |
| 16 | .\" implied; without malicious intent or gross negligence. In no event |
| 17 | .\" may a licensor, author or contributor be held liable for indirect, |
| 18 | .\" direct, other damage, loss, or other issues arising in any way out |
| 19 | .\" of dealing in the work, even if advised of the possibility of such |
| 20 | .\" damage or existence of a defect, except proven that it results out |
| 21 | .\" of said person’s immediate fault when using the work as intended. |
| 22 | .\"- |
| 23 | .\" Try to make GNU groff and AT&T nroff more compatible |
| 24 | .\" * ` generates ‘ in gnroff, so use \` |
| 25 | .\" * ' generates ’ in gnroff, \' generates ´, so use \*(aq |
| 26 | .\" * - generates ‐ in gnroff, \- generates −, so .tr it to - |
| 27 | .\" thus use - for hyphens and \- for minus signs and option dashes |
| 28 | .\" * ~ is size-reduced and placed atop in groff, so use \*(TI |
| 29 | .\" * ^ is size-reduced and placed atop in groff, so use \*(ha |
| 30 | .\" * \(en does not work in nroff, so use \*(en |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 31 | .\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba |
| 32 | .\" Also make sure to use \& especially with two-letter words. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 33 | .\" The section after the "doc" macropackage has been loaded contains |
| 34 | .\" additional code to convene between the UCB mdoc macropackage (and |
| 35 | .\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage. |
| 36 | .\" |
| 37 | .ie \n(.g \{\ |
| 38 | . if \*[.T]ascii .tr \-\N'45' |
| 39 | . if \*[.T]latin1 .tr \-\N'45' |
| 40 | . if \*[.T]utf8 .tr \-\N'45' |
| 41 | . ds <= \[<=] |
| 42 | . ds >= \[>=] |
| 43 | . ds Rq \[rq] |
| 44 | . ds Lq \[lq] |
| 45 | . ds sL \(aq |
| 46 | . ds sR \(aq |
| 47 | . if \*[.T]utf8 .ds sL ` |
| 48 | . if \*[.T]ps .ds sL ` |
| 49 | . if \*[.T]utf8 .ds sR ' |
| 50 | . if \*[.T]ps .ds sR ' |
| 51 | . ds aq \(aq |
| 52 | . ds TI \(ti |
| 53 | . ds ha \(ha |
| 54 | . ds en \(en |
| 55 | .\} |
| 56 | .el \{\ |
| 57 | . ds aq ' |
| 58 | . ds TI ~ |
| 59 | . ds ha ^ |
| 60 | . ds en \(em |
| 61 | .\} |
| 62 | .\" |
| 63 | .\" Implement .Dd with the Mdocdate RCS keyword |
| 64 | .\" |
| 65 | .rn Dd xD |
| 66 | .de Dd |
| 67 | .ie \\$1$Mdocdate: \{\ |
| 68 | . xD \\$2 \\$3, \\$4 |
| 69 | .\} |
| 70 | .el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 |
| 71 | .. |
| 72 | .\" |
| 73 | .\" .Dd must come before definition of .Mx, because when called |
| 74 | .\" with -mandoc, it might implement .Mx itself, but we want to |
| 75 | .\" use our own definition. And .Dd must come *first*, always. |
| 76 | .\" |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 77 | .Dd $Mdocdate: January 20 2016 $ |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 78 | .\" |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 79 | .\" Check which macro package we use, and do other -mdoc setup. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 80 | .\" |
| 81 | .ie \n(.g \{\ |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 82 | . if \*[.T]utf8 .tr \[la]\*(Lt |
| 83 | . if \*[.T]utf8 .tr \[ra]\*(Gt |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 84 | . ie d volume-ds-1 .ds tT gnu |
| 85 | . el .ds tT bsd |
| 86 | .\} |
| 87 | .el .ds tT ucb |
| 88 | .\" |
| 89 | .\" Implement .Mx (MirBSD) |
| 90 | .\" |
| 91 | .ie "\*(tT"gnu" \{\ |
| 92 | . eo |
| 93 | . de Mx |
| 94 | . nr curr-font \n[.f] |
| 95 | . nr curr-size \n[.ps] |
| 96 | . ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u] |
| 97 | . ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx] |
| 98 | . if !\n[arg-limit] \ |
| 99 | . if \n[.$] \{\ |
| 100 | . ds macro-name Mx |
| 101 | . parse-args \$@ |
| 102 | . \} |
| 103 | . if (\n[arg-limit] > \n[arg-ptr]) \{\ |
| 104 | . nr arg-ptr +1 |
| 105 | . ie (\n[type\n[arg-ptr]] == 2) \ |
| 106 | . as str-Mx1 \~\*[arg\n[arg-ptr]] |
| 107 | . el \ |
| 108 | . nr arg-ptr -1 |
| 109 | . \} |
| 110 | . ds arg\n[arg-ptr] "\*[str-Mx1] |
| 111 | . nr type\n[arg-ptr] 2 |
| 112 | . ds space\n[arg-ptr] "\*[space] |
| 113 | . nr num-args (\n[arg-limit] - \n[arg-ptr]) |
| 114 | . nr arg-limit \n[arg-ptr] |
| 115 | . if \n[num-args] \ |
| 116 | . parse-space-vector |
| 117 | . print-recursive |
| 118 | .. |
| 119 | . ec |
| 120 | . ds sP \s0 |
| 121 | . ds tN \*[Tn-font-size] |
| 122 | .\} |
| 123 | .el \{\ |
| 124 | . de Mx |
| 125 | . nr cF \\n(.f |
| 126 | . nr cZ \\n(.s |
| 127 | . ds aa \&\f\\n(cF\s\\n(cZ |
| 128 | . if \\n(aC==0 \{\ |
| 129 | . ie \\n(.$==0 \&MirOS\\*(aa |
| 130 | . el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9 |
| 131 | . \} |
| 132 | . if \\n(aC>\\n(aP \{\ |
| 133 | . nr aP \\n(aP+1 |
| 134 | . ie \\n(C\\n(aP==2 \{\ |
| 135 | . as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa |
| 136 | . ie \\n(aC>\\n(aP \{\ |
| 137 | . nr aP \\n(aP+1 |
| 138 | . nR |
| 139 | . \} |
| 140 | . el .aZ |
| 141 | . \} |
| 142 | . el \{\ |
| 143 | . as b1 \&MirOS\\*(aa |
| 144 | . nR |
| 145 | . \} |
| 146 | . \} |
| 147 | .. |
| 148 | .\} |
| 149 | .\"- |
| 150 | .Dt MKSH 1 |
| 151 | .Os MirBSD |
| 152 | .Sh NAME |
| 153 | .Nm mksh , |
| 154 | .Nm sh |
| 155 | .Nd MirBSD Korn shell |
| 156 | .Sh SYNOPSIS |
| 157 | .Nm |
| 158 | .Bk -words |
| 159 | .Op Fl +abCefhiklmnprUuvXx |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 160 | .Oo |
| 161 | .Fl T Oo Ar \&! Oc Ns Ar tty |
| 162 | \*(Ba |
| 163 | .Ar \&\- |
| 164 | .Oc |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 165 | .Op Fl +o Ar option |
| 166 | .Oo |
| 167 | .Fl c Ar string \*(Ba |
| 168 | .Fl s \*(Ba |
| 169 | .Ar file |
| 170 | .Op Ar argument ... |
| 171 | .Oc |
| 172 | .Ek |
| 173 | .Nm builtin-name |
| 174 | .Op Ar argument ... |
| 175 | .Sh DESCRIPTION |
| 176 | .Nm |
| 177 | is a command interpreter intended for both interactive and shell |
| 178 | script use. |
| 179 | Its command language is a superset of the |
| 180 | .Xr sh C |
| 181 | shell language and largely compatible to the original Korn shell. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 182 | At times, this manual page may give scripting advice; while it |
| 183 | sometimes does take portable shell scripting or various standards |
| 184 | into account all information is first and foremost presented with |
| 185 | .Nm |
| 186 | in mind and should be taken as such. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 187 | .Ss I'm an Android user, so what's mksh? |
| 188 | .Nm mksh |
| 189 | is a |
| 190 | .Ux |
| 191 | shell / command interpreter, similar to |
| 192 | .Nm COMMAND.COM |
| 193 | or |
| 194 | .Nm CMD.EXE , |
| 195 | which has been included with |
| 196 | .Tn Android Open Source Project |
| 197 | for a while now. |
| 198 | Basically, it's a program that runs in a terminal (console window), |
| 199 | takes user input and runs commands or scripts, which it can also |
| 200 | be asked to do by other programs, even in the background. |
| 201 | Any privilege pop-ups you might be encountering are thus not |
| 202 | .Nm mksh |
| 203 | issues but questions by some other program utilising it. |
| 204 | .Ss Invocation |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 205 | Most builtins can be called directly, for example if a link points from its |
| 206 | name to the shell; not all make sense, have been tested or work at all though. |
| 207 | .Pp |
| 208 | The options are as follows: |
| 209 | .Bl -tag -width XcXstring |
| 210 | .It Fl c Ar string |
| 211 | .Nm |
| 212 | will execute the command(s) contained in |
| 213 | .Ar string . |
| 214 | .It Fl i |
| 215 | Interactive shell. |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 216 | A shell that reads commands from standard input is |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 217 | .Dq interactive |
| 218 | if this |
| 219 | option is used or if both standard input and standard error are attached |
| 220 | to a |
| 221 | .Xr tty 4 . |
| 222 | An interactive shell has job control enabled, ignores the |
| 223 | .Dv SIGINT , |
| 224 | .Dv SIGQUIT , |
| 225 | and |
| 226 | .Dv SIGTERM |
| 227 | signals, and prints prompts before reading input (see the |
| 228 | .Ev PS1 |
| 229 | and |
| 230 | .Ev PS2 |
| 231 | parameters). |
| 232 | It also processes the |
| 233 | .Ev ENV |
| 234 | parameter or the |
| 235 | .Pa mkshrc |
| 236 | file (see below). |
| 237 | For non-interactive shells, the |
| 238 | .Ic trackall |
| 239 | option is on by default (see the |
| 240 | .Ic set |
| 241 | command below). |
| 242 | .It Fl l |
| 243 | Login shell. |
| 244 | If the basename the shell is called with (i.e. argv[0]) |
| 245 | starts with |
| 246 | .Ql \- |
| 247 | or if this option is used, |
| 248 | the shell is assumed to be a login shell; see |
| 249 | .Sx Startup files |
| 250 | below. |
| 251 | .It Fl p |
| 252 | Privileged shell. |
| 253 | A shell is |
| 254 | .Dq privileged |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 255 | if the real user ID or group ID does not match the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 256 | effective user ID or group ID (see |
| 257 | .Xr getuid 2 |
| 258 | and |
| 259 | .Xr getgid 2 ) . |
| 260 | Clearing the privileged option causes the shell to set |
| 261 | its effective user ID (group ID) to its real user ID (group ID). |
| 262 | For further implications, see |
| 263 | .Sx Startup files . |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 264 | If the shell is privileged and this flag is not explicitly set, the |
| 265 | .Dq privileged |
| 266 | option is cleared automatically after processing the startup files. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 267 | .It Fl r |
| 268 | Restricted shell. |
| 269 | A shell is |
| 270 | .Dq restricted |
| 271 | if this |
| 272 | option is used. |
| 273 | The following restrictions come into effect after the shell processes any |
| 274 | profile and |
| 275 | .Ev ENV |
| 276 | files: |
| 277 | .Pp |
| 278 | .Bl -bullet -compact |
| 279 | .It |
| 280 | The |
| 281 | .Ic cd |
| 282 | .Po and Ic chdir Pc |
| 283 | command is disabled. |
| 284 | .It |
| 285 | The |
| 286 | .Ev SHELL , |
| 287 | .Ev ENV , |
| 288 | and |
| 289 | .Ev PATH |
| 290 | parameters cannot be changed. |
| 291 | .It |
| 292 | Command names can't be specified with absolute or relative paths. |
| 293 | .It |
| 294 | The |
| 295 | .Fl p |
| 296 | option of the built-in command |
| 297 | .Ic command |
| 298 | can't be used. |
| 299 | .It |
| 300 | Redirections that create files can't be used (i.e.\& |
| 301 | .Ql \*(Gt , |
| 302 | .Ql \*(Gt\*(Ba , |
| 303 | .Ql \*(Gt\*(Gt , |
| 304 | .Ql \*(Lt\*(Gt ) . |
| 305 | .El |
| 306 | .It Fl s |
| 307 | The shell reads commands from standard input; all non-option arguments |
| 308 | are positional parameters. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 309 | .It Fl T Ar name |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 310 | Spawn |
| 311 | .Nm |
| 312 | on the |
| 313 | .Xr tty 4 |
| 314 | device given. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 315 | The paths |
| 316 | .Ar name , |
| 317 | .Pa /dev/ttyC Ns Ar name |
| 318 | and |
| 319 | .Pa /dev/tty Ns Ar name |
| 320 | are attempted in order. |
| 321 | Unless |
| 322 | .Ar name |
| 323 | begins with an exclamation mark |
| 324 | .Pq Sq \&! , |
| 325 | this is done in a subshell and returns immediately. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 326 | If |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 327 | .Ar name |
| 328 | is a dash |
| 329 | .Pq Sq \&\- , |
| 330 | detach from controlling terminal (daemonise) instead. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 331 | .El |
| 332 | .Pp |
| 333 | In addition to the above, the options described in the |
| 334 | .Ic set |
| 335 | built-in command can also be used on the command line: |
| 336 | both |
| 337 | .Op Fl +abCefhkmnuvXx |
| 338 | and |
| 339 | .Op Fl +o Ar option |
| 340 | can be used for single letter or long options, respectively. |
| 341 | .Pp |
| 342 | If neither the |
| 343 | .Fl c |
| 344 | nor the |
| 345 | .Fl s |
| 346 | option is specified, the first non-option argument specifies the name |
| 347 | of a file the shell reads commands from. |
| 348 | If there are no non-option |
| 349 | arguments, the shell reads commands from the standard input. |
| 350 | The name of the shell (i.e. the contents of $0) |
| 351 | is determined as follows: if the |
| 352 | .Fl c |
| 353 | option is used and there is a non-option argument, it is used as the name; |
| 354 | if commands are being read from a file, the file is used as the name; |
| 355 | otherwise, the basename the shell was called with (i.e. argv[0]) is used. |
| 356 | .Pp |
| 357 | The exit status of the shell is 127 if the command file specified on the |
| 358 | command line could not be opened, or non-zero if a fatal syntax error |
| 359 | occurred during the execution of a script. |
| 360 | In the absence of fatal errors, |
| 361 | the exit status is that of the last command executed, or zero, if no |
| 362 | command is executed. |
| 363 | .Ss Startup files |
| 364 | For the actual location of these files, see |
| 365 | .Sx FILES . |
| 366 | A login shell processes the system profile first. |
| 367 | A privileged shell then processes the suid profile. |
| 368 | A non-privileged login shell processes the user profile next. |
| 369 | A non-privileged interactive shell checks the value of the |
| 370 | .Ev ENV |
| 371 | parameter after subjecting it to parameter, command, arithmetic and tilde |
| 372 | .Pq Sq \*(TI |
| 373 | substitution; if unset or empty, the user mkshrc profile is processed; |
| 374 | otherwise, if a file whose name is the substitution result exists, |
| 375 | it is processed; non-existence is silently ignored. |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 376 | A privileged shell then drops privileges if neither was the |
| 377 | .Fl p |
| 378 | option given on the command line nor set during execution of the startup files. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 379 | .Ss Command syntax |
| 380 | The shell begins parsing its input by removing any backslash-newline |
| 381 | combinations, then breaking it into |
| 382 | .Em words . |
| 383 | Words (which are sequences of characters) are delimited by unquoted whitespace |
| 384 | characters (space, tab, and newline) or meta-characters |
| 385 | .Po |
| 386 | .Ql \*(Lt , |
| 387 | .Ql \*(Gt , |
| 388 | .Ql \*(Ba , |
| 389 | .Ql \&; , |
| 390 | .Ql \&( , |
| 391 | .Ql \&) , |
| 392 | and |
| 393 | .Ql & |
| 394 | .Pc . |
| 395 | Aside from delimiting words, spaces and tabs are ignored, while newlines |
| 396 | usually delimit commands. |
| 397 | The meta-characters are used in building the following |
| 398 | .Em tokens : |
| 399 | .Ql \*(Lt , |
| 400 | .Ql \*(Lt& , |
| 401 | .Ql \*(Lt\*(Lt , |
| 402 | .Ql \*(Lt\*(Lt\*(Lt , |
| 403 | .Ql \*(Gt , |
| 404 | .Ql \*(Gt& , |
| 405 | .Ql \*(Gt\*(Gt , |
| 406 | .Ql &\*(Gt , |
| 407 | etc. are used to specify redirections (see |
| 408 | .Sx Input/output redirection |
| 409 | below); |
| 410 | .Ql \*(Ba |
| 411 | is used to create pipelines; |
| 412 | .Ql \*(Ba& |
| 413 | is used to create co-processes (see |
| 414 | .Sx Co-processes |
| 415 | below); |
| 416 | .Ql \&; |
| 417 | is used to separate commands; |
| 418 | .Ql & |
| 419 | is used to create asynchronous pipelines; |
| 420 | .Ql && |
| 421 | and |
| 422 | .Ql \*(Ba\*(Ba |
| 423 | are used to specify conditional execution; |
| 424 | .Ql ;; , |
| 425 | .Ql ;&\& |
| 426 | and |
| 427 | .Ql ;\*(Ba\& |
| 428 | are used in |
| 429 | .Ic case |
| 430 | statements; |
| 431 | .Ql \&(( .. )) |
| 432 | is used in arithmetic expressions; |
| 433 | and lastly, |
| 434 | .Ql \&( .. )\& |
| 435 | is used to create subshells. |
| 436 | .Pp |
| 437 | Whitespace and meta-characters can be quoted individually using a backslash |
| 438 | .Pq Sq \e , |
| 439 | or in groups using double |
| 440 | .Pq Sq \&" |
| 441 | or single |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 442 | .Pq Dq \*(aq |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 443 | quotes. |
| 444 | Note that the following characters are also treated specially by the |
| 445 | shell and must be quoted if they are to represent themselves: |
| 446 | .Ql \e , |
| 447 | .Ql \&" , |
| 448 | .Ql \*(aq , |
| 449 | .Ql # , |
| 450 | .Ql $ , |
| 451 | .Ql \` , |
| 452 | .Ql \*(TI , |
| 453 | .Ql { , |
| 454 | .Ql } , |
| 455 | .Ql * , |
| 456 | .Ql \&? , |
| 457 | and |
| 458 | .Ql \&[ . |
| 459 | The first three of these are the above mentioned quoting characters (see |
| 460 | .Sx Quoting |
| 461 | below); |
| 462 | .Ql # , |
| 463 | if used at the beginning of a word, introduces a comment \*(en everything after |
| 464 | the |
| 465 | .Ql # |
| 466 | up to the nearest newline is ignored; |
| 467 | .Ql $ |
| 468 | is used to introduce parameter, command, and arithmetic substitutions (see |
| 469 | .Sx Substitution |
| 470 | below); |
| 471 | .Ql \` |
| 472 | introduces an old-style command substitution (see |
| 473 | .Sx Substitution |
| 474 | below); |
| 475 | .Ql \*(TI |
| 476 | begins a directory expansion (see |
| 477 | .Sx Tilde expansion |
| 478 | below); |
| 479 | .Ql { |
| 480 | and |
| 481 | .Ql } |
| 482 | delimit |
| 483 | .Xr csh 1 Ns -style |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 484 | alternations (see |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 485 | .Sx Brace expansion |
| 486 | below); |
| 487 | and finally, |
| 488 | .Ql * , |
| 489 | .Ql \&? , |
| 490 | and |
| 491 | .Ql \&[ |
| 492 | are used in file name generation (see |
| 493 | .Sx File name patterns |
| 494 | below). |
| 495 | .Pp |
| 496 | As words and tokens are parsed, the shell builds commands, of which there |
| 497 | are two basic types: |
| 498 | .Em simple-commands , |
| 499 | typically programmes that are executed, and |
| 500 | .Em compound-commands , |
| 501 | such as |
| 502 | .Ic for |
| 503 | and |
| 504 | .Ic if |
| 505 | statements, grouping constructs, and function definitions. |
| 506 | .Pp |
| 507 | A simple-command consists of some combination of parameter assignments |
| 508 | (see |
| 509 | .Sx Parameters |
| 510 | below), |
| 511 | input/output redirections (see |
| 512 | .Sx Input/output redirections |
| 513 | below), |
| 514 | and command words; the only restriction is that parameter assignments come |
| 515 | before any command words. |
| 516 | The command words, if any, define the command |
| 517 | that is to be executed and its arguments. |
| 518 | The command may be a shell built-in command, a function, |
| 519 | or an external command |
| 520 | (i.e. a separate executable file that is located using the |
| 521 | .Ev PATH |
| 522 | parameter; see |
| 523 | .Sx Command execution |
| 524 | below). |
| 525 | Note that all command constructs have an exit status: for external commands, |
| 526 | this is related to the status returned by |
| 527 | .Xr wait 2 |
| 528 | (if the command could not be found, the exit status is 127; if it could not |
| 529 | be executed, the exit status is 126); the exit status of other command |
| 530 | constructs (built-in commands, functions, compound-commands, pipelines, lists, |
| 531 | etc.) are all well-defined and are described where the construct is |
| 532 | described. |
| 533 | The exit status of a command consisting only of parameter |
| 534 | assignments is that of the last command substitution performed during the |
| 535 | parameter assignment or 0 if there were no command substitutions. |
| 536 | .Pp |
| 537 | Commands can be chained together using the |
| 538 | .Ql \*(Ba |
| 539 | token to form pipelines, in which the standard output of each command but the |
| 540 | last is piped (see |
| 541 | .Xr pipe 2 ) |
| 542 | to the standard input of the following command. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 543 | The exit status of a pipeline is that of its last command, unless the |
| 544 | .Ic pipefail |
| 545 | option is set (see there). |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 546 | All commands of a pipeline are executed in separate subshells; |
| 547 | this is allowed by POSIX but differs from both variants of |
| 548 | .At |
| 549 | .Nm ksh , |
| 550 | where all but the last command were executed in subshells; see the |
| 551 | .Ic read |
| 552 | builtin's description for implications and workarounds. |
| 553 | A pipeline may be prefixed by the |
| 554 | .Ql \&! |
| 555 | reserved word which causes the exit status of the pipeline to be logically |
| 556 | complemented: if the original status was 0, the complemented status will be 1; |
| 557 | if the original status was not 0, the complemented status will be 0. |
| 558 | .Pp |
| 559 | .Em Lists |
| 560 | of commands can be created by separating pipelines by any of the following |
| 561 | tokens: |
| 562 | .Ql && , |
| 563 | .Ql \*(Ba\*(Ba , |
| 564 | .Ql & , |
| 565 | .Ql \*(Ba& , |
| 566 | and |
| 567 | .Ql \&; . |
| 568 | The first two are for conditional execution: |
| 569 | .Dq Ar cmd1 No && Ar cmd2 |
| 570 | executes |
| 571 | .Ar cmd2 |
| 572 | only if the exit status of |
| 573 | .Ar cmd1 |
| 574 | is zero; |
| 575 | .Ql \*(Ba\*(Ba |
| 576 | is the opposite \*(en |
| 577 | .Ar cmd2 |
| 578 | is executed only if the exit status of |
| 579 | .Ar cmd1 |
| 580 | is non-zero. |
| 581 | .Ql && |
| 582 | and |
| 583 | .Ql \*(Ba\*(Ba |
| 584 | have equal precedence which is higher than that of |
| 585 | .Ql & , |
| 586 | .Ql \*(Ba& , |
| 587 | and |
| 588 | .Ql \&; , |
| 589 | which also have equal precedence. |
| 590 | Note that the |
| 591 | .Ql && |
| 592 | and |
| 593 | .Ql \*(Ba\*(Ba |
| 594 | operators are |
| 595 | .Qq left-associative . |
| 596 | For example, both of these commands will print only |
| 597 | .Qq bar : |
| 598 | .Bd -literal -offset indent |
| 599 | $ false && echo foo \*(Ba\*(Ba echo bar |
| 600 | $ true \*(Ba\*(Ba echo foo && echo bar |
| 601 | .Ed |
| 602 | .Pp |
| 603 | The |
| 604 | .Ql & |
| 605 | token causes the preceding command to be executed asynchronously; that is, |
| 606 | the shell starts the command but does not wait for it to complete (the shell |
| 607 | does keep track of the status of asynchronous commands; see |
| 608 | .Sx Job control |
| 609 | below). |
| 610 | When an asynchronous command is started when job control is disabled |
| 611 | (i.e. in most scripts), the command is started with signals |
| 612 | .Dv SIGINT |
| 613 | and |
| 614 | .Dv SIGQUIT |
| 615 | ignored and with input redirected from |
| 616 | .Pa /dev/null |
| 617 | (however, redirections specified in the asynchronous command have precedence). |
| 618 | The |
| 619 | .Ql \*(Ba& |
| 620 | operator starts a co-process which is a special kind of asynchronous process |
| 621 | (see |
| 622 | .Sx Co-processes |
| 623 | below). |
| 624 | Note that a command must follow the |
| 625 | .Ql && |
| 626 | and |
| 627 | .Ql \*(Ba\*(Ba |
| 628 | operators, while it need not follow |
| 629 | .Ql & , |
| 630 | .Ql \*(Ba& , |
| 631 | or |
| 632 | .Ql \&; . |
| 633 | The exit status of a list is that of the last command executed, with the |
| 634 | exception of asynchronous lists, for which the exit status is 0. |
| 635 | .Pp |
| 636 | Compound commands are created using the following reserved words. |
| 637 | These words |
| 638 | are only recognised if they are unquoted and if they are used as the first |
| 639 | word of a command (i.e. they can't be preceded by parameter assignments or |
| 640 | redirections): |
| 641 | .Bd -literal -offset indent |
| 642 | case else function then ! ( |
| 643 | do esac if time [[ (( |
| 644 | done fi in until { |
| 645 | elif for select while } |
| 646 | .Ed |
| 647 | .Pp |
| 648 | In the following compound command descriptions, command lists (denoted as |
| 649 | .Em list ) |
| 650 | that are followed by reserved words must end with a semicolon, a newline, or |
| 651 | a (syntactically correct) reserved word. |
| 652 | For example, the following are all valid: |
| 653 | .Bd -literal -offset indent |
| 654 | $ { echo foo; echo bar; } |
| 655 | $ { echo foo; echo bar\*(Ltnewline\*(Gt} |
| 656 | $ { { echo foo; echo bar; } } |
| 657 | .Ed |
| 658 | .Pp |
| 659 | This is not valid: |
| 660 | .Pp |
| 661 | .Dl $ { echo foo; echo bar } |
| 662 | .Bl -tag -width 4n |
| 663 | .It Pq Ar list |
| 664 | Execute |
| 665 | .Ar list |
| 666 | in a subshell. |
| 667 | There is no implicit way to pass environment changes from a |
| 668 | subshell back to its parent. |
| 669 | .It { Ar list ; No } |
| 670 | Compound construct; |
| 671 | .Ar list |
| 672 | is executed, but not in a subshell. |
| 673 | Note that |
| 674 | .Ql { |
| 675 | and |
| 676 | .Ql } |
| 677 | are reserved words, not meta-characters. |
| 678 | .It Xo case Ar word No in |
| 679 | .Oo Op \&( |
| 680 | .Ar pattern |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 681 | .Op \*(Ba Ar pattern |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 682 | .No ... Ns ) |
| 683 | .Ar list |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 684 | .Ic terminator |
| 685 | .Oc No ... esac |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 686 | .Xc |
| 687 | The |
| 688 | .Ic case |
| 689 | statement attempts to match |
| 690 | .Ar word |
| 691 | against a specified |
| 692 | .Ar pattern ; |
| 693 | the |
| 694 | .Ar list |
| 695 | associated with the first successfully matched pattern is executed. |
| 696 | Patterns used in |
| 697 | .Ic case |
| 698 | statements are the same as those used for file name patterns except that the |
| 699 | restrictions regarding |
| 700 | .Ql \&. |
| 701 | and |
| 702 | .Ql / |
| 703 | are dropped. |
| 704 | Note that any unquoted space before and after a pattern is |
| 705 | stripped; any space within a pattern must be quoted. |
| 706 | Both the word and the |
| 707 | patterns are subject to parameter, command, and arithmetic substitution, as |
| 708 | well as tilde substitution. |
| 709 | .Pp |
| 710 | For historical reasons, open and close braces may be used instead of |
| 711 | .Ic in |
| 712 | and |
| 713 | .Ic esac |
| 714 | e.g.\& |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 715 | .Ic case $foo { *) echo bar ;; } . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 716 | .Pp |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 717 | The list |
| 718 | .Ic terminator Ns s |
| 719 | are: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 720 | .Bl -tag -width 4n |
| 721 | .It Ql ;; |
| 722 | Terminate after the list. |
| 723 | .It Ql ;&\& |
| 724 | Fall through into the next list. |
| 725 | .It Ql ;\*(Ba\& |
| 726 | Evaluate the remaining pattern-list tuples. |
| 727 | .El |
| 728 | .Pp |
| 729 | The exit status of a |
| 730 | .Ic case |
| 731 | statement is that of the executed |
| 732 | .Ar list ; |
| 733 | if no |
| 734 | .Ar list |
| 735 | is executed, the exit status is zero. |
| 736 | .It Xo for Ar name |
| 737 | .Oo in Ar word No ... Oc ; |
| 738 | .No do Ar list ; No done |
| 739 | .Xc |
| 740 | For each |
| 741 | .Ar word |
| 742 | in the specified word list, the parameter |
| 743 | .Ar name |
| 744 | is set to the word and |
| 745 | .Ar list |
| 746 | is executed. |
| 747 | If |
| 748 | .Ic in |
| 749 | is not used to specify a word list, the positional parameters |
| 750 | ($1, $2, etc.)\& |
| 751 | are used instead. |
| 752 | For historical reasons, open and close braces may be used instead of |
| 753 | .Ic do |
| 754 | and |
| 755 | .Ic done |
| 756 | e.g.\& |
| 757 | .Ic for i; { echo $i; } . |
| 758 | The exit status of a |
| 759 | .Ic for |
| 760 | statement is the last exit status of |
| 761 | .Ar list ; |
| 762 | if |
| 763 | .Ar list |
| 764 | is never executed, the exit status is zero. |
| 765 | .It Xo if Ar list ; |
| 766 | .No then Ar list ; |
| 767 | .Oo elif Ar list ; |
| 768 | .No then Ar list ; Oc |
| 769 | .No ... |
| 770 | .Oo else Ar list ; Oc |
| 771 | .No fi |
| 772 | .Xc |
| 773 | If the exit status of the first |
| 774 | .Ar list |
| 775 | is zero, the second |
| 776 | .Ar list |
| 777 | is executed; otherwise, the |
| 778 | .Ar list |
| 779 | following the |
| 780 | .Ic elif , |
| 781 | if any, is executed with similar consequences. |
| 782 | If all the lists following the |
| 783 | .Ic if |
| 784 | and |
| 785 | .Ic elif Ns s |
| 786 | fail (i.e. exit with non-zero status), the |
| 787 | .Ar list |
| 788 | following the |
| 789 | .Ic else |
| 790 | is executed. |
| 791 | The exit status of an |
| 792 | .Ic if |
| 793 | statement is that of non-conditional |
| 794 | .Ar list |
| 795 | that is executed; if no non-conditional |
| 796 | .Ar list |
| 797 | is executed, the exit status is zero. |
| 798 | .It Xo select Ar name |
| 799 | .Oo in Ar word No ... Oc ; |
| 800 | .No do Ar list ; No done |
| 801 | .Xc |
| 802 | The |
| 803 | .Ic select |
| 804 | statement provides an automatic method of presenting the user with a menu and |
| 805 | selecting from it. |
| 806 | An enumerated list of the specified |
| 807 | .Ar word Ns (s) |
| 808 | is printed on standard error, followed by a prompt |
| 809 | .Po |
| 810 | .Ev PS3: normally |
| 811 | .Sq #?\ \& |
| 812 | .Pc . |
| 813 | A number corresponding to one of the enumerated words is then read from |
| 814 | standard input, |
| 815 | .Ar name |
| 816 | is set to the selected word (or unset if the selection is not valid), |
| 817 | .Ev REPLY |
| 818 | is set to what was read (leading/trailing space is stripped), and |
| 819 | .Ar list |
| 820 | is executed. |
| 821 | If a blank line (i.e. zero or more |
| 822 | .Ev IFS |
| 823 | octets) is entered, the menu is reprinted without executing |
| 824 | .Ar list . |
| 825 | .Pp |
| 826 | When |
| 827 | .Ar list |
| 828 | completes, the enumerated list is printed if |
| 829 | .Ev REPLY |
| 830 | is |
| 831 | .Dv NULL , |
| 832 | the prompt is printed, and so on. |
| 833 | This process continues until an end-of-file |
| 834 | is read, an interrupt is received, or a |
| 835 | .Ic break |
| 836 | statement is executed inside the loop. |
| 837 | If |
| 838 | .Dq in word ... |
| 839 | is omitted, the positional parameters are used |
| 840 | (i.e. $1, $2, etc.). |
| 841 | For historical reasons, open and close braces may be used instead of |
| 842 | .Ic do |
| 843 | and |
| 844 | .Ic done |
| 845 | e.g.\& |
| 846 | .Ic select i; { echo $i; } . |
| 847 | The exit status of a |
| 848 | .Ic select |
| 849 | statement is zero if a |
| 850 | .Ic break |
| 851 | statement is used to exit the loop, non-zero otherwise. |
| 852 | .It Xo until Ar list ; |
| 853 | .No do Ar list ; |
| 854 | .No done |
| 855 | .Xc |
| 856 | This works like |
| 857 | .Ic while , |
| 858 | except that the body is executed only while the exit status of the first |
| 859 | .Ar list |
| 860 | is non-zero. |
| 861 | .It Xo while Ar list ; |
| 862 | .No do Ar list ; |
| 863 | .No done |
| 864 | .Xc |
| 865 | A |
| 866 | .Ic while |
| 867 | is a pre-checked loop. |
| 868 | Its body is executed as often as the exit status of the first |
| 869 | .Ar list |
| 870 | is zero. |
| 871 | The exit status of a |
| 872 | .Ic while |
| 873 | statement is the last exit status of the |
| 874 | .Ar list |
| 875 | in the body of the loop; if the body is not executed, the exit status is zero. |
| 876 | .It Xo function Ar name |
| 877 | .No { Ar list ; No } |
| 878 | .Xc |
| 879 | Defines the function |
| 880 | .Ar name |
| 881 | (see |
| 882 | .Sx Functions |
| 883 | below). |
| 884 | Note that redirections specified after a function definition are |
| 885 | performed whenever the function is executed, not when the function definition |
| 886 | is executed. |
| 887 | .It Ar name Ns \&() Ar command |
| 888 | Mostly the same as |
| 889 | .Ic function |
| 890 | (see |
| 891 | .Sx Functions |
| 892 | below). |
| 893 | Whitespace (space or tab) after |
| 894 | .Ar name |
| 895 | will be ignored most of the time. |
| 896 | .It Xo function Ar name Ns \&() |
| 897 | .No { Ar list ; No } |
| 898 | .Xc |
| 899 | The same as |
| 900 | .Ar name Ns \&() |
| 901 | .Pq Nm bash Ns ism . |
| 902 | The |
| 903 | .Ic function |
| 904 | keyword is ignored. |
| 905 | .It Xo Ic time Op Fl p |
| 906 | .Op Ar pipeline |
| 907 | .Xc |
| 908 | The |
| 909 | .Sx Command execution |
| 910 | section describes the |
| 911 | .Ic time |
| 912 | reserved word. |
| 913 | .It \&(( Ar expression No )) |
| 914 | The arithmetic expression |
| 915 | .Ar expression |
| 916 | is evaluated; equivalent to |
| 917 | .Dq let expression |
| 918 | (see |
| 919 | .Sx Arithmetic expressions |
| 920 | and the |
| 921 | .Ic let |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 922 | command, below) in a compound construct. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 923 | .It Bq Bq Ar \ \&expression\ \& |
| 924 | Similar to the |
| 925 | .Ic test |
| 926 | and |
| 927 | .Ic \&[ ... \&] |
| 928 | commands (described later), with the following exceptions: |
| 929 | .Bl -bullet |
| 930 | .It |
| 931 | Field splitting and file name generation are not performed on arguments. |
| 932 | .It |
| 933 | The |
| 934 | .Fl a |
| 935 | .Pq AND |
| 936 | and |
| 937 | .Fl o |
| 938 | .Pq OR |
| 939 | operators are replaced with |
| 940 | .Ql && |
| 941 | and |
| 942 | .Ql \*(Ba\*(Ba , |
| 943 | respectively. |
| 944 | .It |
| 945 | Operators (e.g.\& |
| 946 | .Sq Fl f , |
| 947 | .Sq = , |
| 948 | .Sq \&! ) |
| 949 | must be unquoted. |
| 950 | .It |
| 951 | Parameter, command, and arithmetic substitutions are performed as expressions |
| 952 | are evaluated and lazy expression evaluation is used for the |
| 953 | .Ql && |
| 954 | and |
| 955 | .Ql \*(Ba\*(Ba |
| 956 | operators. |
| 957 | This means that in the following statement, |
| 958 | .Ic $(\*(Ltfoo) |
| 959 | is evaluated if and only if the file |
| 960 | .Pa foo |
| 961 | exists and is readable: |
| 962 | .Bd -literal -offset indent |
| 963 | $ [[ \-r foo && $(\*(Ltfoo) = b*r ]] |
| 964 | .Ed |
| 965 | .It |
| 966 | The second operand of the |
| 967 | .Sq != |
| 968 | and |
| 969 | .Sq = |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 970 | expressions are a subset of patterns (e.g. the comparison |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 971 | .Ic \&[[ foobar = f*r ]] |
| 972 | succeeds). |
| 973 | This even works indirectly: |
| 974 | .Bd -literal -offset indent |
| 975 | $ bar=foobar; baz=\*(aqf*r\*(aq |
| 976 | $ [[ $bar = $baz ]]; echo $? |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 977 | $ [[ $bar = \&"$baz" ]]; echo $? |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 978 | .Ed |
| 979 | .Pp |
| 980 | Perhaps surprisingly, the first comparison succeeds, |
| 981 | whereas the second doesn't. |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 982 | This does not apply to all extglob metacharacters, currently. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 983 | .El |
| 984 | .El |
| 985 | .Ss Quoting |
| 986 | Quoting is used to prevent the shell from treating characters or words |
| 987 | specially. |
| 988 | There are three methods of quoting. |
| 989 | First, |
| 990 | .Ql \e |
| 991 | quotes the following character, unless it is at the end of a line, in which |
| 992 | case both the |
| 993 | .Ql \e |
| 994 | and the newline are stripped. |
| 995 | Second, a single quote |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 996 | .Pq Dq \*(aq |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 997 | quotes everything up to the next single quote (this may span lines). |
| 998 | Third, a double quote |
| 999 | .Pq Sq \&" |
| 1000 | quotes all characters, except |
| 1001 | .Ql $ , |
| 1002 | .Ql \` |
| 1003 | and |
| 1004 | .Ql \e , |
| 1005 | up to the next unquoted double quote. |
| 1006 | .Ql $ |
| 1007 | and |
| 1008 | .Ql \` |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1009 | inside double quotes have their usual meaning (i.e. parameter, arithmetic, |
| 1010 | or command substitution) except no field splitting is carried out on the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1011 | results of double-quoted substitutions. |
| 1012 | If a |
| 1013 | .Ql \e |
| 1014 | inside a double-quoted string is followed by |
| 1015 | .Ql \e , |
| 1016 | .Ql $ , |
| 1017 | .Ql \` , |
| 1018 | or |
| 1019 | .Ql \&" , |
| 1020 | it is replaced by the second character; if it is followed by a newline, both |
| 1021 | the |
| 1022 | .Ql \e |
| 1023 | and the newline are stripped; otherwise, both the |
| 1024 | .Ql \e |
| 1025 | and the character following are unchanged. |
| 1026 | .Pp |
| 1027 | If a single-quoted string is preceded by an unquoted |
| 1028 | .Ql $ , |
| 1029 | C style backslash expansion (see below) is applied (even single quote |
| 1030 | characters inside can be escaped and do not terminate the string then); |
| 1031 | the expanded result is treated as any other single-quoted string. |
| 1032 | If a double-quoted string is preceded by an unquoted |
| 1033 | .Ql $ , |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1034 | the |
| 1035 | .Ql $ |
| 1036 | is simply ignored. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1037 | .Ss Backslash expansion |
| 1038 | In places where backslashes are expanded, certain C and |
| 1039 | .At |
| 1040 | .Nm ksh |
| 1041 | or GNU |
| 1042 | .Nm bash |
| 1043 | style escapes are translated. |
| 1044 | These include |
| 1045 | .Ql \ea , |
| 1046 | .Ql \eb , |
| 1047 | .Ql \ef , |
| 1048 | .Ql \en , |
| 1049 | .Ql \er , |
| 1050 | .Ql \et , |
| 1051 | .Ql \eU######## , |
| 1052 | .Ql \eu#### , |
| 1053 | and |
| 1054 | .Ql \ev . |
| 1055 | For |
| 1056 | .Ql \eU######## |
| 1057 | and |
| 1058 | .Ql \eu#### , |
| 1059 | .Dq # |
| 1060 | means a hexadecimal digit, of thich there may be none up to four or eight; |
| 1061 | these escapes translate a Unicode codepoint to UTF-8. |
| 1062 | Furthermore, |
| 1063 | .Ql \eE |
| 1064 | and |
| 1065 | .Ql \ee |
| 1066 | expand to the escape character. |
| 1067 | .Pp |
| 1068 | In the |
| 1069 | .Ic print |
| 1070 | builtin mode, |
| 1071 | .Ql \e" , |
| 1072 | .Ql \e\*(aq , |
| 1073 | and |
| 1074 | .Ql \e? |
| 1075 | are explicitly excluded; |
| 1076 | octal sequences must have the none up to three octal digits |
| 1077 | .Dq # |
| 1078 | prefixed with the digit zero |
| 1079 | .Pq Ql \e0### ; |
| 1080 | hexadecimal sequences |
| 1081 | .Ql \ex## |
| 1082 | are limited to none up to two hexadecimal digits |
| 1083 | .Dq # ; |
| 1084 | both octal and hexadecimal sequences convert to raw octets; |
| 1085 | .Ql \e# , |
| 1086 | where # is none of the above, translates to \e# (backslashes are retained). |
| 1087 | .Pp |
| 1088 | Backslash expansion in the C style mode slightly differs: octal sequences |
| 1089 | .Ql \e### |
| 1090 | must have no digit zero prefixing the one up to three octal digits |
| 1091 | .Dq # |
| 1092 | and yield raw octets; hexadecimal sequences |
| 1093 | .Ql \ex#* |
| 1094 | greedily eat up as many hexadecimal digits |
| 1095 | .Dq # |
| 1096 | as they can and terminate with the first non-hexadecimal digit; |
| 1097 | these translate a Unicode codepoint to UTF-8. |
| 1098 | The sequence |
| 1099 | .Ql \ec# , |
| 1100 | where |
| 1101 | .Dq # |
| 1102 | is any octet, translates to Ctrl-# (which basically means, |
| 1103 | .Ql \ec? |
| 1104 | becomes DEL, everything else is bitwise ANDed with 0x1F). |
| 1105 | Finally, |
| 1106 | .Ql \e# , |
| 1107 | where # is none of the above, translates to # (has the backslash trimmed), |
| 1108 | even if it is a newline. |
| 1109 | .Ss Aliases |
| 1110 | There are two types of aliases: normal command aliases and tracked aliases. |
| 1111 | Command aliases are normally used as a short hand for a long or often used |
| 1112 | command. |
| 1113 | The shell expands command aliases (i.e. substitutes the alias name |
| 1114 | for its value) when it reads the first word of a command. |
| 1115 | An expanded alias is re-processed to check for more aliases. |
| 1116 | If a command alias ends in a |
| 1117 | space or tab, the following word is also checked for alias expansion. |
| 1118 | The alias expansion process stops when a word that is not an alias is found, |
| 1119 | when a quoted word is found, or when an alias word that is currently being |
| 1120 | expanded is found. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1121 | Aliases are specifically an interactive feature: while they do happen |
| 1122 | to work in scripts and on the command line in some cases, aliases are |
| 1123 | expanded during lexing, so their use must be in a separate command tree |
| 1124 | from their definition; otherwise, the alias will not be found. |
| 1125 | Noticeably, command lists (separated by semicolon, in command substitutions |
| 1126 | also by newline) may be one same parse tree. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1127 | .Pp |
| 1128 | The following command aliases are defined automatically by the shell: |
| 1129 | .Bd -literal -offset indent |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1130 | autoload=\*(aq\etypeset \-fu\*(aq |
| 1131 | functions=\*(aq\etypeset \-f\*(aq |
| 1132 | hash=\*(aq\ebuiltin alias \-t\*(aq |
| 1133 | history=\*(aq\ebuiltin fc \-l\*(aq |
| 1134 | integer=\*(aq\etypeset \-i\*(aq |
| 1135 | local=\*(aq\etypeset\*(aq |
| 1136 | login=\*(aq\eexec login\*(aq |
| 1137 | nameref=\*(aq\etypeset \-n\*(aq |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1138 | nohup=\*(aqnohup \*(aq |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1139 | r=\*(aq\ebuiltin fc \-e \-\*(aq |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1140 | type=\*(aq\ebuiltin whence \-v\*(aq |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1141 | .Ed |
| 1142 | .Pp |
| 1143 | Tracked aliases allow the shell to remember where it found a particular |
| 1144 | command. |
| 1145 | The first time the shell does a path search for a command that is |
| 1146 | marked as a tracked alias, it saves the full path of the command. |
| 1147 | The next |
| 1148 | time the command is executed, the shell checks the saved path to see that it |
| 1149 | is still valid, and if so, avoids repeating the path search. |
| 1150 | Tracked aliases can be listed and created using |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1151 | .Ic alias Fl t . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1152 | Note that changing the |
| 1153 | .Ev PATH |
| 1154 | parameter clears the saved paths for all tracked aliases. |
| 1155 | If the |
| 1156 | .Ic trackall |
| 1157 | option is set (i.e.\& |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1158 | .Ic set Fl o Ic trackall |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1159 | or |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1160 | .Ic set Fl h ) , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1161 | the shell tracks all commands. |
| 1162 | This option is set automatically for non-interactive shells. |
| 1163 | For interactive shells, only the following commands are |
| 1164 | automatically tracked: |
| 1165 | .Xr cat 1 , |
| 1166 | .Xr cc 1 , |
| 1167 | .Xr chmod 1 , |
| 1168 | .Xr cp 1 , |
| 1169 | .Xr date 1 , |
| 1170 | .Xr ed 1 , |
| 1171 | .Xr emacs 1 , |
| 1172 | .Xr grep 1 , |
| 1173 | .Xr ls 1 , |
| 1174 | .Xr make 1 , |
| 1175 | .Xr mv 1 , |
| 1176 | .Xr pr 1 , |
| 1177 | .Xr rm 1 , |
| 1178 | .Xr sed 1 , |
| 1179 | .Xr sh 1 , |
| 1180 | .Xr vi 1 , |
| 1181 | and |
| 1182 | .Xr who 1 . |
| 1183 | .Ss Substitution |
| 1184 | The first step the shell takes in executing a simple-command is to perform |
| 1185 | substitutions on the words of the command. |
| 1186 | There are three kinds of |
| 1187 | substitution: parameter, command, and arithmetic. |
| 1188 | Parameter substitutions, |
| 1189 | which are described in detail in the next section, take the form |
| 1190 | .Pf $ Ns Ar name |
| 1191 | or |
| 1192 | .Pf ${ Ns Ar ... Ns } ; |
| 1193 | command substitutions take the form |
| 1194 | .Pf $( Ns Ar command Ns \&) |
| 1195 | or (deprecated) |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1196 | .Pf \` Ns Ar command Ns \` |
| 1197 | or (executed in the current environment) |
| 1198 | .Pf ${\ \& Ar command Ns \&;} |
| 1199 | and strip trailing newlines; |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1200 | and arithmetic substitutions take the form |
| 1201 | .Pf $(( Ns Ar expression Ns )) . |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1202 | Parsing the current-environment command substitution requires a space, |
| 1203 | tab or newline after the opening brace and that the closing brace be |
| 1204 | recognised as a keyword (i.e. is preceded by a newline or semicolon). |
| 1205 | They are also called funsubs (function substitutions) and behave like |
| 1206 | functions in that |
| 1207 | .Ic local |
| 1208 | and |
| 1209 | .Ic return |
| 1210 | work, and in that |
| 1211 | .Ic exit |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1212 | terminates the parent shell; shell options are shared. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1213 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 1214 | Another variant of substitution are the valsubs (value substitutions) |
| 1215 | .Pf ${\*(Ba\& Ns Ar command Ns \&;} |
| 1216 | which are also executed in the current environment, like funsubs, but |
| 1217 | share their I/O with the parent; instead, they evaluate to whatever |
| 1218 | the, initially empty, expression-local variable |
| 1219 | .Ev REPLY |
| 1220 | is set to within the |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1221 | .Ar command Ns s . |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 1222 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1223 | If a substitution appears outside of double quotes, the results of the |
| 1224 | substitution are generally subject to word or field splitting according to |
| 1225 | the current value of the |
| 1226 | .Ev IFS |
| 1227 | parameter. |
| 1228 | The |
| 1229 | .Ev IFS |
| 1230 | parameter specifies a list of octets which are used to break a string up |
| 1231 | into several words; any octets from the set space, tab, and newline that |
| 1232 | appear in the |
| 1233 | .Ev IFS |
| 1234 | octets are called |
| 1235 | .Dq IFS whitespace . |
| 1236 | Sequences of one or more |
| 1237 | .Ev IFS |
| 1238 | whitespace octets, in combination with zero or one |
| 1239 | .Pf non- Ev IFS |
| 1240 | whitespace octets, delimit a field. |
| 1241 | As a special case, leading and trailing |
| 1242 | .Ev IFS |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 1243 | whitespace is stripped (i.e. no leading or trailing empty field |
| 1244 | is created by it); leading or trailing |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1245 | .Pf non- Ev IFS |
| 1246 | whitespace does create an empty field. |
| 1247 | .Pp |
| 1248 | Example: If |
| 1249 | .Ev IFS |
| 1250 | is set to |
| 1251 | .Dq \*(Ltspace\*(Gt: , |
| 1252 | and VAR is set to |
| 1253 | .Dq \*(Ltspace\*(GtA\*(Ltspace\*(Gt:\*(Ltspace\*(Gt\*(Ltspace\*(GtB::D , |
| 1254 | the substitution for $VAR results in four fields: |
| 1255 | .Sq A , |
| 1256 | .Sq B , |
| 1257 | .Sq |
| 1258 | (an empty field), |
| 1259 | and |
| 1260 | .Sq D . |
| 1261 | Note that if the |
| 1262 | .Ev IFS |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1263 | parameter is set to the empty string, no field splitting is done; |
| 1264 | if it is unset, the default value of space, tab, and newline is used. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1265 | .Pp |
| 1266 | Also, note that the field splitting applies only to the immediate result of |
| 1267 | the substitution. |
| 1268 | Using the previous example, the substitution for $VAR:E |
| 1269 | results in the fields: |
| 1270 | .Sq A , |
| 1271 | .Sq B , |
| 1272 | .Sq , |
| 1273 | and |
| 1274 | .Sq D:E , |
| 1275 | not |
| 1276 | .Sq A , |
| 1277 | .Sq B , |
| 1278 | .Sq , |
| 1279 | .Sq D , |
| 1280 | and |
| 1281 | .Sq E . |
| 1282 | This behavior is POSIX compliant, but incompatible with some other shell |
| 1283 | implementations which do field splitting on the word which contained the |
| 1284 | substitution or use |
| 1285 | .Dv IFS |
| 1286 | as a general whitespace delimiter. |
| 1287 | .Pp |
| 1288 | The results of substitution are, unless otherwise specified, also subject to |
| 1289 | brace expansion and file name expansion (see the relevant sections below). |
| 1290 | .Pp |
| 1291 | A command substitution is replaced by the output generated by the specified |
| 1292 | command which is run in a subshell. |
| 1293 | For |
| 1294 | .Pf $( Ns Ar command Ns \&) |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1295 | and |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1296 | .Pf ${\*(Ba\& Ns Ar command Ns \&;} |
| 1297 | and |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1298 | .Pf ${\ \& Ar command Ns \&;} |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1299 | substitutions, normal quoting rules are used when |
| 1300 | .Ar command |
| 1301 | is parsed; however, for the deprecated |
| 1302 | .Pf \` Ns Ar command Ns \` |
| 1303 | form, a |
| 1304 | .Ql \e |
| 1305 | followed by any of |
| 1306 | .Ql $ , |
| 1307 | .Ql \` , |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1308 | .Ql \&" |
| 1309 | .Pq currently, and violating Tn POSIX , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1310 | or |
| 1311 | .Ql \e |
| 1312 | is stripped (a |
| 1313 | .Ql \e |
| 1314 | followed by any other character is unchanged). |
| 1315 | As a special case in command substitutions, a command of the form |
| 1316 | .Pf \*(Lt Ar file |
| 1317 | is interpreted to mean substitute the contents of |
| 1318 | .Ar file . |
| 1319 | Note that |
| 1320 | .Ic $(\*(Ltfoo) |
| 1321 | has the same effect as |
| 1322 | .Ic $(cat foo) . |
| 1323 | .Pp |
| 1324 | Note that some shells do not use a recursive parser for command substitutions, |
| 1325 | leading to failure for certain constructs; to be portable, use as workaround |
| 1326 | .Ql x=$(cat) \*(Lt\*(Lt"EOF" |
| 1327 | (or the newline-keeping |
| 1328 | .Ql x=\*(Lt\*(Lt"EOF" |
| 1329 | extension) instead to merely slurp the string. |
| 1330 | .St -p1003.1 |
| 1331 | recommends to use case statements of the form |
| 1332 | .Ql "x=$(case $foo in (bar) echo $bar ;; (*) echo $baz ;; esac)" |
| 1333 | instead, which would work but not serve as example for this portability issue. |
| 1334 | .Bd -literal -offset indent |
| 1335 | x=$(case $foo in bar) echo $bar ;; *) echo $baz ;; esac) |
| 1336 | # above fails to parse on old shells; below is the workaround |
| 1337 | x=$(eval $(cat)) \*(Lt\*(Lt"EOF" |
| 1338 | case $foo in bar) echo $bar ;; *) echo $baz ;; esac |
| 1339 | EOF |
| 1340 | .Ed |
| 1341 | .Pp |
| 1342 | Arithmetic substitutions are replaced by the value of the specified expression. |
| 1343 | For example, the command |
| 1344 | .Ic print $((2+3*4)) |
| 1345 | displays 14. |
| 1346 | See |
| 1347 | .Sx Arithmetic expressions |
| 1348 | for a description of an expression. |
| 1349 | .Ss Parameters |
| 1350 | Parameters are shell variables; they can be assigned values and their values |
| 1351 | can be accessed using a parameter substitution. |
| 1352 | A parameter name is either one |
| 1353 | of the special single punctuation or digit character parameters described |
| 1354 | below, or a letter followed by zero or more letters or digits |
| 1355 | .Po |
| 1356 | .Ql _ |
| 1357 | counts as a letter |
| 1358 | .Pc . |
| 1359 | The latter form can be treated as arrays by appending an array index of the |
| 1360 | form |
| 1361 | .Op Ar expr |
| 1362 | where |
| 1363 | .Ar expr |
| 1364 | is an arithmetic expression. |
| 1365 | Array indices in |
| 1366 | .Nm |
| 1367 | are limited to the range 0 through 4294967295, inclusive. |
| 1368 | That is, they are a 32-bit unsigned integer. |
| 1369 | .Pp |
| 1370 | Parameter substitutions take the form |
| 1371 | .Pf $ Ns Ar name , |
| 1372 | .Pf ${ Ns Ar name Ns } , |
| 1373 | or |
| 1374 | .Sm off |
| 1375 | .Pf ${ Ar name Oo Ar expr Oc } |
| 1376 | .Sm on |
| 1377 | where |
| 1378 | .Ar name |
| 1379 | is a parameter name. |
| 1380 | Substitution of all array elements with |
| 1381 | .Pf ${ Ns Ar name Ns \&[*]} |
| 1382 | and |
| 1383 | .Pf ${ Ns Ar name Ns \&[@]} |
| 1384 | works equivalent to $* and $@ for positional parameters. |
| 1385 | If substitution is performed on a parameter |
| 1386 | (or an array parameter element) |
| 1387 | that is not set, a null string is substituted unless the |
| 1388 | .Ic nounset |
| 1389 | option |
| 1390 | .Po |
| 1391 | .Ic set Fl o Ic nounset |
| 1392 | or |
| 1393 | .Ic set Fl u |
| 1394 | .Pc |
| 1395 | is set, in which case an error occurs. |
| 1396 | .Pp |
| 1397 | Parameters can be assigned values in a number of ways. |
| 1398 | First, the shell implicitly sets some parameters like |
| 1399 | .Ql # , |
| 1400 | .Ql PWD , |
| 1401 | and |
| 1402 | .Ql $ ; |
| 1403 | this is the only way the special single character parameters are set. |
| 1404 | Second, parameters are imported from the shell's environment at startup. |
| 1405 | Third, parameters can be assigned values on the command line: for example, |
| 1406 | .Ic FOO=bar |
| 1407 | sets the parameter |
| 1408 | .Dq FOO |
| 1409 | to |
| 1410 | .Dq bar ; |
| 1411 | multiple parameter assignments can be given on a single command line and they |
| 1412 | can be followed by a simple-command, in which case the assignments are in |
| 1413 | effect only for the duration of the command (such assignments are also |
| 1414 | exported; see below for the implications of this). |
| 1415 | Note that both the parameter name and the |
| 1416 | .Ql = |
| 1417 | must be unquoted for the shell to recognise a parameter assignment. |
| 1418 | The construct |
| 1419 | .Ic FOO+=baz |
| 1420 | is also recognised; the old and new values are immediately concatenated. |
| 1421 | The fourth way of setting a parameter is with the |
| 1422 | .Ic export , |
| 1423 | .Ic global , |
| 1424 | .Ic readonly , |
| 1425 | and |
| 1426 | .Ic typeset |
| 1427 | commands; see their descriptions in the |
| 1428 | .Sx Command execution |
| 1429 | section. |
| 1430 | Fifth, |
| 1431 | .Ic for |
| 1432 | and |
| 1433 | .Ic select |
| 1434 | loops set parameters as well as the |
| 1435 | .Ic getopts , |
| 1436 | .Ic read , |
| 1437 | and |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1438 | .Ic set Fl A |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1439 | commands. |
| 1440 | Lastly, parameters can be assigned values using assignment operators |
| 1441 | inside arithmetic expressions (see |
| 1442 | .Sx Arithmetic expressions |
| 1443 | below) or using the |
| 1444 | .Sm off |
| 1445 | .Pf ${ Ar name No = Ar value No } |
| 1446 | .Sm on |
| 1447 | form of the parameter substitution (see below). |
| 1448 | .Pp |
| 1449 | Parameters with the export attribute (set using the |
| 1450 | .Ic export |
| 1451 | or |
| 1452 | .Ic typeset Fl x |
| 1453 | commands, or by parameter assignments followed by simple commands) are put in |
| 1454 | the environment (see |
| 1455 | .Xr environ 7 ) |
| 1456 | of commands run by the shell as |
| 1457 | .Ar name Ns = Ns Ar value |
| 1458 | pairs. |
| 1459 | The order in which parameters appear in the environment of a command is |
| 1460 | unspecified. |
| 1461 | When the shell starts up, it extracts parameters and their values |
| 1462 | from its environment and automatically sets the export attribute for those |
| 1463 | parameters. |
| 1464 | .Pp |
| 1465 | Modifiers can be applied to the |
| 1466 | .Pf ${ Ns Ar name Ns } |
| 1467 | form of parameter substitution: |
| 1468 | .Bl -tag -width Ds |
| 1469 | .Sm off |
| 1470 | .It ${ Ar name No :\- Ar word No } |
| 1471 | .Sm on |
| 1472 | If |
| 1473 | .Ar name |
| 1474 | is set and not |
| 1475 | .Dv NULL , |
| 1476 | it is substituted; otherwise, |
| 1477 | .Ar word |
| 1478 | is substituted. |
| 1479 | .Sm off |
| 1480 | .It ${ Ar name No :+ Ar word No } |
| 1481 | .Sm on |
| 1482 | If |
| 1483 | .Ar name |
| 1484 | is set and not |
| 1485 | .Dv NULL , |
| 1486 | .Ar word |
| 1487 | is substituted; otherwise, nothing is substituted. |
| 1488 | .Sm off |
| 1489 | .It ${ Ar name No := Ar word No } |
| 1490 | .Sm on |
| 1491 | If |
| 1492 | .Ar name |
| 1493 | is set and not |
| 1494 | .Dv NULL , |
| 1495 | it is substituted; otherwise, it is assigned |
| 1496 | .Ar word |
| 1497 | and the resulting value of |
| 1498 | .Ar name |
| 1499 | is substituted. |
| 1500 | .Sm off |
| 1501 | .It ${ Ar name No :? Ar word No } |
| 1502 | .Sm on |
| 1503 | If |
| 1504 | .Ar name |
| 1505 | is set and not |
| 1506 | .Dv NULL , |
| 1507 | it is substituted; otherwise, |
| 1508 | .Ar word |
| 1509 | is printed on standard error (preceded by |
| 1510 | .Ar name : ) |
| 1511 | and an error occurs (normally causing termination of a shell script, function, |
| 1512 | or script sourced using the |
| 1513 | .Sq \&. |
| 1514 | built-in). |
| 1515 | If |
| 1516 | .Ar word |
| 1517 | is omitted, the string |
| 1518 | .Dq parameter null or not set |
| 1519 | is used instead. |
| 1520 | Currently a bug, if |
| 1521 | .Ar word |
| 1522 | is a variable which expands to the null string, the |
| 1523 | error message is also printed. |
| 1524 | .El |
| 1525 | .Pp |
| 1526 | Note that, for all of the above, |
| 1527 | .Ar word |
| 1528 | is actually considered quoted, and special parsing rules apply. |
| 1529 | The parsing rules also differ on whether the expression is double-quoted: |
| 1530 | .Ar word |
| 1531 | then uses double-quoting rules, except for the double quote itself |
| 1532 | .Pq Sq \&" |
| 1533 | and the closing brace, which, if backslash escaped, gets quote removal applied. |
| 1534 | .Pp |
| 1535 | In the above modifiers, the |
| 1536 | .Ql \&: |
| 1537 | can be omitted, in which case the conditions only depend on |
| 1538 | .Ar name |
| 1539 | being set (as opposed to set and not |
| 1540 | .Dv NULL ) . |
| 1541 | If |
| 1542 | .Ar word |
| 1543 | is needed, parameter, command, arithmetic, and tilde substitution are performed |
| 1544 | on it; if |
| 1545 | .Ar word |
| 1546 | is not needed, it is not evaluated. |
| 1547 | .Pp |
| 1548 | The following forms of parameter substitution can also be used (if |
| 1549 | .Ar name |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1550 | is an array, the element with the key |
| 1551 | .Dq 0 |
| 1552 | will be substituted in scalar context): |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1553 | .Pp |
| 1554 | .Bl -tag -width Ds -compact |
| 1555 | .It Pf ${# Ns Ar name Ns \&} |
| 1556 | The number of positional parameters if |
| 1557 | .Ar name |
| 1558 | is |
| 1559 | .Ql * , |
| 1560 | .Ql @ , |
| 1561 | or not specified; otherwise the length |
| 1562 | .Pq in characters |
| 1563 | of the string value of parameter |
| 1564 | .Ar name . |
| 1565 | .Pp |
| 1566 | .It Pf ${# Ns Ar name Ns \&[*]} |
| 1567 | .It Pf ${# Ns Ar name Ns \&[@]} |
| 1568 | The number of elements in the array |
| 1569 | .Ar name . |
| 1570 | .Pp |
| 1571 | .It Pf ${% Ns Ar name Ns \&} |
| 1572 | The width |
| 1573 | .Pq in screen columns |
| 1574 | of the string value of parameter |
| 1575 | .Ar name , |
| 1576 | or \-1 if |
| 1577 | .Pf ${ Ns Ar name Ns } |
| 1578 | contains a control character. |
| 1579 | .Pp |
| 1580 | .It Pf ${! Ns Ar name Ns } |
| 1581 | The name of the variable referred to by |
| 1582 | .Ar name . |
| 1583 | This will be |
| 1584 | .Ar name |
| 1585 | except when |
| 1586 | .Ar name |
| 1587 | is a name reference (bound variable), created by the |
| 1588 | .Ic nameref |
| 1589 | command (which is an alias for |
| 1590 | .Ic typeset Fl n ) . |
| 1591 | .Pp |
| 1592 | .It Pf ${! Ns Ar name Ns \&[*]} |
| 1593 | .It Pf ${! Ns Ar name Ns \&[@]} |
| 1594 | The names of indices (keys) in the array |
| 1595 | .Ar name . |
| 1596 | .Pp |
| 1597 | .Sm off |
| 1598 | .It Xo |
| 1599 | .Pf ${ Ar name |
| 1600 | .Pf # Ar pattern No } |
| 1601 | .Xc |
| 1602 | .It Xo |
| 1603 | .Pf ${ Ar name |
| 1604 | .Pf ## Ar pattern No } |
| 1605 | .Xc |
| 1606 | .Sm on |
| 1607 | If |
| 1608 | .Ar pattern |
| 1609 | matches the beginning of the value of parameter |
| 1610 | .Ar name , |
| 1611 | the matched text is deleted from the result of substitution. |
| 1612 | A single |
| 1613 | .Ql # |
| 1614 | results in the shortest match, and two |
| 1615 | of them result in the longest match. |
| 1616 | Cannot be applied to a vector |
| 1617 | .Pq ${*} or ${@} or ${array[*]} or ${array[@]} . |
| 1618 | .Pp |
| 1619 | .Sm off |
| 1620 | .It Xo |
| 1621 | .Pf ${ Ar name |
| 1622 | .Pf % Ar pattern No } |
| 1623 | .Xc |
| 1624 | .It Xo |
| 1625 | .Pf ${ Ar name |
| 1626 | .Pf %% Ar pattern No } |
| 1627 | .Xc |
| 1628 | .Sm on |
| 1629 | Like ${..#..} substitution, but it deletes from the end of the value. |
| 1630 | Cannot be applied to a vector. |
| 1631 | .Pp |
| 1632 | .Sm off |
| 1633 | .It Xo |
| 1634 | .Pf ${ Ar name |
| 1635 | .Pf / Ar pattern / Ar string No } |
| 1636 | .Xc |
| 1637 | .It Xo |
| 1638 | .Pf ${ Ar name |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1639 | .Pf /# Ar pattern / Ar string No } |
| 1640 | .Xc |
| 1641 | .It Xo |
| 1642 | .Pf ${ Ar name |
| 1643 | .Pf /% Ar pattern / Ar string No } |
| 1644 | .Xc |
| 1645 | .It Xo |
| 1646 | .Pf ${ Ar name |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1647 | .Pf // Ar pattern / Ar string No } |
| 1648 | .Xc |
| 1649 | .Sm on |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1650 | The longest match of |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1651 | .Ar pattern |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1652 | in the value of parameter |
| 1653 | .Ar name |
| 1654 | is replaced with |
| 1655 | .Ar string |
| 1656 | (deleted if |
| 1657 | .Ar string |
| 1658 | is empty; the trailing slash |
| 1659 | .Pq Ql / |
| 1660 | may be omitted in that case). |
| 1661 | A leading slash followed by |
| 1662 | .Ql # |
| 1663 | or |
| 1664 | .Ql % |
| 1665 | causes the pattern to be anchored at the beginning or end of |
| 1666 | the value, respectively; empty unanchored |
| 1667 | .Ar pattern Ns s |
| 1668 | cause no replacement; a single leading slash or use of a |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1669 | .Ar pattern |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1670 | that matches the empty string causes the replacement to |
| 1671 | happen only once; two leading slashes cause all occurrences |
| 1672 | of matches in the value to be replaced. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1673 | Cannot be applied to a vector. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1674 | Inefficiently implemented, may be slow. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1675 | .Pp |
| 1676 | .Sm off |
| 1677 | .It Xo |
| 1678 | .Pf ${ Ar name : Ns Ar pos |
| 1679 | .Pf : Ns Ar len Ns } |
| 1680 | .Xc |
| 1681 | .Sm on |
| 1682 | The first |
| 1683 | .Ar len |
| 1684 | characters of |
| 1685 | .Ar name , |
| 1686 | starting at position |
| 1687 | .Ar pos , |
| 1688 | are substituted. |
| 1689 | Both |
| 1690 | .Ar pos |
| 1691 | and |
| 1692 | .Pf : Ns Ar len |
| 1693 | are optional. |
| 1694 | If |
| 1695 | .Ar pos |
| 1696 | is negative, counting starts at the end of the string; if it |
| 1697 | is omitted, it defaults to 0. |
| 1698 | If |
| 1699 | .Ar len |
| 1700 | is omitted or greater than the length of the remaining string, |
| 1701 | all of it is substituted. |
| 1702 | Both |
| 1703 | .Ar pos |
| 1704 | and |
| 1705 | .Ar len |
| 1706 | are evaluated as arithmetic expressions. |
| 1707 | Currently, |
| 1708 | .Ar pos |
| 1709 | must start with a space, opening parenthesis or digit to be recognised. |
| 1710 | Cannot be applied to a vector. |
| 1711 | .Pp |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 1712 | .It Pf ${ Ns Ar name Ns @#} |
| 1713 | The hash (using the BAFH algorithm) of the expansion of |
| 1714 | .Ar name . |
| 1715 | This is also used internally for the shell's hashtables. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1716 | .Pp |
| 1717 | .It Pf ${ Ns Ar name Ns @Q} |
| 1718 | A quoted expression safe for re-entry, whose value is the value of the |
| 1719 | .Ar name |
| 1720 | parameter, is substituted. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1721 | .El |
| 1722 | .Pp |
| 1723 | Note that |
| 1724 | .Ar pattern |
| 1725 | may need extended globbing pattern |
| 1726 | .Pq @(...) , |
| 1727 | single |
| 1728 | .Pq \&\*(aq...\&\*(aq |
| 1729 | or double |
| 1730 | .Pq \&"...\&" |
| 1731 | quote escaping unless |
| 1732 | .Fl o Ic sh |
| 1733 | is set. |
| 1734 | .Pp |
| 1735 | The following special parameters are implicitly set by the shell and cannot be |
| 1736 | set directly using assignments: |
| 1737 | .Bl -tag -width "1 .. 9" |
| 1738 | .It Ev \&! |
| 1739 | Process ID of the last background process started. |
| 1740 | If no background processes have been started, the parameter is not set. |
| 1741 | .It Ev \&# |
| 1742 | The number of positional parameters ($1, $2, etc.). |
| 1743 | .It Ev \&$ |
| 1744 | The PID of the shell, or the PID of the original shell if it is a subshell. |
| 1745 | Do |
| 1746 | .Em NOT |
| 1747 | use this mechanism for generating temporary file names; see |
| 1748 | .Xr mktemp 1 |
| 1749 | instead. |
| 1750 | .It Ev \- |
| 1751 | The concatenation of the current single letter options (see the |
| 1752 | .Ic set |
| 1753 | command below for a list of options). |
| 1754 | .It Ev \&? |
| 1755 | The exit status of the last non-asynchronous command executed. |
| 1756 | If the last command was killed by a signal, |
| 1757 | .Ic $?\& |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1758 | is set to 128 plus the signal number, but at most 255. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1759 | .It Ev 0 |
| 1760 | The name of the shell, determined as follows: |
| 1761 | the first argument to |
| 1762 | .Nm |
| 1763 | if it was invoked with the |
| 1764 | .Fl c |
| 1765 | option and arguments were given; otherwise the |
| 1766 | .Ar file |
| 1767 | argument, if it was supplied; |
| 1768 | or else the basename the shell was invoked with (i.e.\& |
| 1769 | .Li argv[0] ) . |
| 1770 | .Ev $0 |
| 1771 | is also set to the name of the current script or |
| 1772 | the name of the current function, if it was defined with the |
| 1773 | .Ic function |
| 1774 | keyword (i.e. a Korn shell style function). |
| 1775 | .It Ev 1 No .. Ev 9 |
| 1776 | The first nine positional parameters that were supplied to the shell, function, |
| 1777 | or script sourced using the |
| 1778 | .Sq \&. |
| 1779 | built-in. |
| 1780 | Further positional parameters may be accessed using |
| 1781 | .Pf ${ Ar number Ns } . |
| 1782 | .It Ev * |
| 1783 | All positional parameters (except 0), i.e. $1, $2, $3, ... |
| 1784 | .br |
| 1785 | If used |
| 1786 | outside of double quotes, parameters are separate words (which are subjected |
| 1787 | to word splitting); if used within double quotes, parameters are separated |
| 1788 | by the first character of the |
| 1789 | .Ev IFS |
| 1790 | parameter (or the empty string if |
| 1791 | .Ev IFS |
| 1792 | is |
| 1793 | .Dv NULL ) . |
| 1794 | .It Ev @ |
| 1795 | Same as |
| 1796 | .Ic $* , |
| 1797 | unless it is used inside double quotes, in which case a separate word is |
| 1798 | generated for each positional parameter. |
| 1799 | If there are no positional parameters, no word is generated. |
| 1800 | .Ic $@ |
| 1801 | can be used to access arguments, verbatim, without losing |
| 1802 | .Dv NULL |
| 1803 | arguments or splitting arguments with spaces. |
| 1804 | .El |
| 1805 | .Pp |
| 1806 | The following parameters are set and/or used by the shell: |
| 1807 | .Bl -tag -width "KSH_VERSION" |
| 1808 | .It Ev _ |
| 1809 | .Pq underscore |
| 1810 | When an external command is executed by the shell, this parameter is set in the |
| 1811 | environment of the new process to the path of the executed command. |
| 1812 | In interactive use, this parameter is also set in the parent shell to the last |
| 1813 | word of the previous command. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1814 | .It Ev BASHPID |
| 1815 | The PID of the shell or subshell. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1816 | .It Ev CDPATH |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1817 | Like |
| 1818 | .Ev PATH , |
| 1819 | but used to resolve the argument to the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1820 | .Ic cd |
| 1821 | built-in command. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1822 | Note that if |
| 1823 | .Ev CDPATH |
| 1824 | is set and does not contain |
| 1825 | .Sq \&. |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1826 | or an empty string element, the current directory is not searched. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1827 | Also, the |
| 1828 | .Ic cd |
| 1829 | built-in command will display the resulting directory when a match is found |
| 1830 | in any search path other than the empty path. |
| 1831 | .It Ev COLUMNS |
| 1832 | Set to the number of columns on the terminal or window. |
| 1833 | Always set, defaults to 80, unless the |
| 1834 | value as reported by |
| 1835 | .Xr stty 1 |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1836 | is non-zero and sane enough (minimum is 12x3); similar for |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1837 | .Ev LINES . |
| 1838 | This parameter is used by the interactive line editing modes, and by the |
| 1839 | .Ic select , |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1840 | .Ic set Fl o , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1841 | and |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1842 | .Ic kill Fl l |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1843 | commands to format information columns. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1844 | Importing from the environment or unsetting this parameter removes the |
| 1845 | binding to the actual terminal size in favour of the provided value. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1846 | .It Ev ENV |
| 1847 | If this parameter is found to be set after any profile files are executed, the |
| 1848 | expanded value is used as a shell startup file. |
| 1849 | It typically contains function and alias definitions. |
| 1850 | .It Ev ERRNO |
| 1851 | Integer value of the shell's |
| 1852 | .Va errno |
| 1853 | variable. |
| 1854 | It indicates the reason the last system call failed. |
| 1855 | Not yet implemented. |
| 1856 | .It Ev EXECSHELL |
| 1857 | If set, this parameter is assumed to contain the shell that is to be used to |
| 1858 | execute commands that |
| 1859 | .Xr execve 2 |
| 1860 | fails to execute and which do not start with a |
| 1861 | .Dq #! Ns Ar shell |
| 1862 | sequence. |
| 1863 | .It Ev FCEDIT |
| 1864 | The editor used by the |
| 1865 | .Ic fc |
| 1866 | command (see below). |
| 1867 | .It Ev FPATH |
| 1868 | Like |
| 1869 | .Ev PATH , |
| 1870 | but used when an undefined function is executed to locate the file defining the |
| 1871 | function. |
| 1872 | It is also searched when a command can't be found using |
| 1873 | .Ev PATH . |
| 1874 | See |
| 1875 | .Sx Functions |
| 1876 | below for more information. |
| 1877 | .It Ev HISTFILE |
| 1878 | The name of the file used to store command history. |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1879 | When assigned to or unset, the file is opened, history is truncated |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 1880 | then loaded from the file; subsequent new commands (possibly consisting |
| 1881 | of several lines) are appended once they successfully compiled. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1882 | Also, several invocations of the shell will share history if their |
| 1883 | .Ev HISTFILE |
| 1884 | parameters all point to the same file. |
| 1885 | .Pp |
| 1886 | .Sy Note : |
| 1887 | If |
| 1888 | .Ev HISTFILE |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 1889 | is unset or empty, no history file is used. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1890 | This is different from |
| 1891 | .At |
| 1892 | .Nm ksh . |
| 1893 | .It Ev HISTSIZE |
| 1894 | The number of commands normally stored for history. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1895 | The default is 2047. |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 1896 | Do not set this value to insanely high values such as 1000000000 because |
| 1897 | .Nm |
| 1898 | can then not allocate enough memory for the history and will not start. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1899 | .It Ev HOME |
| 1900 | The default directory for the |
| 1901 | .Ic cd |
| 1902 | command and the value substituted for an unqualified |
| 1903 | .Ic \*(TI |
| 1904 | (see |
| 1905 | .Sx Tilde expansion |
| 1906 | below). |
| 1907 | .It Ev IFS |
| 1908 | Internal field separator, used during substitution and by the |
| 1909 | .Ic read |
| 1910 | command, to split values into distinct arguments; normally set to space, tab, |
| 1911 | and newline. |
| 1912 | See |
| 1913 | .Sx Substitution |
| 1914 | above for details. |
| 1915 | .Pp |
| 1916 | .Sy Note : |
| 1917 | This parameter is not imported from the environment when the shell is |
| 1918 | started. |
| 1919 | .It Ev KSHEGID |
| 1920 | The effective group id of the shell. |
| 1921 | .It Ev KSHGID |
| 1922 | The real group id of the shell. |
| 1923 | .It Ev KSHUID |
| 1924 | The real user id of the shell. |
| 1925 | .It Ev KSH_VERSION |
| 1926 | The name and version of the shell (read-only). |
| 1927 | See also the version commands in |
| 1928 | .Sx Emacs editing mode |
| 1929 | and |
| 1930 | .Sx Vi editing mode |
| 1931 | sections, below. |
| 1932 | .It Ev LINENO |
| 1933 | The line number of the function or shell script that is currently being |
| 1934 | executed. |
| 1935 | .It Ev LINES |
| 1936 | Set to the number of lines on the terminal or window. |
| 1937 | Always set, defaults to 24. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 1938 | See |
| 1939 | .Ev COLUMNS . |
| 1940 | .It Ev EPOCHREALTIME |
| 1941 | Time since the epoch, as returned by |
| 1942 | .Xr gettimeofday 2 , |
| 1943 | formatted as decimal |
| 1944 | .Va tv_sec |
| 1945 | followed by a dot |
| 1946 | .Pq Sq .\& |
| 1947 | and |
| 1948 | .Va tv_usec |
| 1949 | padded to exactly six decimal digits. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1950 | .It Ev OLDPWD |
| 1951 | The previous working directory. |
| 1952 | Unset if |
| 1953 | .Ic cd |
| 1954 | has not successfully changed directories since the shell started, or if the |
| 1955 | shell doesn't know where it is. |
| 1956 | .It Ev OPTARG |
| 1957 | When using |
| 1958 | .Ic getopts , |
| 1959 | it contains the argument for a parsed option, if it requires one. |
| 1960 | .It Ev OPTIND |
| 1961 | The index of the next argument to be processed when using |
| 1962 | .Ic getopts . |
| 1963 | Assigning 1 to this parameter causes |
| 1964 | .Ic getopts |
| 1965 | to process arguments from the beginning the next time it is invoked. |
| 1966 | .It Ev PATH |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 1967 | A colon (semicolon on OS/2) separated list of directories that are |
| 1968 | searched when looking for commands and files sourced using the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 1969 | .Sq \&. |
| 1970 | command (see below). |
| 1971 | An empty string resulting from a leading or trailing |
| 1972 | colon, or two adjacent colons, is treated as a |
| 1973 | .Sq \&. |
| 1974 | (the current directory). |
| 1975 | .It Ev PGRP |
| 1976 | The process ID of the shell's process group leader. |
| 1977 | .It Ev PIPESTATUS |
| 1978 | An array containing the errorlevel (exit status) codes, |
| 1979 | one by one, of the last pipeline run in the foreground. |
| 1980 | .It Ev PPID |
| 1981 | The process ID of the shell's parent. |
| 1982 | .It Ev PS1 |
| 1983 | The primary prompt for interactive shells. |
| 1984 | Parameter, command, and arithmetic |
| 1985 | substitutions are performed, and |
| 1986 | .Ql \&! |
| 1987 | is replaced with the current command number (see the |
| 1988 | .Ic fc |
| 1989 | command below). |
| 1990 | A literal |
| 1991 | .Ql \&! |
| 1992 | can be put in the prompt by placing |
| 1993 | .Ql !! |
| 1994 | in |
| 1995 | .Ev PS1 . |
| 1996 | .Pp |
| 1997 | The default prompt is |
| 1998 | .Sq $\ \& |
| 1999 | for non-root users, |
| 2000 | .Sq #\ \& |
| 2001 | for root. |
| 2002 | If |
| 2003 | .Nm |
| 2004 | is invoked by root and |
| 2005 | .Ev PS1 |
| 2006 | does not contain a |
| 2007 | .Sq # |
| 2008 | character, the default value will be used even if |
| 2009 | .Ev PS1 |
| 2010 | already exists in the environment. |
| 2011 | .Pp |
| 2012 | The |
| 2013 | .Nm |
| 2014 | distribution comes with a sample |
| 2015 | .Pa dot.mkshrc |
| 2016 | containing a sophisticated example, but you might like the following one |
| 2017 | (note that ${HOSTNAME:=$(hostname)} and the |
| 2018 | root-vs-user distinguishing clause are (in this example) executed at |
| 2019 | .Ev PS1 |
| 2020 | assignment time, while the $USER and $PWD are escaped |
| 2021 | and thus will be evaluated each time a prompt is displayed): |
| 2022 | .Bd -literal |
| 2023 | PS1=\*(aq${USER:=$(id \-un)}\*(aq"@${HOSTNAME:=$(hostname)}:\e$PWD $( |
| 2024 | if (( USER_ID )); then print \e$; else print \e#; fi) " |
| 2025 | .Ed |
| 2026 | .Pp |
| 2027 | Note that since the command-line editors try to figure out how long the prompt |
| 2028 | is (so they know how far it is to the edge of the screen), escape codes in |
| 2029 | the prompt tend to mess things up. |
| 2030 | You can tell the shell not to count certain |
| 2031 | sequences (such as escape codes) by prefixing your prompt with a |
| 2032 | character (such as Ctrl-A) followed by a carriage return and then delimiting |
| 2033 | the escape codes with this character. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2034 | Any occurrences of that character in the prompt are not printed. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2035 | By the way, don't blame me for |
| 2036 | this hack; it's derived from the original |
| 2037 | .Xr ksh88 1 , |
| 2038 | which did print the delimiter character so you were out of luck |
| 2039 | if you did not have any non-printing characters. |
| 2040 | .Pp |
| 2041 | Since Backslashes and other special characters may be |
| 2042 | interpreted by the shell, to set |
| 2043 | .Ev PS1 |
| 2044 | either escape the backslash itself, |
| 2045 | or use double quotes. |
| 2046 | The latter is more practical. |
| 2047 | This is a more complex example, |
| 2048 | avoiding to directly enter special characters (for example with |
| 2049 | .Ic \*(haV |
| 2050 | in the emacs editing mode), |
| 2051 | which embeds the current working directory, |
| 2052 | in reverse video |
| 2053 | .Pq colour would work, too , |
| 2054 | in the prompt string: |
| 2055 | .Bd -literal -offset indent |
| 2056 | x=$(print \e\e001) |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 2057 | PS1="$x$(print \e\er)$x$(tput so)$x\e$PWD$x$(tput se)$x\*(Gt " |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2058 | .Ed |
| 2059 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2060 | Due to a strong suggestion from David G. Korn, |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2061 | .Nm |
| 2062 | now also supports the following form: |
| 2063 | .Bd -literal -offset indent |
| 2064 | PS1=$'\e1\er\e1\ee[7m\e1$PWD\e1\ee[0m\e1\*(Gt ' |
| 2065 | .Ed |
| 2066 | .It Ev PS2 |
| 2067 | Secondary prompt string, by default |
| 2068 | .Sq \*(Gt\ \& , |
| 2069 | used when more input is needed to complete a command. |
| 2070 | .It Ev PS3 |
| 2071 | Prompt used by the |
| 2072 | .Ic select |
| 2073 | statement when reading a menu selection. |
| 2074 | The default is |
| 2075 | .Sq #?\ \& . |
| 2076 | .It Ev PS4 |
| 2077 | Used to prefix commands that are printed during execution tracing (see the |
| 2078 | .Ic set Fl x |
| 2079 | command below). |
| 2080 | Parameter, command, and arithmetic substitutions are performed |
| 2081 | before it is printed. |
| 2082 | The default is |
| 2083 | .Sq +\ \& . |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2084 | You may want to set it to |
| 2085 | .Sq \&[$EPOCHREALTIME]\ \& |
| 2086 | instead, to include timestamps. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2087 | .It Ev PWD |
| 2088 | The current working directory. |
| 2089 | May be unset or |
| 2090 | .Dv NULL |
| 2091 | if the shell doesn't know where it is. |
| 2092 | .It Ev RANDOM |
| 2093 | Each time |
| 2094 | .Ev RANDOM |
| 2095 | is referenced, it is assigned a number between 0 and 32767 from |
| 2096 | a Linear Congruential PRNG first. |
| 2097 | .It Ev REPLY |
| 2098 | Default parameter for the |
| 2099 | .Ic read |
| 2100 | command if no names are given. |
| 2101 | Also used in |
| 2102 | .Ic select |
| 2103 | loops to store the value that is read from standard input. |
| 2104 | .It Ev SECONDS |
| 2105 | The number of seconds since the shell started or, if the parameter has been |
| 2106 | assigned an integer value, the number of seconds since the assignment plus the |
| 2107 | value that was assigned. |
| 2108 | .It Ev TMOUT |
| 2109 | If set to a positive integer in an interactive shell, it specifies the maximum |
| 2110 | number of seconds the shell will wait for input after printing the primary |
| 2111 | prompt |
| 2112 | .Pq Ev PS1 . |
| 2113 | If the time is exceeded, the shell exits. |
| 2114 | .It Ev TMPDIR |
| 2115 | The directory temporary shell files are created in. |
| 2116 | If this parameter is not |
| 2117 | set, or does not contain the absolute path of a writable directory, temporary |
| 2118 | files are created in |
| 2119 | .Pa /tmp . |
| 2120 | .It Ev USER_ID |
| 2121 | The effective user id of the shell. |
| 2122 | .El |
| 2123 | .Ss Tilde expansion |
| 2124 | Tilde expansion which is done in parallel with parameter substitution, is done |
| 2125 | on words starting with an unquoted |
| 2126 | .Ql \*(TI . |
| 2127 | The characters following the tilde, up to the first |
| 2128 | .Ql / , |
| 2129 | if any, are assumed to be a login name. |
| 2130 | If the login name is empty, |
| 2131 | .Ql + , |
| 2132 | or |
| 2133 | .Ql \- , |
| 2134 | the value of the |
| 2135 | .Ev HOME , |
| 2136 | .Ev PWD , |
| 2137 | or |
| 2138 | .Ev OLDPWD |
| 2139 | parameter is substituted, respectively. |
| 2140 | Otherwise, the password file is |
| 2141 | searched for the login name, and the tilde expression is substituted with the |
| 2142 | user's home directory. |
| 2143 | If the login name is not found in the password file or |
| 2144 | if any quoting or parameter substitution occurs in the login name, no |
| 2145 | substitution is performed. |
| 2146 | .Pp |
| 2147 | In parameter assignments |
| 2148 | (such as those preceding a simple-command or those occurring |
| 2149 | in the arguments of |
| 2150 | .Ic alias , |
| 2151 | .Ic export , |
| 2152 | .Ic global , |
| 2153 | .Ic readonly , |
| 2154 | and |
| 2155 | .Ic typeset ) , |
| 2156 | tilde expansion is done after any assignment |
| 2157 | (i.e. after the equals sign) |
| 2158 | or after an unquoted colon |
| 2159 | .Pq Sq \&: ; |
| 2160 | login names are also delimited by colons. |
| 2161 | .Pp |
| 2162 | The home directory of previously expanded login names are cached and re-used. |
| 2163 | The |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2164 | .Ic alias Fl d |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2165 | command may be used to list, change, and add to this cache (e.g.\& |
| 2166 | .Ic alias \-d fac=/usr/local/facilities; cd \*(TIfac/bin ) . |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2167 | .Ss Brace expansion (alternation) |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2168 | Brace expressions take the following form: |
| 2169 | .Bd -unfilled -offset indent |
| 2170 | .Sm off |
| 2171 | .Xo |
| 2172 | .Ar prefix No { Ar str1 No ,..., |
| 2173 | .Ar strN No } Ar suffix |
| 2174 | .Xc |
| 2175 | .Sm on |
| 2176 | .Ed |
| 2177 | .Pp |
| 2178 | The expressions are expanded to |
| 2179 | .Ar N |
| 2180 | words, each of which is the concatenation of |
| 2181 | .Ar prefix , |
| 2182 | .Ar str Ns i , |
| 2183 | and |
| 2184 | .Ar suffix |
| 2185 | (e.g.\& |
| 2186 | .Dq a{c,b{X,Y},d}e |
| 2187 | expands to four words: |
| 2188 | .Dq ace , |
| 2189 | .Dq abXe , |
| 2190 | .Dq abYe , |
| 2191 | and |
| 2192 | .Dq ade ) . |
| 2193 | As noted in the example, brace expressions can be nested and the resulting |
| 2194 | words are not sorted. |
| 2195 | Brace expressions must contain an unquoted comma |
| 2196 | .Pq Sq \&, |
| 2197 | for expansion to occur (e.g.\& |
| 2198 | .Ic {} |
| 2199 | and |
| 2200 | .Ic {foo} |
| 2201 | are not expanded). |
| 2202 | Brace expansion is carried out after parameter substitution |
| 2203 | and before file name generation. |
| 2204 | .Ss File name patterns |
| 2205 | A file name pattern is a word containing one or more unquoted |
| 2206 | .Ql \&? , |
| 2207 | .Ql * , |
| 2208 | .Ql + , |
| 2209 | .Ql @ , |
| 2210 | or |
| 2211 | .Ql \&! |
| 2212 | characters or |
| 2213 | .Dq \&[..] |
| 2214 | sequences. |
| 2215 | Once brace expansion has been performed, the shell replaces file |
| 2216 | name patterns with the sorted names of all the files that match the pattern |
| 2217 | (if no files match, the word is left unchanged). |
| 2218 | The pattern elements have the following meaning: |
| 2219 | .Bl -tag -width Ds |
| 2220 | .It \&? |
| 2221 | Matches any single character. |
| 2222 | .It \&* |
| 2223 | Matches any sequence of octets. |
| 2224 | .It \&[..] |
| 2225 | Matches any of the octets inside the brackets. |
| 2226 | Ranges of octets can be specified by separating two octets by a |
| 2227 | .Ql \- |
| 2228 | (e.g.\& |
| 2229 | .Dq \&[a0\-9] |
| 2230 | matches the letter |
| 2231 | .Sq a |
| 2232 | or any digit). |
| 2233 | In order to represent itself, a |
| 2234 | .Ql \- |
| 2235 | must either be quoted or the first or last octet in the octet list. |
| 2236 | Similarly, a |
| 2237 | .Ql \&] |
| 2238 | must be quoted or the first octet in the list if it is to represent itself |
| 2239 | instead of the end of the list. |
| 2240 | Also, a |
| 2241 | .Ql \&! |
| 2242 | appearing at the start of the list has special meaning (see below), so to |
| 2243 | represent itself it must be quoted or appear later in the list. |
| 2244 | .It \&[!..] |
| 2245 | Like [..], |
| 2246 | except it matches any octet not inside the brackets. |
| 2247 | .Sm off |
| 2248 | .It *( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) |
| 2249 | .Sm on |
| 2250 | Matches any string of octets that matches zero or more occurrences of the |
| 2251 | specified patterns. |
| 2252 | Example: The pattern |
| 2253 | .Ic *(foo\*(Babar) |
| 2254 | matches the strings |
| 2255 | .Dq , |
| 2256 | .Dq foo , |
| 2257 | .Dq bar , |
| 2258 | .Dq foobarfoo , |
| 2259 | etc. |
| 2260 | .Sm off |
| 2261 | .It +( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) |
| 2262 | .Sm on |
| 2263 | Matches any string of octets that matches one or more occurrences of the |
| 2264 | specified patterns. |
| 2265 | Example: The pattern |
| 2266 | .Ic +(foo\*(Babar) |
| 2267 | matches the strings |
| 2268 | .Dq foo , |
| 2269 | .Dq bar , |
| 2270 | .Dq foobar , |
| 2271 | etc. |
| 2272 | .Sm off |
| 2273 | .It ?( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) |
| 2274 | .Sm on |
| 2275 | Matches the empty string or a string that matches one of the specified |
| 2276 | patterns. |
| 2277 | Example: The pattern |
| 2278 | .Ic ?(foo\*(Babar) |
| 2279 | only matches the strings |
| 2280 | .Dq , |
| 2281 | .Dq foo , |
| 2282 | and |
| 2283 | .Dq bar . |
| 2284 | .Sm off |
| 2285 | .It @( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) |
| 2286 | .Sm on |
| 2287 | Matches a string that matches one of the specified patterns. |
| 2288 | Example: The pattern |
| 2289 | .Ic @(foo\*(Babar) |
| 2290 | only matches the strings |
| 2291 | .Dq foo |
| 2292 | and |
| 2293 | .Dq bar . |
| 2294 | .Sm off |
| 2295 | .It !( Ar pattern\*(Ba No ...\*(Ba Ar pattern ) |
| 2296 | .Sm on |
| 2297 | Matches any string that does not match one of the specified patterns. |
| 2298 | Examples: The pattern |
| 2299 | .Ic !(foo\*(Babar) |
| 2300 | matches all strings except |
| 2301 | .Dq foo |
| 2302 | and |
| 2303 | .Dq bar ; |
| 2304 | the pattern |
| 2305 | .Ic !(*) |
| 2306 | matches no strings; the pattern |
| 2307 | .Ic !(?)*\& |
| 2308 | matches all strings (think about it). |
| 2309 | .El |
| 2310 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2311 | Note that complicated globbing, especially with alternatives, |
| 2312 | is slow; using separate comparisons may (or may not) be faster. |
| 2313 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2314 | Note that |
| 2315 | .Nm mksh |
| 2316 | .Po and Nm pdksh Pc |
| 2317 | never matches |
| 2318 | .Sq \&. |
| 2319 | and |
| 2320 | .Sq .. , |
| 2321 | but |
| 2322 | .At |
| 2323 | .Nm ksh , |
| 2324 | Bourne |
| 2325 | .Nm sh , |
| 2326 | and GNU |
| 2327 | .Nm bash |
| 2328 | do. |
| 2329 | .Pp |
| 2330 | Note that none of the above pattern elements match either a period |
| 2331 | .Pq Sq \&. |
| 2332 | at the start of a file name or a slash |
| 2333 | .Pq Sq / , |
| 2334 | even if they are explicitly used in a [..] sequence; also, the names |
| 2335 | .Sq \&. |
| 2336 | and |
| 2337 | .Sq .. |
| 2338 | are never matched, even by the pattern |
| 2339 | .Sq .* . |
| 2340 | .Pp |
| 2341 | If the |
| 2342 | .Ic markdirs |
| 2343 | option is set, any directories that result from file name generation are marked |
| 2344 | with a trailing |
| 2345 | .Ql / . |
| 2346 | .Ss Input/output redirection |
| 2347 | When a command is executed, its standard input, standard output, and standard |
| 2348 | error (file descriptors 0, 1, and 2, respectively) are normally inherited from |
| 2349 | the shell. |
| 2350 | Three exceptions to this are commands in pipelines, for which |
| 2351 | standard input and/or standard output are those set up by the pipeline, |
| 2352 | asynchronous commands created when job control is disabled, for which standard |
| 2353 | input is initially set to be from |
| 2354 | .Pa /dev/null , |
| 2355 | and commands for which any of the following redirections have been specified: |
| 2356 | .Bl -tag -width XXxxmarker |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2357 | .It \*(Gt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2358 | Standard output is redirected to |
| 2359 | .Ar file . |
| 2360 | If |
| 2361 | .Ar file |
| 2362 | does not exist, it is created; if it does exist, is a regular file, and the |
| 2363 | .Ic noclobber |
| 2364 | option is set, an error occurs; otherwise, the file is truncated. |
| 2365 | Note that this means the command |
| 2366 | .Ic cmd \*(Ltfoo \*(Gtfoo |
| 2367 | will open |
| 2368 | .Ar foo |
| 2369 | for reading and then truncate it when it opens it for writing, before |
| 2370 | .Ar cmd |
| 2371 | gets a chance to actually read |
| 2372 | .Ar foo . |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2373 | .It \*(Gt\*(Ba Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2374 | Same as |
| 2375 | .Ic \*(Gt , |
| 2376 | except the file is truncated, even if the |
| 2377 | .Ic noclobber |
| 2378 | option is set. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2379 | .It \*(Gt\*(Gt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2380 | Same as |
| 2381 | .Ic \*(Gt , |
| 2382 | except if |
| 2383 | .Ar file |
| 2384 | exists it is appended to instead of being truncated. |
| 2385 | Also, the file is opened |
| 2386 | in append mode, so writes always go to the end of the file (see |
| 2387 | .Xr open 2 ) . |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2388 | .It \*(Lt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2389 | Standard input is redirected from |
| 2390 | .Ar file , |
| 2391 | which is opened for reading. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2392 | .It \*(Lt\*(Gt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2393 | Same as |
| 2394 | .Ic \*(Lt , |
| 2395 | except the file is opened for reading and writing. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2396 | .It \*(Lt\*(Lt Ns Ar marker |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2397 | After reading the command line containing this kind of redirection (called a |
| 2398 | .Dq here document ) , |
| 2399 | the shell copies lines from the command source into a temporary file until a |
| 2400 | line matching |
| 2401 | .Ar marker |
| 2402 | is read. |
| 2403 | When the command is executed, standard input is redirected from the |
| 2404 | temporary file. |
| 2405 | If |
| 2406 | .Ar marker |
| 2407 | contains no quoted characters, the contents of the temporary file are processed |
| 2408 | as if enclosed in double quotes each time the command is executed, so |
| 2409 | parameter, command, and arithmetic substitutions are performed, along with |
| 2410 | backslash |
| 2411 | .Pq Sq \e |
| 2412 | escapes for |
| 2413 | .Ql $ , |
| 2414 | .Ql \` , |
| 2415 | .Ql \e , |
| 2416 | and |
| 2417 | .Ql \enewline , |
| 2418 | but not for |
| 2419 | .Ql \&" . |
| 2420 | If multiple here documents are used on the same command line, they are saved in |
| 2421 | order. |
| 2422 | .Pp |
| 2423 | If no |
| 2424 | .Ar marker |
| 2425 | is given, the here document ends at the next |
| 2426 | .Ic \*(Lt\*(Lt |
| 2427 | and substitution will be performed. |
| 2428 | If |
| 2429 | .Ar marker |
| 2430 | is only a set of either single |
| 2431 | .Dq \*(aq\*(aq |
| 2432 | or double |
| 2433 | .Sq \&"" |
| 2434 | quotes with nothing in between, the here document ends at the next empty line |
| 2435 | and substitution will not be performed. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2436 | .It \*(Lt\*(Lt\- Ns Ar marker |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2437 | Same as |
| 2438 | .Ic \*(Lt\*(Lt , |
| 2439 | except leading tabs are stripped from lines in the here document. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2440 | .It \*(Lt\*(Lt\*(Lt Ns Ar word |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2441 | Same as |
| 2442 | .Ic \*(Lt\*(Lt , |
| 2443 | except that |
| 2444 | .Ar word |
| 2445 | .Em is |
| 2446 | the here document. |
| 2447 | This is called a here string. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2448 | .It \*(Lt& Ns Ar fd |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2449 | Standard input is duplicated from file descriptor |
| 2450 | .Ar fd . |
| 2451 | .Ar fd |
| 2452 | can be a number, indicating the number of an existing file descriptor; |
| 2453 | the letter |
| 2454 | .Ql p , |
| 2455 | indicating the file descriptor associated with the output of the current |
| 2456 | co-process; or the character |
| 2457 | .Ql \- , |
| 2458 | indicating standard input is to be closed. |
| 2459 | Note that |
| 2460 | .Ar fd |
| 2461 | is limited to a single digit in most shell implementations. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2462 | .It \*(Gt& Ns Ar fd |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2463 | Same as |
| 2464 | .Ic \*(Lt& , |
| 2465 | except the operation is done on standard output. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2466 | .It &\*(Gt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2467 | Same as |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2468 | .Ic \*(Gt Ns Ar file 2\*(Gt&1 . |
| 2469 | This is a deprecated (legacy) GNU |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2470 | .Nm bash |
| 2471 | extension supported by |
| 2472 | .Nm |
| 2473 | which also supports the preceding explicit fd number, for example, |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2474 | .Ic 3&\*(Gt Ns Ar file |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2475 | is the same as |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2476 | .Ic 3\*(Gt Ns Ar file 2\*(Gt&3 |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2477 | in |
| 2478 | .Nm |
| 2479 | but a syntax error in GNU |
| 2480 | .Nm bash . |
| 2481 | .It Xo |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2482 | .No &\*(Gt\*(Ba Ns Ar file , |
| 2483 | .No &\*(Gt\*(Gt Ns Ar file , |
| 2484 | .No &\*(Gt& Ns Ar fd |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2485 | .Xc |
| 2486 | Same as |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2487 | .Ic \*(Gt\*(Ba Ns Ar file , |
| 2488 | .Ic \*(Gt\*(Gt Ns Ar file , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2489 | or |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2490 | .Ic \*(Gt& Ns Ar fd , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2491 | followed by |
| 2492 | .Ic 2\*(Gt&1 , |
| 2493 | as above. |
| 2494 | These are |
| 2495 | .Nm |
| 2496 | extensions. |
| 2497 | .El |
| 2498 | .Pp |
| 2499 | In any of the above redirections, the file descriptor that is redirected |
| 2500 | (i.e. standard input or standard output) |
| 2501 | can be explicitly given by preceding the |
| 2502 | redirection with a number (portably, only a single digit). |
| 2503 | Parameter, command, and arithmetic |
| 2504 | substitutions, tilde substitutions, and (if the shell is interactive) |
| 2505 | file name generation are all performed on the |
| 2506 | .Ar file , |
| 2507 | .Ar marker , |
| 2508 | and |
| 2509 | .Ar fd |
| 2510 | arguments of redirections. |
| 2511 | Note, however, that the results of any file name |
| 2512 | generation are only used if a single file is matched; if multiple files match, |
| 2513 | the word with the expanded file name generation characters is used. |
| 2514 | Note |
| 2515 | that in restricted shells, redirections which can create files cannot be used. |
| 2516 | .Pp |
| 2517 | For simple-commands, redirections may appear anywhere in the command; for |
| 2518 | compound-commands |
| 2519 | .Po |
| 2520 | .Ic if |
| 2521 | statements, etc. |
| 2522 | .Pc , |
| 2523 | any redirections must appear at the end. |
| 2524 | Redirections are processed after |
| 2525 | pipelines are created and in the order they are given, so the following |
| 2526 | will print an error with a line number prepended to it: |
| 2527 | .Pp |
| 2528 | .D1 $ cat /foo/bar 2\*(Gt&1 \*(Gt/dev/null \*(Ba pr \-n \-t |
| 2529 | .Pp |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2530 | File descriptors created by I/O redirections are private to the shell. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2531 | .Ss Arithmetic expressions |
| 2532 | Integer arithmetic expressions can be used with the |
| 2533 | .Ic let |
| 2534 | command, inside $((..)) expressions, inside array references (e.g.\& |
| 2535 | .Ar name Ns Bq Ar expr ) , |
| 2536 | as numeric arguments to the |
| 2537 | .Ic test |
| 2538 | command, and as the value of an assignment to an integer parameter. |
Elliott Hughes | f7f7956 | 2014-10-07 15:04:14 -0700 | [diff] [blame] | 2539 | .Em Warning : |
| 2540 | This also affects implicit conversion to integer, for example as done by the |
| 2541 | .Ic let |
| 2542 | command. |
| 2543 | .Em Never |
| 2544 | use unchecked user input, e.g. from the environment, in arithmetics! |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2545 | .Pp |
| 2546 | Expressions are calculated using signed arithmetic and the |
| 2547 | .Vt mksh_ari_t |
| 2548 | type (a 32-bit signed integer), unless they begin with a sole |
| 2549 | .Sq # |
| 2550 | character, in which case they use |
| 2551 | .Vt mksh_uari_t |
| 2552 | .Po a 32-bit unsigned integer Pc . |
| 2553 | .Pp |
| 2554 | Expressions may contain alpha-numeric parameter identifiers, array references, |
| 2555 | and integer constants and may be combined with the following C operators |
| 2556 | (listed and grouped in increasing order of precedence): |
| 2557 | .Pp |
| 2558 | Unary operators: |
| 2559 | .Bd -literal -offset indent |
| 2560 | + \- ! \*(TI ++ \-\- |
| 2561 | .Ed |
| 2562 | .Pp |
| 2563 | Binary operators: |
| 2564 | .Bd -literal -offset indent |
| 2565 | , |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2566 | = += \-= *= /= %= \*(Lt\*(Lt\*(Lt= \*(Gt\*(Gt\*(Gt= \*(Lt\*(Lt= \*(Gt\*(Gt= &= \*(ha= \*(Ba= |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2567 | \*(Ba\*(Ba |
| 2568 | && |
| 2569 | \*(Ba |
| 2570 | \*(ha |
| 2571 | & |
| 2572 | == != |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2573 | \*(Lt \*(Lt= \*(Gt \*(Gt= |
| 2574 | \*(Lt\*(Lt\*(Lt \*(Gt\*(Gt\*(Gt \*(Lt\*(Lt \*(Gt\*(Gt |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2575 | + \- |
| 2576 | * / % |
| 2577 | .Ed |
| 2578 | .Pp |
| 2579 | Ternary operators: |
| 2580 | .Bd -literal -offset indent |
| 2581 | ?: (precedence is immediately higher than assignment) |
| 2582 | .Ed |
| 2583 | .Pp |
| 2584 | Grouping operators: |
| 2585 | .Bd -literal -offset indent |
| 2586 | ( ) |
| 2587 | .Ed |
| 2588 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2589 | Integer constants and expressions are calculated using an exactly 32-bit |
| 2590 | wide, signed or unsigned, type with silent wraparound on integer overflow. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2591 | Integer constants may be specified with arbitrary bases using the notation |
| 2592 | .Ar base Ns # Ns Ar number , |
| 2593 | where |
| 2594 | .Ar base |
| 2595 | is a decimal integer specifying the base, and |
| 2596 | .Ar number |
| 2597 | is a number in the specified base. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2598 | Additionally, base-16 integers may be specified by prefixing them with |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2599 | .Sq 0x |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2600 | .Pq case-insensitive |
| 2601 | in all forms of arithmetic expressions, except as numeric arguments to the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2602 | .Ic test |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2603 | built-in command. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2604 | Prefixing numbers with a sole digit zero |
| 2605 | .Pq Sq 0 |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2606 | does not cause interpretation as octal, as that's unsafe to do. |
| 2607 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2608 | As a special |
| 2609 | .Nm mksh |
| 2610 | extension, numbers to the base of one are treated as either (8-bit |
| 2611 | transparent) ASCII or Unicode codepoints, depending on the shell's |
| 2612 | .Ic utf8\-mode |
| 2613 | flag (current setting). |
| 2614 | The |
| 2615 | .At |
| 2616 | .Nm ksh93 |
| 2617 | syntax of |
| 2618 | .Dq \*(aqx\*(aq |
| 2619 | instead of |
| 2620 | .Dq 1#x |
| 2621 | is also supported. |
| 2622 | Note that NUL bytes (integral value of zero) cannot be used. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2623 | An unset or empty parameter evaluates to 0 in integer context. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2624 | In Unicode mode, raw octets are mapped into the range EF80..EFFF as in |
| 2625 | OPTU-8, which is in the PUA and has been assigned by CSUR for this use. |
| 2626 | If more than one octet in ASCII mode, or a sequence of more than one |
| 2627 | octet not forming a valid and minimal CESU-8 sequence is passed, the |
| 2628 | behaviour is undefined (usually, the shell aborts with a parse error, |
| 2629 | but rarely, it succeeds, e.g. on the sequence C2 20). |
| 2630 | That's why you should always use ASCII mode unless you know that the |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2631 | input is well-formed UTF-8 in the range of 0000..FFFD if you use this |
| 2632 | feature, as opposed to |
| 2633 | .Ic read Fl a . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2634 | .Pp |
| 2635 | The operators are evaluated as follows: |
| 2636 | .Bl -tag -width Ds -offset indent |
| 2637 | .It unary + |
| 2638 | Result is the argument (included for completeness). |
| 2639 | .It unary \- |
| 2640 | Negation. |
| 2641 | .It \&! |
| 2642 | Logical NOT; |
| 2643 | the result is 1 if argument is zero, 0 if not. |
| 2644 | .It \*(TI |
| 2645 | Arithmetic (bit-wise) NOT. |
| 2646 | .It ++ |
| 2647 | Increment; must be applied to a parameter (not a literal or other expression). |
| 2648 | The parameter is incremented by 1. |
| 2649 | When used as a prefix operator, the result |
| 2650 | is the incremented value of the parameter; when used as a postfix operator, the |
| 2651 | result is the original value of the parameter. |
| 2652 | .It \-\- |
| 2653 | Similar to |
| 2654 | .Ic ++ , |
| 2655 | except the parameter is decremented by 1. |
| 2656 | .It \&, |
| 2657 | Separates two arithmetic expressions; the left-hand side is evaluated first, |
| 2658 | then the right. |
| 2659 | The result is the value of the expression on the right-hand side. |
| 2660 | .It = |
| 2661 | Assignment; the variable on the left is set to the value on the right. |
| 2662 | .It Xo |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2663 | .No += \-= *= /= %= \*(Lt\*(Lt\*(Lt= \*(Gt\*(Gt\*(Gt= |
| 2664 | .No \*(Lt\*(Lt= \*(Gt\*(Gt= &= \*(ha= \*(Ba= |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2665 | .Xc |
| 2666 | Assignment operators. |
| 2667 | .Sm off |
| 2668 | .Ao Ar var Ac Xo |
| 2669 | .Aq Ar op |
| 2670 | .No = Aq Ar expr |
| 2671 | .Xc |
| 2672 | .Sm on |
| 2673 | is the same as |
| 2674 | .Sm off |
| 2675 | .Ao Ar var Ac Xo |
| 2676 | .No = Aq Ar var |
| 2677 | .Aq Ar op |
| 2678 | .Aq Ar expr , |
| 2679 | .Xc |
| 2680 | .Sm on |
| 2681 | with any operator precedence in |
| 2682 | .Aq Ar expr |
| 2683 | preserved. |
| 2684 | For example, |
| 2685 | .Dq var1 *= 5 + 3 |
| 2686 | is the same as specifying |
| 2687 | .Dq var1 = var1 * (5 + 3) . |
| 2688 | .It \*(Ba\*(Ba |
| 2689 | Logical OR; |
| 2690 | the result is 1 if either argument is non-zero, 0 if not. |
| 2691 | The right argument is evaluated only if the left argument is zero. |
| 2692 | .It && |
| 2693 | Logical AND; |
| 2694 | the result is 1 if both arguments are non-zero, 0 if not. |
| 2695 | The right argument is evaluated only if the left argument is non-zero. |
| 2696 | .It \*(Ba |
| 2697 | Arithmetic (bit-wise) OR. |
| 2698 | .It \*(ha |
| 2699 | Arithmetic (bit-wise) XOR |
| 2700 | (exclusive-OR). |
| 2701 | .It & |
| 2702 | Arithmetic (bit-wise) AND. |
| 2703 | .It == |
| 2704 | Equal; the result is 1 if both arguments are equal, 0 if not. |
| 2705 | .It != |
| 2706 | Not equal; the result is 0 if both arguments are equal, 1 if not. |
| 2707 | .It \*(Lt |
| 2708 | Less than; the result is 1 if the left argument is less than the right, 0 if |
| 2709 | not. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2710 | .It \*(Lt= \*(Gt \*(Gt= |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 2711 | Less than or equal, greater than, greater than or equal. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2712 | See |
| 2713 | .Ic \*(Lt . |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2714 | .It \*(Lt\*(Lt\*(Lt \*(Gt\*(Gt\*(Gt |
| 2715 | Rotate left (right); the result is similar to shift (see |
| 2716 | .Ic \*(Lt\*(Lt ) |
| 2717 | except that the bits shifted out at one end are shifted in |
| 2718 | at the other end, instead of zero or sign bits. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2719 | .It \*(Lt\*(Lt \*(Gt\*(Gt |
| 2720 | Shift left (right); the result is the left argument with its bits shifted left |
| 2721 | (right) by the amount given in the right argument. |
| 2722 | .It + \- * / |
| 2723 | Addition, subtraction, multiplication, and division. |
| 2724 | .It % |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 2725 | Remainder; the result is the symmetric remainder of the division of the left |
| 2726 | argument by the right. |
| 2727 | To get the mathematical modulus of |
| 2728 | .Dq a Ic mod No b , |
| 2729 | use the formula |
| 2730 | .Do |
| 2731 | .Pq a % b + b |
| 2732 | .No % b |
| 2733 | .Dc . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2734 | .It Xo |
| 2735 | .Sm off |
| 2736 | .Aq Ar arg1 ? |
| 2737 | .Aq Ar arg2 : |
| 2738 | .Aq Ar arg3 |
| 2739 | .Sm on |
| 2740 | .Xc |
| 2741 | If |
| 2742 | .Aq Ar arg1 |
| 2743 | is non-zero, the result is |
| 2744 | .Aq Ar arg2 ; |
| 2745 | otherwise the result is |
| 2746 | .Aq Ar arg3 . |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2747 | The non-result argument is not evaluated. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2748 | .El |
| 2749 | .Ss Co-processes |
| 2750 | A co-process (which is a pipeline created with the |
| 2751 | .Sq \*(Ba& |
| 2752 | operator) is an asynchronous process that the shell can both write to (using |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2753 | .Ic print Fl p ) |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2754 | and read from (using |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2755 | .Ic read Fl p ) . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2756 | The input and output of the co-process can also be manipulated using |
| 2757 | .Ic \*(Gt&p |
| 2758 | and |
| 2759 | .Ic \*(Lt&p |
| 2760 | redirections, respectively. |
| 2761 | Once a co-process has been started, another can't |
| 2762 | be started until the co-process exits, or until the co-process's input has been |
| 2763 | redirected using an |
| 2764 | .Ic exec Ar n Ns Ic \*(Gt&p |
| 2765 | redirection. |
| 2766 | If a co-process's input is redirected in this way, the next |
| 2767 | co-process to be started will share the output with the first co-process, |
| 2768 | unless the output of the initial co-process has been redirected using an |
| 2769 | .Ic exec Ar n Ns Ic \*(Lt&p |
| 2770 | redirection. |
| 2771 | .Pp |
| 2772 | Some notes concerning co-processes: |
| 2773 | .Bl -bullet |
| 2774 | .It |
| 2775 | The only way to close the co-process's input (so the co-process reads an |
| 2776 | end-of-file) is to redirect the input to a numbered file descriptor and then |
| 2777 | close that file descriptor: |
| 2778 | .Ic exec 3\*(Gt&p; exec 3\*(Gt&\- |
| 2779 | .It |
| 2780 | In order for co-processes to share a common output, the shell must keep the |
| 2781 | write portion of the output pipe open. |
| 2782 | This means that end-of-file will not be |
| 2783 | detected until all co-processes sharing the co-process's output have exited |
| 2784 | (when they all exit, the shell closes its copy of the pipe). |
| 2785 | This can be |
| 2786 | avoided by redirecting the output to a numbered file descriptor (as this also |
| 2787 | causes the shell to close its copy). |
| 2788 | Note that this behaviour is slightly |
| 2789 | different from the original Korn shell which closes its copy of the write |
| 2790 | portion of the co-process output when the most recently started co-process |
| 2791 | (instead of when all sharing co-processes) exits. |
| 2792 | .It |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2793 | .Ic print Fl p |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2794 | will ignore |
| 2795 | .Dv SIGPIPE |
| 2796 | signals during writes if the signal is not being trapped or ignored; the same |
| 2797 | is true if the co-process input has been duplicated to another file descriptor |
| 2798 | and |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2799 | .Ic print Fl u Ns Ar n |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2800 | is used. |
| 2801 | .El |
| 2802 | .Ss Functions |
| 2803 | Functions are defined using either Korn shell |
| 2804 | .Ic function Ar function-name |
| 2805 | syntax or the Bourne/POSIX shell |
| 2806 | .Ar function-name Ns \&() |
| 2807 | syntax (see below for the difference between the two forms). |
| 2808 | Functions are like |
| 2809 | .Li .\(hyscripts |
| 2810 | (i.e. scripts sourced using the |
| 2811 | .Sq \&. |
| 2812 | built-in) |
| 2813 | in that they are executed in the current environment. |
| 2814 | However, unlike |
| 2815 | .Li .\(hyscripts , |
| 2816 | shell arguments (i.e. positional parameters $1, $2, etc.)\& |
| 2817 | are never visible inside them. |
| 2818 | When the shell is determining the location of a command, functions |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2819 | are searched after special built-in commands, before builtins and the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2820 | .Ev PATH |
| 2821 | is searched. |
| 2822 | .Pp |
| 2823 | An existing function may be deleted using |
| 2824 | .Ic unset Fl f Ar function-name . |
| 2825 | A list of functions can be obtained using |
| 2826 | .Ic typeset +f |
| 2827 | and the function definitions can be listed using |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2828 | .Ic typeset Fl f . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2829 | The |
| 2830 | .Ic autoload |
| 2831 | command (which is an alias for |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2832 | .Ic typeset Fl fu ) |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2833 | may be used to create undefined functions: when an undefined function is |
| 2834 | executed, the shell searches the path specified in the |
| 2835 | .Ev FPATH |
| 2836 | parameter for a file with the same name as the function which, if found, is |
| 2837 | read and executed. |
| 2838 | If after executing the file the named function is found to |
| 2839 | be defined, the function is executed; otherwise, the normal command search is |
| 2840 | continued (i.e. the shell searches the regular built-in command table and |
| 2841 | .Ev PATH ) . |
| 2842 | Note that if a command is not found using |
| 2843 | .Ev PATH , |
| 2844 | an attempt is made to autoload a function using |
| 2845 | .Ev FPATH |
| 2846 | (this is an undocumented feature of the original Korn shell). |
| 2847 | .Pp |
| 2848 | Functions can have two attributes, |
| 2849 | .Dq trace |
| 2850 | and |
| 2851 | .Dq export , |
| 2852 | which can be set with |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2853 | .Ic typeset Fl ft |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2854 | and |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2855 | .Ic typeset Fl fx , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2856 | respectively. |
| 2857 | When a traced function is executed, the shell's |
| 2858 | .Ic xtrace |
| 2859 | option is turned on for the function's duration. |
| 2860 | The |
| 2861 | .Dq export |
| 2862 | attribute of functions is currently not used. |
| 2863 | In the original Korn shell, |
| 2864 | exported functions are visible to shell scripts that are executed. |
| 2865 | .Pp |
| 2866 | Since functions are executed in the current shell environment, parameter |
| 2867 | assignments made inside functions are visible after the function completes. |
| 2868 | If this is not the desired effect, the |
| 2869 | .Ic typeset |
| 2870 | command can be used inside a function to create a local parameter. |
| 2871 | Note that |
| 2872 | .At |
| 2873 | .Nm ksh93 |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2874 | uses static scoping (one global scope, one local scope per function) |
| 2875 | and allows local variables only on Korn style functions, whereas |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2876 | .Nm mksh |
| 2877 | uses dynamic scoping (nested scopes of varying locality). |
| 2878 | Note that special parameters (e.g.\& |
| 2879 | .Ic \&$$ , $! ) |
| 2880 | can't be scoped in this way. |
| 2881 | .Pp |
| 2882 | The exit status of a function is that of the last command executed in the |
| 2883 | function. |
| 2884 | A function can be made to finish immediately using the |
| 2885 | .Ic return |
| 2886 | command; this may also be used to explicitly specify the exit status. |
| 2887 | .Pp |
| 2888 | Functions defined with the |
| 2889 | .Ic function |
| 2890 | reserved word are treated differently in the following ways from functions |
| 2891 | defined with the |
| 2892 | .Ic \&() |
| 2893 | notation: |
| 2894 | .Bl -bullet |
| 2895 | .It |
| 2896 | The $0 parameter is set to the name of the function |
| 2897 | (Bourne-style functions leave $0 untouched). |
| 2898 | .It |
| 2899 | Parameter assignments preceding function calls are not kept in the shell |
| 2900 | environment (executing Bourne-style functions will keep assignments). |
| 2901 | .It |
| 2902 | .Ev OPTIND |
| 2903 | is saved/reset and restored on entry and exit from the function so |
| 2904 | .Ic getopts |
| 2905 | can be used properly both inside and outside the function (Bourne-style |
| 2906 | functions leave |
| 2907 | .Ev OPTIND |
| 2908 | untouched, so using |
| 2909 | .Ic getopts |
| 2910 | inside a function interferes with using |
| 2911 | .Ic getopts |
| 2912 | outside the function). |
| 2913 | .It |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 2914 | Shell options |
| 2915 | .Pq Ic set Fl o |
| 2916 | have local scope, i.e. changes inside a function are reset upon its exit. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2917 | .El |
| 2918 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 2919 | In the future, the following differences may also be added: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2920 | .Bl -bullet |
| 2921 | .It |
| 2922 | A separate trap/signal environment will be used during the execution of |
| 2923 | functions. |
| 2924 | This will mean that traps set inside a function will not affect the |
| 2925 | shell's traps and signals that are not ignored in the shell (but may be |
| 2926 | trapped) will have their default effect in a function. |
| 2927 | .It |
| 2928 | The EXIT trap, if set in a function, will be executed after the function |
| 2929 | returns. |
| 2930 | .El |
| 2931 | .Ss Command execution |
| 2932 | After evaluation of command-line arguments, redirections, and parameter |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2933 | assignments, the type of command is determined: a special built-in command, |
| 2934 | a function, a normal builtin, or the name of a file to execute found using the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2935 | .Ev PATH |
| 2936 | parameter. |
| 2937 | The checks are made in the above order. |
| 2938 | Special built-in commands differ from other commands in that the |
| 2939 | .Ev PATH |
| 2940 | parameter is not used to find them, an error during their execution can |
| 2941 | cause a non-interactive shell to exit, and parameter assignments that are |
| 2942 | specified before the command are kept after the command completes. |
| 2943 | Regular built-in commands are different only in that the |
| 2944 | .Ev PATH |
| 2945 | parameter is not used to find them. |
| 2946 | .Pp |
| 2947 | The original |
| 2948 | .Nm ksh |
| 2949 | and POSIX differ somewhat in which commands are considered |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2950 | special or regular. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2951 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2952 | POSIX special built-in utilities: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2953 | .Pp |
| 2954 | .Ic \&. , \&: , break , continue , |
| 2955 | .Ic eval , exec , exit , export , |
| 2956 | .Ic readonly , return , set , shift , |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2957 | .Ic times , trap , unset |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2958 | .Pp |
| 2959 | Additional |
| 2960 | .Nm |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2961 | commands keeping assignments: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2962 | .Pp |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2963 | .Ic builtin , global , source , typeset , |
| 2964 | .Ic wait |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2965 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2966 | Builtins that are not special: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2967 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 2968 | .Ic [ , alias , bg , bind , |
| 2969 | .Ic cat , cd , command , echo , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2970 | .Ic false , fc , fg , getopts , |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2971 | .Ic jobs , kill , let , print , |
| 2972 | .Ic pwd , read , realpath , rename , |
| 2973 | .Ic sleep , suspend , test , true , |
| 2974 | .Ic ulimit , umask , unalias , whence |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2975 | .Pp |
| 2976 | Once the type of command has been determined, any command-line parameter |
| 2977 | assignments are performed and exported for the duration of the command. |
| 2978 | .Pp |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 2979 | The following describes the special and regular built-in commands and |
| 2980 | builtin-like reserved words: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 2981 | .Pp |
| 2982 | .Bl -tag -width false -compact |
| 2983 | .It Ic \&. Ar file Op Ar arg ... |
| 2984 | This is called the |
| 2985 | .Dq dot |
| 2986 | command. |
| 2987 | Execute the commands in |
| 2988 | .Ar file |
| 2989 | in the current environment. |
| 2990 | The file is searched for in the directories of |
| 2991 | .Ev PATH . |
| 2992 | If arguments are given, the positional parameters may be used to access them |
| 2993 | while |
| 2994 | .Ar file |
| 2995 | is being executed. |
| 2996 | If no arguments are given, the positional parameters are |
| 2997 | those of the environment the command is used in. |
| 2998 | .Pp |
| 2999 | .It Ic \&: Op Ar ... |
| 3000 | The null command. |
| 3001 | Exit status is set to zero. |
| 3002 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 3003 | .It Ic \&[ Ar expression Ic \&] |
| 3004 | See |
| 3005 | .Ic test . |
| 3006 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3007 | .It Xo Ic alias |
| 3008 | .Oo Fl d \*(Ba t Oo Fl r Oc \*(Ba |
| 3009 | .Cm +\-x Oc |
| 3010 | .Op Fl p |
| 3011 | .Op Cm + |
| 3012 | .Oo Ar name |
| 3013 | .Op Ns = Ns Ar value |
| 3014 | .Ar ... Oc |
| 3015 | .Xc |
| 3016 | Without arguments, |
| 3017 | .Ic alias |
| 3018 | lists all aliases. |
| 3019 | For any name without a value, the existing alias is listed. |
| 3020 | Any name with a value defines an alias (see |
| 3021 | .Sx Aliases |
| 3022 | above). |
| 3023 | .Pp |
| 3024 | When listing aliases, one of two formats is used. |
| 3025 | Normally, aliases are listed as |
| 3026 | .Ar name Ns = Ns Ar value , |
| 3027 | where |
| 3028 | .Ar value |
| 3029 | is quoted. |
| 3030 | If options were preceded with |
| 3031 | .Ql + , |
| 3032 | or a lone |
| 3033 | .Ql + |
| 3034 | is given on the command line, only |
| 3035 | .Ar name |
| 3036 | is printed. |
| 3037 | .Pp |
| 3038 | The |
| 3039 | .Fl d |
| 3040 | option causes directory aliases which are used in tilde expansion to be |
| 3041 | listed or set (see |
| 3042 | .Sx Tilde expansion |
| 3043 | above). |
| 3044 | .Pp |
| 3045 | If the |
| 3046 | .Fl p |
| 3047 | option is used, each alias is prefixed with the string |
| 3048 | .Dq alias\ \& . |
| 3049 | .Pp |
| 3050 | The |
| 3051 | .Fl t |
| 3052 | option indicates that tracked aliases are to be listed/set (values specified on |
| 3053 | the command line are ignored for tracked aliases). |
| 3054 | The |
| 3055 | .Fl r |
| 3056 | option indicates that all tracked aliases are to be reset. |
| 3057 | .Pp |
| 3058 | The |
| 3059 | .Fl x |
| 3060 | option sets |
| 3061 | .Pq Ic +x No clears |
| 3062 | the export attribute of an alias, or, if no names are given, lists the aliases |
| 3063 | with the export attribute (exporting an alias has no effect). |
| 3064 | .Pp |
| 3065 | .It Ic bg Op Ar job ... |
| 3066 | Resume the specified stopped job(s) in the background. |
| 3067 | If no jobs are specified, |
| 3068 | .Ic %+ |
| 3069 | is assumed. |
| 3070 | See |
| 3071 | .Sx Job control |
| 3072 | below for more information. |
| 3073 | .Pp |
| 3074 | .It Ic bind Op Fl l |
| 3075 | The current bindings are listed. |
| 3076 | If the |
| 3077 | .Fl l |
| 3078 | flag is given, |
| 3079 | .Ic bind |
| 3080 | instead lists the names of the functions to which keys may be bound. |
| 3081 | See |
| 3082 | .Sx Emacs editing mode |
| 3083 | for more information. |
| 3084 | .Pp |
| 3085 | .It Xo Ic bind Op Fl m |
| 3086 | .Ar string Ns = Ns Op Ar substitute |
| 3087 | .Ar ... |
| 3088 | .Xc |
| 3089 | .It Xo Ic bind |
| 3090 | .Ar string Ns = Ns Op Ar editing-command |
| 3091 | .Ar ... |
| 3092 | .Xc |
| 3093 | The specified editing command is bound to the given |
| 3094 | .Ar string , |
| 3095 | which should consist of a control character |
| 3096 | optionally preceded by one of the two prefix characters |
| 3097 | and optionally succeded by a tilde character. |
| 3098 | Future input of the |
| 3099 | .Ar string |
| 3100 | will cause the editing command to be immediately invoked. |
| 3101 | If the |
| 3102 | .Fl m |
| 3103 | flag is given, the specified input |
| 3104 | .Ar string |
| 3105 | will afterwards be immediately replaced by the given |
| 3106 | .Ar substitute |
| 3107 | string which may contain editing commands but not other macros. |
| 3108 | If a tilde postfix is given, a tilde trailing the one or |
| 3109 | two prefices and the control character is ignored, any |
| 3110 | other trailing character will be processed afterwards. |
| 3111 | .Pp |
| 3112 | Control characters may be written using caret notation |
| 3113 | i.e. \*(haX represents Ctrl-X. |
| 3114 | Note that although only two prefix characters (usually ESC and \*(haX) |
| 3115 | are supported, some multi-character sequences can be supported. |
| 3116 | .Pp |
| 3117 | The following default bindings show how the arrow keys, the home, end and |
| 3118 | delete key on a BSD wsvt25, xterm\-xfree86 or GNU screen terminal are bound |
| 3119 | (of course some escape sequences won't work out quite this nicely): |
| 3120 | .Bd -literal -offset indent |
| 3121 | bind \*(aq\*(haX\*(aq=prefix\-2 |
| 3122 | bind \*(aq\*(ha[[\*(aq=prefix\-2 |
| 3123 | bind \*(aq\*(haXA\*(aq=up\-history |
| 3124 | bind \*(aq\*(haXB\*(aq=down\-history |
| 3125 | bind \*(aq\*(haXC\*(aq=forward\-char |
| 3126 | bind \*(aq\*(haXD\*(aq=backward\-char |
| 3127 | bind \*(aq\*(haX1\*(TI\*(aq=beginning\-of\-line |
| 3128 | bind \*(aq\*(haX7\*(TI\*(aq=beginning\-of\-line |
| 3129 | bind \*(aq\*(haXH\*(aq=beginning\-of\-line |
| 3130 | bind \*(aq\*(haX4\*(TI\*(aq=end\-of\-line |
| 3131 | bind \*(aq\*(haX8\*(TI\*(aq=end\-of\-line |
| 3132 | bind \*(aq\*(haXF\*(aq=end\-of\-line |
| 3133 | bind \*(aq\*(haX3\*(TI\*(aq=delete\-char\-forward |
| 3134 | .Ed |
| 3135 | .Pp |
| 3136 | .It Ic break Op Ar level |
| 3137 | Exit the |
| 3138 | .Ar level Ns th |
| 3139 | inner-most |
| 3140 | .Ic for , |
| 3141 | .Ic select , |
| 3142 | .Ic until , |
| 3143 | or |
| 3144 | .Ic while |
| 3145 | loop. |
| 3146 | .Ar level |
| 3147 | defaults to 1. |
| 3148 | .Pp |
| 3149 | .It Xo |
| 3150 | .Ic builtin |
| 3151 | .Op Fl \- |
| 3152 | .Ar command Op Ar arg ... |
| 3153 | .Xc |
| 3154 | Execute the built-in command |
| 3155 | .Ar command . |
| 3156 | .Pp |
| 3157 | .It Xo |
| 3158 | .Ic cat |
| 3159 | .Op Fl u |
| 3160 | .Op Ar |
| 3161 | .Xc |
| 3162 | Read files sequentially, in command line order, and write them to |
| 3163 | standard output. |
| 3164 | If a |
| 3165 | .Ar file |
| 3166 | is a single dash |
| 3167 | .Pq Sq - |
| 3168 | or absent, read from standard input. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3169 | For direct builtin calls, the |
| 3170 | .Tn POSIX |
| 3171 | .Fl u |
| 3172 | option is supported as a no-op. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3173 | For calls from shell, if any options are given, an external |
| 3174 | .Xr cat 1 |
| 3175 | utility is preferred over the builtin. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3176 | .Pp |
| 3177 | .It Xo |
| 3178 | .Ic cd |
| 3179 | .Op Fl L |
| 3180 | .Op Ar dir |
| 3181 | .Xc |
| 3182 | .It Xo |
| 3183 | .Ic cd |
| 3184 | .Fl P Op Fl e |
| 3185 | .Op Ar dir |
| 3186 | .Xc |
| 3187 | .It Xo |
| 3188 | .Ic chdir |
| 3189 | .Op Fl eLP |
| 3190 | .Op Ar dir |
| 3191 | .Xc |
| 3192 | Set the working directory to |
| 3193 | .Ar dir . |
| 3194 | If the parameter |
| 3195 | .Ev CDPATH |
| 3196 | is set, it lists the search path for the directory containing |
| 3197 | .Ar dir . |
| 3198 | A |
| 3199 | .Dv NULL |
| 3200 | path means the current directory. |
| 3201 | If |
| 3202 | .Ar dir |
| 3203 | is found in any component of the |
| 3204 | .Ev CDPATH |
| 3205 | search path other than the |
| 3206 | .Dv NULL |
| 3207 | path, the name of the new working directory will be written to standard output. |
| 3208 | If |
| 3209 | .Ar dir |
| 3210 | is missing, the home directory |
| 3211 | .Ev HOME |
| 3212 | is used. |
| 3213 | If |
| 3214 | .Ar dir |
| 3215 | is |
| 3216 | .Ql \- , |
| 3217 | the previous working directory is used (see the |
| 3218 | .Ev OLDPWD |
| 3219 | parameter). |
| 3220 | .Pp |
| 3221 | If the |
| 3222 | .Fl L |
| 3223 | option (logical path) is used or if the |
| 3224 | .Ic physical |
| 3225 | option isn't set (see the |
| 3226 | .Ic set |
| 3227 | command below), references to |
| 3228 | .Sq .. |
| 3229 | in |
| 3230 | .Ar dir |
| 3231 | are relative to the path used to get to the directory. |
| 3232 | If the |
| 3233 | .Fl P |
| 3234 | option (physical path) is used or if the |
| 3235 | .Ic physical |
| 3236 | option is set, |
| 3237 | .Sq .. |
| 3238 | is relative to the filesystem directory tree. |
| 3239 | The |
| 3240 | .Ev PWD |
| 3241 | and |
| 3242 | .Ev OLDPWD |
| 3243 | parameters are updated to reflect the current and old working directory, |
| 3244 | respectively. |
| 3245 | If the |
| 3246 | .Fl e |
| 3247 | option is set for physical filesystem traversal, and |
| 3248 | .Ev PWD |
| 3249 | could not be set, the exit code is 1; greater than 1 if an |
| 3250 | error occurred, 0 otherwise. |
| 3251 | .Pp |
| 3252 | .It Xo |
| 3253 | .Ic cd |
| 3254 | .Op Fl eLP |
| 3255 | .Ar old new |
| 3256 | .Xc |
| 3257 | .It Xo |
| 3258 | .Ic chdir |
| 3259 | .Op Fl eLP |
| 3260 | .Ar old new |
| 3261 | .Xc |
| 3262 | The string |
| 3263 | .Ar new |
| 3264 | is substituted for |
| 3265 | .Ar old |
| 3266 | in the current directory, and the shell attempts to change to the new |
| 3267 | directory. |
| 3268 | .Pp |
| 3269 | .It Xo |
| 3270 | .Ic command |
| 3271 | .Op Fl pVv |
| 3272 | .Ar cmd |
| 3273 | .Op Ar arg ... |
| 3274 | .Xc |
| 3275 | If neither the |
| 3276 | .Fl v |
| 3277 | nor |
| 3278 | .Fl V |
| 3279 | option is given, |
| 3280 | .Ar cmd |
| 3281 | is executed exactly as if |
| 3282 | .Ic command |
| 3283 | had not been specified, with two exceptions: |
| 3284 | firstly, |
| 3285 | .Ar cmd |
| 3286 | cannot be a shell function; |
| 3287 | and secondly, special built-in commands lose their specialness |
| 3288 | (i.e. redirection and utility errors do not cause the shell to |
| 3289 | exit, and command assignments are not permanent). |
| 3290 | .Pp |
| 3291 | If the |
| 3292 | .Fl p |
| 3293 | option is given, a default search path is used instead of the current value of |
| 3294 | .Ev PATH , |
| 3295 | the actual value of which is system dependent. |
| 3296 | .Pp |
| 3297 | If the |
| 3298 | .Fl v |
| 3299 | option is given, instead of executing |
| 3300 | .Ar cmd , |
| 3301 | information about what would be executed is given (and the same is done for |
| 3302 | .Ar arg ... ) . |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3303 | For builtins, functions and keywords, their names are simply printed; |
| 3304 | for aliases, a command that defines them is printed; |
| 3305 | for utilities found by searching the |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3306 | .Ev PATH |
| 3307 | parameter, the full path of the command is printed. |
| 3308 | If no command is found |
| 3309 | (i.e. the path search fails), nothing is printed and |
| 3310 | .Ic command |
| 3311 | exits with a non-zero status. |
| 3312 | The |
| 3313 | .Fl V |
| 3314 | option is like the |
| 3315 | .Fl v |
| 3316 | option, except it is more verbose. |
| 3317 | .Pp |
| 3318 | .It Ic continue Op Ar level |
| 3319 | Jumps to the beginning of the |
| 3320 | .Ar level Ns th |
| 3321 | inner-most |
| 3322 | .Ic for , |
| 3323 | .Ic select , |
| 3324 | .Ic until , |
| 3325 | or |
| 3326 | .Ic while |
| 3327 | loop. |
| 3328 | .Ar level |
| 3329 | defaults to 1. |
| 3330 | .Pp |
| 3331 | .It Xo |
| 3332 | .Ic echo |
| 3333 | .Op Fl Een |
| 3334 | .Op Ar arg ... |
| 3335 | .Xc |
| 3336 | .Em Warning: |
| 3337 | this utility is not portable; use the Korn shell builtin |
| 3338 | .Ic print |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3339 | instead. |
| 3340 | .Pp |
| 3341 | Prints its arguments (separated by spaces) followed by a newline, to the |
| 3342 | standard output. |
| 3343 | The newline is suppressed if any of the arguments contain the |
| 3344 | backslash sequence |
| 3345 | .Ql \ec . |
| 3346 | See the |
| 3347 | .Ic print |
| 3348 | command below for a list of other backslash sequences that are recognised. |
| 3349 | .Pp |
| 3350 | The options are provided for compatibility with |
| 3351 | .Bx |
| 3352 | shell scripts. |
| 3353 | The |
| 3354 | .Fl n |
| 3355 | option suppresses the trailing newline, |
| 3356 | .Fl e |
| 3357 | enables backslash interpretation (a no-op, since this is normally done), and |
| 3358 | .Fl E |
| 3359 | suppresses backslash interpretation. |
| 3360 | .Pp |
| 3361 | If the |
| 3362 | .Ic posix |
| 3363 | or |
| 3364 | .Ic sh |
| 3365 | option is set or this is a direct builtin call, only the first argument |
| 3366 | is treated as an option, and only if it is exactly |
| 3367 | .Dq Fl n . |
| 3368 | Backslash interpretation is disabled. |
| 3369 | .Pp |
| 3370 | .It Ic eval Ar command ... |
| 3371 | The arguments are concatenated (with spaces between them) to form a single |
| 3372 | string which the shell then parses and executes in the current environment. |
| 3373 | .Pp |
| 3374 | .It Xo |
| 3375 | .Ic exec |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 3376 | .Op Fl a Ar argv0 |
| 3377 | .Op Fl c |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3378 | .Op Ar command Op Ar arg ... |
| 3379 | .Xc |
| 3380 | The command is executed without forking, replacing the shell process. |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 3381 | This is currently absolute, i.e.\& |
| 3382 | .Ic exec |
| 3383 | never returns, even if the |
| 3384 | .Ar command |
| 3385 | is not found. |
| 3386 | The |
| 3387 | .Fl a |
| 3388 | option permits setting a different |
| 3389 | .Li argv[0] |
| 3390 | value, and |
| 3391 | .Fl c |
| 3392 | clears the environment before executing the child process, except for the |
| 3393 | .Ev _ |
| 3394 | variable and direct assignments. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3395 | .Pp |
| 3396 | If no command is given except for I/O redirection, the I/O redirection is |
| 3397 | permanent and the shell is |
| 3398 | not replaced. |
| 3399 | Any file descriptors greater than 2 which are opened or |
| 3400 | .Xr dup 2 Ns 'd |
| 3401 | in this way are not made available to other executed commands (i.e. commands |
| 3402 | that are not built-in to the shell). |
| 3403 | Note that the Bourne shell differs here; |
| 3404 | it does pass these file descriptors on. |
| 3405 | .Pp |
| 3406 | .It Ic exit Op Ar status |
| 3407 | The shell exits with the specified exit status. |
| 3408 | If |
| 3409 | .Ar status |
| 3410 | is not specified, the exit status is the current value of the |
| 3411 | .Ic $?\& |
| 3412 | parameter. |
| 3413 | .Pp |
| 3414 | .It Xo |
| 3415 | .Ic export |
| 3416 | .Op Fl p |
| 3417 | .Op Ar parameter Ns Op = Ns Ar value |
| 3418 | .Xc |
| 3419 | Sets the export attribute of the named parameters. |
| 3420 | Exported parameters are passed in the environment to executed commands. |
| 3421 | If values are specified, the named parameters are also assigned. |
| 3422 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3423 | If no parameters are specified, all parameters with the export attribute |
| 3424 | set are printed one per line; either their names, or, if a |
| 3425 | .Ql \- |
| 3426 | with no option letter is specified, name=value pairs, or, with |
| 3427 | .Fl p , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3428 | .Ic export |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3429 | commands suitable for re-entry. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3430 | .Pp |
| 3431 | .It Ic false |
| 3432 | A command that exits with a non-zero status. |
| 3433 | .Pp |
| 3434 | .It Xo |
| 3435 | .Ic fc |
| 3436 | .Oo Fl e Ar editor \*(Ba |
| 3437 | .Fl l Op Fl n Oc |
| 3438 | .Op Fl r |
| 3439 | .Op Ar first Op Ar last |
| 3440 | .Xc |
| 3441 | .Ar first |
| 3442 | and |
| 3443 | .Ar last |
| 3444 | select commands from the history. |
| 3445 | Commands can be selected by history number |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 3446 | (negative numbers go backwards from the current, most recent, line) |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3447 | or a string specifying the most recent command starting with that string. |
| 3448 | The |
| 3449 | .Fl l |
| 3450 | option lists the command on standard output, and |
| 3451 | .Fl n |
| 3452 | inhibits the default command numbers. |
| 3453 | The |
| 3454 | .Fl r |
| 3455 | option reverses the order of the list. |
| 3456 | Without |
| 3457 | .Fl l , |
| 3458 | the selected commands are edited by the editor specified with the |
| 3459 | .Fl e |
| 3460 | option, or if no |
| 3461 | .Fl e |
| 3462 | is specified, the editor specified by the |
| 3463 | .Ev FCEDIT |
| 3464 | parameter (if this parameter is not set, |
| 3465 | .Pa /bin/ed |
| 3466 | is used), and then executed by the shell. |
| 3467 | .Pp |
| 3468 | .It Xo |
| 3469 | .Ic fc |
| 3470 | .Cm \-e \- \*(Ba Fl s |
| 3471 | .Op Fl g |
| 3472 | .Op Ar old Ns = Ns Ar new |
| 3473 | .Op Ar prefix |
| 3474 | .Xc |
| 3475 | Re-execute the selected command (the previous command by default) after |
| 3476 | performing the optional substitution of |
| 3477 | .Ar old |
| 3478 | with |
| 3479 | .Ar new . |
| 3480 | If |
| 3481 | .Fl g |
| 3482 | is specified, all occurrences of |
| 3483 | .Ar old |
| 3484 | are replaced with |
| 3485 | .Ar new . |
| 3486 | The meaning of |
| 3487 | .Cm \-e \- |
| 3488 | and |
| 3489 | .Fl s |
| 3490 | is identical: re-execute the selected command without invoking an editor. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3491 | This command is usually accessed with the predefined: |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3492 | .Ic alias r=\*(aqfc \-e \-\*(aq |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3493 | .Pp |
| 3494 | .It Ic fg Op Ar job ... |
| 3495 | Resume the specified job(s) in the foreground. |
| 3496 | If no jobs are specified, |
| 3497 | .Ic %+ |
| 3498 | is assumed. |
| 3499 | See |
| 3500 | .Sx Job control |
| 3501 | below for more information. |
| 3502 | .Pp |
| 3503 | .It Xo |
| 3504 | .Ic getopts |
| 3505 | .Ar optstring name |
| 3506 | .Op Ar arg ... |
| 3507 | .Xc |
| 3508 | Used by shell procedures to parse the specified arguments (or positional |
| 3509 | parameters, if no arguments are given) and to check for legal options. |
| 3510 | .Ar optstring |
| 3511 | contains the option letters that |
| 3512 | .Ic getopts |
| 3513 | is to recognise. |
| 3514 | If a letter is followed by a colon, the option is expected to |
| 3515 | have an argument. |
| 3516 | Options that do not take arguments may be grouped in a single argument. |
| 3517 | If an option takes an argument and the option character is not the |
| 3518 | last character of the argument it is found in, the remainder of the argument is |
| 3519 | taken to be the option's argument; otherwise, the next argument is the option's |
| 3520 | argument. |
| 3521 | .Pp |
| 3522 | Each time |
| 3523 | .Ic getopts |
| 3524 | is invoked, it places the next option in the shell parameter |
| 3525 | .Ar name |
| 3526 | and the index of the argument to be processed by the next call to |
| 3527 | .Ic getopts |
| 3528 | in the shell parameter |
| 3529 | .Ev OPTIND . |
| 3530 | If the option was introduced with a |
| 3531 | .Ql + , |
| 3532 | the option placed in |
| 3533 | .Ar name |
| 3534 | is prefixed with a |
| 3535 | .Ql + . |
| 3536 | When an option requires an argument, |
| 3537 | .Ic getopts |
| 3538 | places it in the shell parameter |
| 3539 | .Ev OPTARG . |
| 3540 | .Pp |
| 3541 | When an illegal option or a missing option argument is encountered, a question |
| 3542 | mark or a colon is placed in |
| 3543 | .Ar name |
| 3544 | (indicating an illegal option or missing argument, respectively) and |
| 3545 | .Ev OPTARG |
| 3546 | is set to the option character that caused the problem. |
| 3547 | Furthermore, if |
| 3548 | .Ar optstring |
| 3549 | does not begin with a colon, a question mark is placed in |
| 3550 | .Ar name , |
| 3551 | .Ev OPTARG |
| 3552 | is unset, and an error message is printed to standard error. |
| 3553 | .Pp |
| 3554 | When the end of the options is encountered, |
| 3555 | .Ic getopts |
| 3556 | exits with a non-zero exit status. |
| 3557 | Options end at the first (non-option |
| 3558 | argument) argument that does not start with a |
| 3559 | .Ql \- , |
| 3560 | or when a |
| 3561 | .Ql \-\- |
| 3562 | argument is encountered. |
| 3563 | .Pp |
| 3564 | Option parsing can be reset by setting |
| 3565 | .Ev OPTIND |
| 3566 | to 1 (this is done automatically whenever the shell or a shell procedure is |
| 3567 | invoked). |
| 3568 | .Pp |
| 3569 | Warning: Changing the value of the shell parameter |
| 3570 | .Ev OPTIND |
| 3571 | to a value other than 1, or parsing different sets of arguments without |
| 3572 | resetting |
| 3573 | .Ev OPTIND , |
| 3574 | may lead to unexpected results. |
| 3575 | .Pp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 3576 | .It global Ar ... |
| 3577 | See |
| 3578 | .Ic typeset . |
| 3579 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3580 | .It Xo |
| 3581 | .Ic hash |
| 3582 | .Op Fl r |
| 3583 | .Op Ar name ... |
| 3584 | .Xc |
| 3585 | Without arguments, any hashed executable command pathnames are listed. |
| 3586 | The |
| 3587 | .Fl r |
| 3588 | option causes all hashed commands to be removed from the hash table. |
| 3589 | Each |
| 3590 | .Ar name |
| 3591 | is searched as if it were a command name and added to the hash table if it is |
| 3592 | an executable command. |
| 3593 | .Pp |
| 3594 | .It Xo |
| 3595 | .Ic jobs |
| 3596 | .Op Fl lnp |
| 3597 | .Op Ar job ... |
| 3598 | .Xc |
| 3599 | Display information about the specified job(s); if no jobs are specified, all |
| 3600 | jobs are displayed. |
| 3601 | The |
| 3602 | .Fl n |
| 3603 | option causes information to be displayed only for jobs that have changed |
| 3604 | state since the last notification. |
| 3605 | If the |
| 3606 | .Fl l |
| 3607 | option is used, the process ID of each process in a job is also listed. |
| 3608 | The |
| 3609 | .Fl p |
| 3610 | option causes only the process group of each job to be printed. |
| 3611 | See |
| 3612 | .Sx Job control |
| 3613 | below for the format of |
| 3614 | .Ar job |
| 3615 | and the displayed job. |
| 3616 | .Pp |
| 3617 | .It Xo |
| 3618 | .Ic kill |
| 3619 | .Oo Fl s Ar signame \*(Ba |
| 3620 | .No \- Ns Ar signum \*(Ba |
| 3621 | .No \- Ns Ar signame Oc |
| 3622 | .No { Ar job \*(Ba pid \*(Ba pgrp No } |
| 3623 | .Ar ... |
| 3624 | .Xc |
| 3625 | Send the specified signal to the specified jobs, process IDs, or process |
| 3626 | groups. |
| 3627 | If no signal is specified, the |
| 3628 | .Dv TERM |
| 3629 | signal is sent. |
| 3630 | If a job is specified, the signal is sent to the job's process group. |
| 3631 | See |
| 3632 | .Sx Job control |
| 3633 | below for the format of |
| 3634 | .Ar job . |
| 3635 | .Pp |
| 3636 | .It Xo |
| 3637 | .Ic kill |
| 3638 | .Fl l |
| 3639 | .Op Ar exit-status ... |
| 3640 | .Xc |
| 3641 | Print the signal name corresponding to |
| 3642 | .Ar exit-status . |
| 3643 | If no arguments are specified, a list of all the signals, their numbers, and |
| 3644 | a short description of them are printed. |
| 3645 | .Pp |
| 3646 | .It Ic let Op Ar expression ... |
| 3647 | Each expression is evaluated (see |
| 3648 | .Sx Arithmetic expressions |
| 3649 | above). |
| 3650 | If all expressions are successfully evaluated, the exit status is 0 (1) |
| 3651 | if the last expression evaluated to non-zero (zero). |
| 3652 | If an error occurs during |
| 3653 | the parsing or evaluation of an expression, the exit status is greater than 1. |
| 3654 | Since expressions may need to be quoted, |
| 3655 | .No \&(( Ar expr No )) |
| 3656 | is syntactic sugar for |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 3657 | .No "{ let '" Ns Ar expr Ns "'; }" . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3658 | .Pp |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 3659 | .It Ic let] |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 3660 | Internally used alias for |
| 3661 | .Ic let . |
| 3662 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3663 | .It Xo |
| 3664 | .Ic mknod |
| 3665 | .Op Fl m Ar mode |
| 3666 | .Ar name |
| 3667 | .Cm b\*(Bac |
| 3668 | .Ar major minor |
| 3669 | .Xc |
| 3670 | .It Xo |
| 3671 | .Ic mknod |
| 3672 | .Op Fl m Ar mode |
| 3673 | .Ar name |
| 3674 | .Cm p |
| 3675 | .Xc |
| 3676 | Create a device special file. |
| 3677 | The file type may be |
| 3678 | .Cm b |
| 3679 | (block type device), |
| 3680 | .Cm c |
| 3681 | (character type device), |
| 3682 | or |
| 3683 | .Cm p |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3684 | .Pq named pipe , Tn FIFO . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3685 | The file created may be modified according to its |
| 3686 | .Ar mode |
| 3687 | (via the |
| 3688 | .Fl m |
| 3689 | option), |
| 3690 | .Ar major |
| 3691 | (major device number), |
| 3692 | and |
| 3693 | .Ar minor |
| 3694 | (minor device number). |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3695 | This is not normally part of |
| 3696 | .Nm mksh ; |
| 3697 | however, distributors may have added this as builtin as a speed hack. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3698 | .Pp |
| 3699 | .It Xo |
| 3700 | .Ic print |
| 3701 | .Oo Fl nprsu Ns Oo Ar n Oc \*(Ba |
| 3702 | .Fl R Op Fl en Oc |
| 3703 | .Op Ar argument ... |
| 3704 | .Xc |
| 3705 | .Ic print |
| 3706 | prints its arguments on the standard output, separated by spaces and |
| 3707 | terminated with a newline. |
| 3708 | The |
| 3709 | .Fl n |
| 3710 | option suppresses the newline. |
| 3711 | By default, certain C escapes are translated. |
| 3712 | These include these mentioned in |
| 3713 | .Sx Backslash expansion |
| 3714 | above, as well as |
| 3715 | .Ql \ec , |
| 3716 | which is equivalent to using the |
| 3717 | .Fl n |
| 3718 | option. |
| 3719 | Backslash expansion may be inhibited with the |
| 3720 | .Fl r |
| 3721 | option. |
| 3722 | The |
| 3723 | .Fl s |
| 3724 | option prints to the history file instead of standard output; the |
| 3725 | .Fl u |
| 3726 | option prints to file descriptor |
| 3727 | .Ar n |
| 3728 | .Po |
| 3729 | .Ar n |
| 3730 | defaults to 1 if omitted |
| 3731 | .Pc ; |
| 3732 | and the |
| 3733 | .Fl p |
| 3734 | option prints to the co-process (see |
| 3735 | .Sx Co-processes |
| 3736 | above). |
| 3737 | .Pp |
| 3738 | The |
| 3739 | .Fl R |
| 3740 | option is used to emulate, to some degree, the |
| 3741 | .Bx |
| 3742 | .Xr echo 1 |
| 3743 | command which does not process |
| 3744 | .Ql \e |
| 3745 | sequences unless the |
| 3746 | .Fl e |
| 3747 | option is given. |
| 3748 | As above, the |
| 3749 | .Fl n |
| 3750 | option suppresses the trailing newline. |
| 3751 | .Pp |
| 3752 | .It Ic printf Ar format Op Ar arguments ... |
| 3753 | Formatted output. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3754 | Approximately the same as the |
| 3755 | .Xr printf 1 , |
| 3756 | utility, except it uses the same |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3757 | .Sx Backslash expansion |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3758 | and I/O code and does not handle floating point as the rest of |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3759 | .Nm mksh . |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3760 | An external utility is preferred over the builtin. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3761 | This is not normally part of |
| 3762 | .Nm mksh ; |
| 3763 | however, distributors may have added this as builtin as a speed hack. |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3764 | Do not use in new code. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3765 | .Pp |
| 3766 | .It Ic pwd Op Fl LP |
| 3767 | Print the present working directory. |
| 3768 | If the |
| 3769 | .Fl L |
| 3770 | option is used or if the |
| 3771 | .Ic physical |
| 3772 | option isn't set (see the |
| 3773 | .Ic set |
| 3774 | command below), the logical path is printed (i.e. the path used to |
| 3775 | .Ic cd |
| 3776 | to the current directory). |
| 3777 | If the |
| 3778 | .Fl P |
| 3779 | option (physical path) is used or if the |
| 3780 | .Ic physical |
| 3781 | option is set, the path determined from the filesystem (by following |
| 3782 | .Sq .. |
| 3783 | directories to the root directory) is printed. |
| 3784 | .Pp |
| 3785 | .It Xo |
| 3786 | .Ic read |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3787 | .Op Fl A \*(Ba Fl a |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3788 | .Op Fl d Ar x |
| 3789 | .Oo Fl N Ar z \*(Ba |
| 3790 | .Fl n Ar z Oc |
| 3791 | .Oo Fl p \*(Ba |
| 3792 | .Fl u Ns Op Ar n |
| 3793 | .Oc Op Fl t Ar n |
| 3794 | .Op Fl rs |
| 3795 | .Op Ar p ... |
| 3796 | .Xc |
| 3797 | Reads a line of input, separates the input into fields using the |
| 3798 | .Ev IFS |
| 3799 | parameter (see |
| 3800 | .Sx Substitution |
| 3801 | above), and assigns each field to the specified parameters |
| 3802 | .Ar p . |
| 3803 | If no parameters are specified, the |
| 3804 | .Ev REPLY |
| 3805 | parameter is used to store the result. |
| 3806 | With the |
| 3807 | .Fl A |
| 3808 | and |
| 3809 | .Fl a |
| 3810 | options, only no or one parameter is accepted. |
| 3811 | If there are more parameters than fields, the extra parameters are set to |
| 3812 | the empty string or 0; if there are more fields than parameters, the last |
| 3813 | parameter is assigned the remaining fields (including the word separators). |
| 3814 | .Pp |
| 3815 | The options are as follows: |
| 3816 | .Bl -tag -width XuXnX |
| 3817 | .It Fl A |
| 3818 | Store the result into the parameter |
| 3819 | .Ar p |
| 3820 | (or |
| 3821 | .Ev REPLY ) |
| 3822 | as array of words. |
| 3823 | .It Fl a |
| 3824 | Store the result without word splitting into the parameter |
| 3825 | .Ar p |
| 3826 | (or |
| 3827 | .Ev REPLY ) |
| 3828 | as array of characters (wide characters if the |
| 3829 | .Ic utf8\-mode |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 3830 | option is enacted, octets otherwise); the codepoints are |
| 3831 | encoded as decimal numbers by default. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3832 | .It Fl d Ar x |
| 3833 | Use the first byte of |
| 3834 | .Ar x , |
| 3835 | .Dv NUL |
| 3836 | if empty, instead of the ASCII newline character as input line delimiter. |
| 3837 | .It Fl N Ar z |
| 3838 | Instead of reading till end-of-line, read exactly |
| 3839 | .Ar z |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3840 | bytes. |
| 3841 | If EOF or a timeout occurs, a partial read is returned with exit status 1. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3842 | .It Fl n Ar z |
| 3843 | Instead of reading till end-of-line, read up to |
| 3844 | .Ar z |
| 3845 | bytes but return as soon as any bytes are read, e.g.\& from a |
| 3846 | slow terminal device, or if EOF or a timeout occurs. |
| 3847 | .It Fl p |
| 3848 | Read from the currently active co-process, see |
| 3849 | .Sx Co-processes |
| 3850 | above for details on this. |
| 3851 | .It Fl u Ns Op Ar n |
| 3852 | Read from the file descriptor |
| 3853 | .Ar n |
| 3854 | (defaults to 0, i.e.\& standard input). |
| 3855 | The argument must immediately follow the option character. |
| 3856 | .It Fl t Ar n |
| 3857 | Interrupt reading after |
| 3858 | .Ar n |
| 3859 | seconds (specified as positive decimal value with an optional fractional part). |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3860 | The exit status of |
| 3861 | .Nm read |
| 3862 | is 1 if the timeout occurred, but partial reads may still be returned. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3863 | .It Fl r |
| 3864 | Normally, the ASCII backslash character escapes the special |
| 3865 | meaning of the following character and is stripped from the input; |
| 3866 | .Ic read |
| 3867 | does not stop when encountering a backslash-newline sequence and |
| 3868 | does not store that newline in the result. |
| 3869 | This option enables raw mode, in which backslashes are not processed. |
| 3870 | .It Fl s |
| 3871 | The input line is saved to the history. |
| 3872 | .El |
| 3873 | .Pp |
| 3874 | If the input is a terminal, both the |
| 3875 | .Fl N |
| 3876 | and |
| 3877 | .Fl n |
| 3878 | options set it into raw mode; |
| 3879 | they read an entire file if \-1 is passed as |
| 3880 | .Ar z |
| 3881 | argument. |
| 3882 | .Pp |
| 3883 | The first parameter may have a question mark and a string appended to it, in |
| 3884 | which case the string is used as a prompt (printed to standard error before |
| 3885 | any input is read) if the input is a |
| 3886 | .Xr tty 4 |
| 3887 | (e.g.\& |
| 3888 | .Ic read nfoo?\*(aqnumber of foos: \*(aq ) . |
| 3889 | .Pp |
| 3890 | If no input is read or a timeout occurred, |
| 3891 | .Ic read |
| 3892 | exits with a non-zero status. |
| 3893 | .Pp |
| 3894 | Another handy set of tricks: |
| 3895 | If |
| 3896 | .Ic read |
| 3897 | is run in a loop such as |
| 3898 | .Ic while read foo; do ...; done |
| 3899 | then leading whitespace will be removed (IFS) and backslashes processed. |
| 3900 | You might want to use |
| 3901 | .Ic while IFS= read \-r foo; do ...; done |
| 3902 | for pristine I/O. |
| 3903 | Similarily, when using the |
| 3904 | .Fl a |
| 3905 | option, use of the |
| 3906 | .Fl r |
| 3907 | option might be prudent; the same applies for: |
| 3908 | .Bd -literal -offset indent |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 3909 | find . \-type f \-print0 \*(Ba& \e |
| 3910 | while IFS= read \-d \*(aq\*(aq \-pr filename; do |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 3911 | print \-r \-\- "found \*(Lt${filename#./}\*(Gt" |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 3912 | done |
| 3913 | .Ed |
| 3914 | .Pp |
| 3915 | The inner loop will be executed in a subshell and variable changes |
| 3916 | cannot be propagated if executed in a pipeline: |
| 3917 | .Bd -literal -offset indent |
| 3918 | bar \*(Ba baz \*(Ba while read foo; do ...; done |
| 3919 | .Ed |
| 3920 | .Pp |
| 3921 | Use co-processes instead: |
| 3922 | .Bd -literal -offset indent |
| 3923 | bar \*(Ba baz \*(Ba& |
| 3924 | while read \-p foo; do ...; done |
| 3925 | exec 3\*(Gt&p; exec 3\*(Gt&\- |
| 3926 | .Ed |
| 3927 | .Pp |
| 3928 | .It Xo |
| 3929 | .Ic readonly |
| 3930 | .Op Fl p |
| 3931 | .Oo Ar parameter |
| 3932 | .Op Ns = Ns Ar value |
| 3933 | .Ar ... Oc |
| 3934 | .Xc |
| 3935 | Sets the read-only attribute of the named parameters. |
| 3936 | If values are given, |
| 3937 | parameters are set to them before setting the attribute. |
| 3938 | Once a parameter is |
| 3939 | made read-only, it cannot be unset and its value cannot be changed. |
| 3940 | .Pp |
| 3941 | If no parameters are specified, the names of all parameters with the read-only |
| 3942 | attribute are printed one per line, unless the |
| 3943 | .Fl p |
| 3944 | option is used, in which case |
| 3945 | .Ic readonly |
| 3946 | commands defining all read-only parameters, including their values, are |
| 3947 | printed. |
| 3948 | .Pp |
| 3949 | .It Xo |
| 3950 | .Ic realpath |
| 3951 | .Op Fl \- |
| 3952 | .Ar name |
| 3953 | .Xc |
| 3954 | Prints the resolved absolute pathname corresponding to |
| 3955 | .Ar name . |
| 3956 | If |
| 3957 | .Ar name |
| 3958 | ends with a slash |
| 3959 | .Pq Sq / , |
| 3960 | it's also checked for existence and whether it is a directory; otherwise, |
| 3961 | .Ic realpath |
| 3962 | returns 0 if the pathname either exists or can be created immediately, |
| 3963 | i.e. all but the last component exist and are directories. |
| 3964 | .Pp |
| 3965 | .It Xo |
| 3966 | .Ic rename |
| 3967 | .Op Fl \- |
| 3968 | .Ar from to |
| 3969 | .Xc |
| 3970 | Renames the file |
| 3971 | .Ar from |
| 3972 | to |
| 3973 | .Ar to . |
| 3974 | Both must be complete pathnames and on the same device. |
| 3975 | This builtin is intended for emergency situations where |
| 3976 | .Pa /bin/mv |
| 3977 | becomes unusable, and directly calls |
| 3978 | .Xr rename 2 . |
| 3979 | .Pp |
| 3980 | .It Ic return Op Ar status |
| 3981 | Returns from a function or |
| 3982 | .Ic .\& |
| 3983 | script, with exit status |
| 3984 | .Ar status . |
| 3985 | If no |
| 3986 | .Ar status |
| 3987 | is given, the exit status of the last executed command is used. |
| 3988 | If used outside of a function or |
| 3989 | .Ic .\& |
| 3990 | script, it has the same effect as |
| 3991 | .Ic exit . |
| 3992 | Note that |
| 3993 | .Nm |
| 3994 | treats both profile and |
| 3995 | .Ev ENV |
| 3996 | files as |
| 3997 | .Ic .\& |
| 3998 | scripts, while the original Korn shell only treats profiles as |
| 3999 | .Ic .\& |
| 4000 | scripts. |
| 4001 | .Pp |
| 4002 | .It Xo |
| 4003 | .Ic set Op Ic +\-abCefhiklmnprsUuvXx |
| 4004 | .Op Ic +\-o Ar option |
| 4005 | .Op Ic +\-A Ar name |
| 4006 | .Op Fl \- |
| 4007 | .Op Ar arg ... |
| 4008 | .Xc |
| 4009 | The |
| 4010 | .Ic set |
| 4011 | command can be used to set |
| 4012 | .Pq Ic \- |
| 4013 | or clear |
| 4014 | .Pq Ic + |
| 4015 | shell options, set the positional parameters, or set an array parameter. |
| 4016 | Options can be changed using the |
| 4017 | .Cm +\-o Ar option |
| 4018 | syntax, where |
| 4019 | .Ar option |
| 4020 | is the long name of an option, or using the |
| 4021 | .Cm +\- Ns Ar letter |
| 4022 | syntax, where |
| 4023 | .Ar letter |
| 4024 | is the option's single letter name (not all options have a single letter name). |
| 4025 | The following table lists both option letters (if they exist) and long names |
| 4026 | along with a description of what the option does: |
| 4027 | .Bl -tag -width 3n |
| 4028 | .It Fl A Ar name |
| 4029 | Sets the elements of the array parameter |
| 4030 | .Ar name |
| 4031 | to |
| 4032 | .Ar arg ... |
| 4033 | If |
| 4034 | .Fl A |
| 4035 | is used, the array is reset (i.e. emptied) first; if |
| 4036 | .Ic +A |
| 4037 | is used, the first N elements are set (where N is the number of arguments); |
| 4038 | the rest are left untouched. |
| 4039 | .Pp |
| 4040 | An alternative syntax for the command |
| 4041 | .Ic set \-A foo \-\- a b c |
| 4042 | which is compatible to |
| 4043 | .Tn GNU |
| 4044 | .Nm bash |
| 4045 | and also supported by |
| 4046 | .At |
| 4047 | .Nm ksh93 |
| 4048 | is: |
| 4049 | .Ic foo=(a b c); foo+=(d e) |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4050 | .It Fl a \*(Ba Fl o Ic allexport |
| 4051 | All new parameters are created with the export attribute. |
| 4052 | .It Fl b \*(Ba Fl o Ic notify |
| 4053 | Print job notification messages asynchronously, instead of just before the |
| 4054 | prompt. |
| 4055 | Only used if job control is enabled |
| 4056 | .Pq Fl m . |
| 4057 | .It Fl C \*(Ba Fl o Ic noclobber |
| 4058 | Prevent \*(Gt redirection from overwriting existing files. |
| 4059 | Instead, \*(Gt\*(Ba must be used to force an overwrite. |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 4060 | Note that this is not safe to use for creation of temporary files or |
| 4061 | lockfiles due to a TOCTOU in a check allowing one to redirect output to |
| 4062 | .Pa /dev/null |
| 4063 | or other device files even in |
| 4064 | .Ic noclobber |
| 4065 | mode. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4066 | .It Fl e \*(Ba Fl o Ic errexit |
| 4067 | Exit (after executing the |
| 4068 | .Dv ERR |
| 4069 | trap) as soon as an error occurs or a command fails (i.e. exits with a |
| 4070 | non-zero status). |
| 4071 | This does not apply to commands whose exit status is |
| 4072 | explicitly tested by a shell construct such as |
| 4073 | .Ic if , |
| 4074 | .Ic until , |
| 4075 | .Ic while , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4076 | or |
| 4077 | .Ic !\& |
| 4078 | statements. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 4079 | For |
| 4080 | .Ic && |
| 4081 | or |
| 4082 | .Ic \*(Ba\*(Ba , |
| 4083 | only the status of the last command is tested. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4084 | .It Fl f \*(Ba Fl o Ic noglob |
| 4085 | Do not expand file name patterns. |
| 4086 | .It Fl h \*(Ba Fl o Ic trackall |
| 4087 | Create tracked aliases for all executed commands (see |
| 4088 | .Sx Aliases |
| 4089 | above). |
| 4090 | Enabled by default for non-interactive shells. |
| 4091 | .It Fl i \*(Ba Fl o Ic interactive |
| 4092 | The shell is an interactive shell. |
| 4093 | This option can only be used when the shell is invoked. |
| 4094 | See above for a description of what this means. |
| 4095 | .It Fl k \*(Ba Fl o Ic keyword |
| 4096 | Parameter assignments are recognised anywhere in a command. |
| 4097 | .It Fl l \*(Ba Fl o Ic login |
| 4098 | The shell is a login shell. |
| 4099 | This option can only be used when the shell is invoked. |
| 4100 | See above for a description of what this means. |
| 4101 | .It Fl m \*(Ba Fl o Ic monitor |
| 4102 | Enable job control (default for interactive shells). |
| 4103 | .It Fl n \*(Ba Fl o Ic noexec |
| 4104 | Do not execute any commands. |
| 4105 | Useful for checking the syntax of scripts |
| 4106 | (ignored if interactive). |
| 4107 | .It Fl p \*(Ba Fl o Ic privileged |
| 4108 | The shell is a privileged shell. |
| 4109 | It is set automatically if, when the shell starts, |
| 4110 | the real UID or GID does not match |
| 4111 | the effective UID (EUID) or GID (EGID), respectively. |
| 4112 | See above for a description of what this means. |
| 4113 | .It Fl r \*(Ba Fl o Ic restricted |
| 4114 | The shell is a restricted shell. |
| 4115 | This option can only be used when the shell is invoked. |
| 4116 | See above for a description of what this means. |
| 4117 | .It Fl s \*(Ba Fl o Ic stdin |
| 4118 | If used when the shell is invoked, commands are read from standard input. |
| 4119 | Set automatically if the shell is invoked with no arguments. |
| 4120 | .Pp |
| 4121 | When |
| 4122 | .Fl s |
| 4123 | is used with the |
| 4124 | .Ic set |
| 4125 | command it causes the specified arguments to be sorted before assigning them to |
| 4126 | the positional parameters (or to array |
| 4127 | .Ar name , |
| 4128 | if |
| 4129 | .Fl A |
| 4130 | is used). |
| 4131 | .It Fl U \*(Ba Fl o Ic utf8\-mode |
| 4132 | Enable UTF-8 support in the |
| 4133 | .Sx Emacs editing mode |
| 4134 | and internal string handling functions. |
| 4135 | This flag is disabled by default, but can be enabled by setting it on the |
| 4136 | shell command line; is enabled automatically for interactive shells if |
| 4137 | requested at compile time, your system supports |
| 4138 | .Fn setlocale LC_CTYPE \&"" |
| 4139 | and optionally |
| 4140 | .Fn nl_langinfo CODESET , |
| 4141 | or the |
| 4142 | .Ev LC_ALL , |
| 4143 | .Ev LC_CTYPE , |
| 4144 | or |
| 4145 | .Ev LANG |
| 4146 | environment variables, |
| 4147 | and at least one of these returns something that matches |
| 4148 | .Dq UTF\-8 |
| 4149 | or |
| 4150 | .Dq utf8 |
| 4151 | case-insensitively; for direct builtin calls depending on the |
| 4152 | aforementioned environment variables; or for stdin or scripts, |
| 4153 | if the input begins with a UTF-8 Byte Order Mark. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4154 | .Pp |
| 4155 | In near future, locale tracking will be implemented, which means that |
| 4156 | .Ic set Fl +U |
| 4157 | is changed whenever one of the |
| 4158 | .Tn POSIX |
| 4159 | locale-related environment variables changes. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4160 | .It Fl u \*(Ba Fl o Ic nounset |
| 4161 | Referencing of an unset parameter, other than |
| 4162 | .Dq $@ |
| 4163 | or |
| 4164 | .Dq $* , |
| 4165 | is treated as an error, unless one of the |
| 4166 | .Ql \- , |
| 4167 | .Ql + , |
| 4168 | or |
| 4169 | .Ql = |
| 4170 | modifiers is used. |
| 4171 | .It Fl v \*(Ba Fl o Ic verbose |
| 4172 | Write shell input to standard error as it is read. |
| 4173 | .It Fl X \*(Ba Fl o Ic markdirs |
| 4174 | Mark directories with a trailing |
| 4175 | .Ql / |
| 4176 | during file name generation. |
| 4177 | .It Fl x \*(Ba Fl o Ic xtrace |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 4178 | Print command trees when they are executed, preceded by |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4179 | the value of |
| 4180 | .Ev PS4 . |
| 4181 | .It Fl o Ic bgnice |
| 4182 | Background jobs are run with lower priority. |
| 4183 | .It Fl o Ic braceexpand |
| 4184 | Enable brace expansion (a.k.a. alternation). |
| 4185 | This is enabled by default. |
| 4186 | If disabled, tilde expansion after an equals sign is disabled as a side effect. |
| 4187 | .It Fl o Ic emacs |
| 4188 | Enable BRL emacs-like command-line editing (interactive shells only); see |
| 4189 | .Sx Emacs editing mode . |
| 4190 | .It Fl o Ic gmacs |
| 4191 | Enable gmacs-like command-line editing (interactive shells only). |
| 4192 | Currently identical to emacs editing except that transpose\-chars (\*(haT) acts |
| 4193 | slightly differently. |
| 4194 | .It Fl o Ic ignoreeof |
| 4195 | The shell will not (easily) exit when end-of-file is read; |
| 4196 | .Ic exit |
| 4197 | must be used. |
| 4198 | To avoid infinite loops, the shell will exit if |
| 4199 | .Dv EOF |
| 4200 | is read 13 times in a row. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 4201 | .It Fl o Ic inherit\-xtrace |
| 4202 | Do not reset |
| 4203 | .Fl o Ic xtrace |
| 4204 | upon entering functions. |
| 4205 | This is enabled by default. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4206 | .It Fl o Ic nohup |
| 4207 | Do not kill running jobs with a |
| 4208 | .Dv SIGHUP |
| 4209 | signal when a login shell exits. |
| 4210 | Currently set by default, but this may |
| 4211 | change in the future to be compatible with |
| 4212 | .At |
| 4213 | .Nm ksh , |
| 4214 | which |
| 4215 | doesn't have this option, but does send the |
| 4216 | .Dv SIGHUP |
| 4217 | signal. |
| 4218 | .It Fl o Ic nolog |
| 4219 | No effect. |
| 4220 | In the original Korn shell, this prevents function definitions from |
| 4221 | being stored in the history file. |
| 4222 | .It Fl o Ic physical |
| 4223 | Causes the |
| 4224 | .Ic cd |
| 4225 | and |
| 4226 | .Ic pwd |
| 4227 | commands to use |
| 4228 | .Dq physical |
| 4229 | (i.e. the filesystem's) |
| 4230 | .Sq .. |
| 4231 | directories instead of |
| 4232 | .Dq logical |
| 4233 | directories (i.e. the shell handles |
| 4234 | .Sq .. , |
| 4235 | which allows the user to be oblivious of symbolic links to directories). |
| 4236 | Clear by default. |
| 4237 | Note that setting this option does not affect the current value of the |
| 4238 | .Ev PWD |
| 4239 | parameter; only the |
| 4240 | .Ic cd |
| 4241 | command changes |
| 4242 | .Ev PWD . |
| 4243 | See the |
| 4244 | .Ic cd |
| 4245 | and |
| 4246 | .Ic pwd |
| 4247 | commands above for more details. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 4248 | .It Fl o Ic pipefail |
| 4249 | Make the exit status of a pipeline (before logically complementing) the |
| 4250 | rightmost non-zero errorlevel, or zero if all commands exited with zero. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4251 | .It Fl o Ic posix |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4252 | Behave closer to the standards |
| 4253 | (see |
| 4254 | .Sx POSIX mode |
| 4255 | for details). |
| 4256 | Automatically enabled if the basename of the shell invocation begins with |
| 4257 | .Dq sh |
| 4258 | and this autodetection feature is compiled in |
| 4259 | .Pq not in MirBSD . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4260 | As a side effect, setting this flag turns off |
| 4261 | .Ic braceexpand |
| 4262 | mode, which can be turned back on manually, and |
| 4263 | .Ic sh |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4264 | mode (unless both are enabled at the same time). |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4265 | .It Fl o Ic sh |
| 4266 | Enable |
| 4267 | .Pa /bin/sh |
| 4268 | .Pq kludge |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4269 | mode (see |
| 4270 | .Sx SH mode ) . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4271 | Automatically enabled if the basename of the shell invocation begins with |
| 4272 | .Dq sh |
| 4273 | and this autodetection feature is compiled in |
| 4274 | .Pq not in MirBSD . |
| 4275 | As a side effect, setting this flag turns off |
| 4276 | .Ic braceexpand |
| 4277 | mode, which can be turned back on manually, and |
| 4278 | .Ic posix |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4279 | mode (unless both are enabled at the same time). |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4280 | .It Fl o Ic vi |
| 4281 | Enable |
| 4282 | .Xr vi 1 Ns -like |
| 4283 | command-line editing (interactive shells only). |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 4284 | See |
| 4285 | .Sx Vi editing mode |
| 4286 | for documentation and limitations. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4287 | .It Fl o Ic vi\-esccomplete |
| 4288 | In vi command-line editing, do command and file name completion when escape |
| 4289 | (\*(ha[) is entered in command mode. |
| 4290 | .It Fl o Ic vi\-tabcomplete |
| 4291 | In vi command-line editing, do command and file name completion when tab (\*(haI) |
| 4292 | is entered in insert mode. |
| 4293 | This is the default. |
| 4294 | .It Fl o Ic viraw |
| 4295 | No effect. |
| 4296 | In the original Korn shell, unless |
| 4297 | .Ic viraw |
| 4298 | was set, the vi command-line mode would let the |
| 4299 | .Xr tty 4 |
| 4300 | driver do the work until ESC (\*(ha[) was entered. |
| 4301 | .Nm |
| 4302 | is always in viraw mode. |
| 4303 | .El |
| 4304 | .Pp |
| 4305 | These options can also be used upon invocation of the shell. |
| 4306 | The current set of |
| 4307 | options (with single letter names) can be found in the parameter |
| 4308 | .Sq $\- . |
| 4309 | .Ic set Fl o |
| 4310 | with no option name will list all the options and whether each is on or off; |
| 4311 | .Ic set +o |
| 4312 | will print the long names of all options that are currently on. |
| 4313 | .Pp |
| 4314 | Remaining arguments, if any, are positional parameters and are assigned, in |
| 4315 | order, to the positional parameters (i.e. $1, $2, etc.). |
| 4316 | If options end with |
| 4317 | .Ql \-\- |
| 4318 | and there are no remaining arguments, all positional parameters are cleared. |
| 4319 | If no options or arguments are given, the values of all names are printed. |
| 4320 | For unknown historical reasons, a lone |
| 4321 | .Ql \- |
| 4322 | option is treated specially \*(en it clears both the |
| 4323 | .Fl v |
| 4324 | and |
| 4325 | .Fl x |
| 4326 | options. |
| 4327 | .Pp |
| 4328 | .It Ic shift Op Ar number |
| 4329 | The positional parameters |
| 4330 | .Ar number Ns +1 , |
| 4331 | .Ar number Ns +2 , |
| 4332 | etc. are renamed to |
| 4333 | .Sq 1 , |
| 4334 | .Sq 2 , |
| 4335 | etc. |
| 4336 | .Ar number |
| 4337 | defaults to 1. |
| 4338 | .Pp |
| 4339 | .It Ic sleep Ar seconds |
| 4340 | Suspends execution for a minimum of the |
| 4341 | .Ar seconds |
| 4342 | specified as positive decimal value with an optional fractional part. |
| 4343 | Signal delivery may continue execution earlier. |
| 4344 | .Pp |
| 4345 | .It Ic source Ar file Op Ar arg ... |
| 4346 | Like |
| 4347 | .Ic \&. Po Do dot Dc Pc , |
| 4348 | except that the current working directory is appended to the |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4349 | search path (GNU |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4350 | .Nm bash |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 4351 | extension). |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4352 | .Pp |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 4353 | .It Ic suspend |
| 4354 | Stops the shell as if it had received the suspend character from |
| 4355 | the terminal. |
| 4356 | It is not possible to suspend a login shell unless the parent process |
| 4357 | is a member of the same terminal session but is a member of a different |
| 4358 | process group. |
| 4359 | As a general rule, if the shell was started by another shell or via |
| 4360 | .Xr su 1 , |
| 4361 | it can be suspended. |
| 4362 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4363 | .It Ic test Ar expression |
| 4364 | .It Ic \&[ Ar expression Ic \&] |
| 4365 | .Ic test |
| 4366 | evaluates the |
| 4367 | .Ar expression |
| 4368 | and returns zero status if true, 1 if false, or greater than 1 if there |
| 4369 | was an error. |
| 4370 | It is normally used as the condition command of |
| 4371 | .Ic if |
| 4372 | and |
| 4373 | .Ic while |
| 4374 | statements. |
| 4375 | Symbolic links are followed for all |
| 4376 | .Ar file |
| 4377 | expressions except |
| 4378 | .Fl h |
| 4379 | and |
| 4380 | .Fl L . |
| 4381 | .Pp |
| 4382 | The following basic expressions are available: |
| 4383 | .Bl -tag -width 17n |
| 4384 | .It Fl a Ar file |
| 4385 | .Ar file |
| 4386 | exists. |
| 4387 | .It Fl b Ar file |
| 4388 | .Ar file |
| 4389 | is a block special device. |
| 4390 | .It Fl c Ar file |
| 4391 | .Ar file |
| 4392 | is a character special device. |
| 4393 | .It Fl d Ar file |
| 4394 | .Ar file |
| 4395 | is a directory. |
| 4396 | .It Fl e Ar file |
| 4397 | .Ar file |
| 4398 | exists. |
| 4399 | .It Fl f Ar file |
| 4400 | .Ar file |
| 4401 | is a regular file. |
| 4402 | .It Fl G Ar file |
| 4403 | .Ar file Ns 's |
| 4404 | group is the shell's effective group ID. |
| 4405 | .It Fl g Ar file |
| 4406 | .Ar file Ns 's |
| 4407 | mode has the setgid bit set. |
| 4408 | .It Fl H Ar file |
| 4409 | .Ar file |
| 4410 | is a context dependent directory (only useful on HP-UX). |
| 4411 | .It Fl h Ar file |
| 4412 | .Ar file |
| 4413 | is a symbolic link. |
| 4414 | .It Fl k Ar file |
| 4415 | .Ar file Ns 's |
| 4416 | mode has the |
| 4417 | .Xr sticky 8 |
| 4418 | bit set. |
| 4419 | .It Fl L Ar file |
| 4420 | .Ar file |
| 4421 | is a symbolic link. |
| 4422 | .It Fl O Ar file |
| 4423 | .Ar file Ns 's |
| 4424 | owner is the shell's effective user ID. |
| 4425 | .It Fl o Ar option |
| 4426 | Shell |
| 4427 | .Ar option |
| 4428 | is set (see the |
| 4429 | .Ic set |
| 4430 | command above for a list of options). |
| 4431 | As a non-standard extension, if the option starts with a |
| 4432 | .Ql \&! , |
| 4433 | the test is negated; the test always fails if |
| 4434 | .Ar option |
| 4435 | doesn't exist (so [ \-o foo \-o \-o !foo ] returns true if and only if option |
| 4436 | .Ar foo |
| 4437 | exists). |
| 4438 | The same can be achieved with [ \-o ?foo ] like in |
| 4439 | .At |
| 4440 | .Nm ksh93 . |
| 4441 | .Ar option |
| 4442 | can also be the short flag led by either |
| 4443 | .Ql \- |
| 4444 | or |
| 4445 | .Ql + |
| 4446 | .Pq no logical negation , |
| 4447 | for example |
| 4448 | .Ql \-x |
| 4449 | or |
| 4450 | .Ql +x |
| 4451 | instead of |
| 4452 | .Ql xtrace . |
| 4453 | .It Fl p Ar file |
| 4454 | .Ar file |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4455 | is a named pipe |
| 4456 | .Pq Tn FIFO . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4457 | .It Fl r Ar file |
| 4458 | .Ar file |
| 4459 | exists and is readable. |
| 4460 | .It Fl S Ar file |
| 4461 | .Ar file |
| 4462 | is a |
| 4463 | .Xr unix 4 Ns -domain |
| 4464 | socket. |
| 4465 | .It Fl s Ar file |
| 4466 | .Ar file |
| 4467 | is not empty. |
| 4468 | .It Fl t Ar fd |
| 4469 | File descriptor |
| 4470 | .Ar fd |
| 4471 | is a |
| 4472 | .Xr tty 4 |
| 4473 | device. |
| 4474 | .It Fl u Ar file |
| 4475 | .Ar file Ns 's |
| 4476 | mode has the setuid bit set. |
| 4477 | .It Fl w Ar file |
| 4478 | .Ar file |
| 4479 | exists and is writable. |
| 4480 | .It Fl x Ar file |
| 4481 | .Ar file |
| 4482 | exists and is executable. |
| 4483 | .It Ar file1 Fl nt Ar file2 |
| 4484 | .Ar file1 |
| 4485 | is newer than |
| 4486 | .Ar file2 |
| 4487 | or |
| 4488 | .Ar file1 |
| 4489 | exists and |
| 4490 | .Ar file2 |
| 4491 | does not. |
| 4492 | .It Ar file1 Fl ot Ar file2 |
| 4493 | .Ar file1 |
| 4494 | is older than |
| 4495 | .Ar file2 |
| 4496 | or |
| 4497 | .Ar file2 |
| 4498 | exists and |
| 4499 | .Ar file1 |
| 4500 | does not. |
| 4501 | .It Ar file1 Fl ef Ar file2 |
| 4502 | .Ar file1 |
| 4503 | is the same file as |
| 4504 | .Ar file2 . |
| 4505 | .It Ar string |
| 4506 | .Ar string |
| 4507 | has non-zero length. |
| 4508 | .It Fl n Ar string |
| 4509 | .Ar string |
| 4510 | is not empty. |
| 4511 | .It Fl z Ar string |
| 4512 | .Ar string |
| 4513 | is empty. |
| 4514 | .It Ar string No = Ar string |
| 4515 | Strings are equal. |
| 4516 | .It Ar string No == Ar string |
| 4517 | Strings are equal. |
| 4518 | .It Ar string No \*(Gt Ar string |
| 4519 | First string operand is greater than second string operand. |
| 4520 | .It Ar string No \*(Lt Ar string |
| 4521 | First string operand is less than second string operand. |
| 4522 | .It Ar string No != Ar string |
| 4523 | Strings are not equal. |
| 4524 | .It Ar number Fl eq Ar number |
| 4525 | Numbers compare equal. |
| 4526 | .It Ar number Fl ne Ar number |
| 4527 | Numbers compare not equal. |
| 4528 | .It Ar number Fl ge Ar number |
| 4529 | Numbers compare greater than or equal. |
| 4530 | .It Ar number Fl gt Ar number |
| 4531 | Numbers compare greater than. |
| 4532 | .It Ar number Fl le Ar number |
| 4533 | Numbers compare less than or equal. |
| 4534 | .It Ar number Fl \< Ar number |
| 4535 | Numbers compare less than. |
| 4536 | .El |
| 4537 | .Pp |
| 4538 | The above basic expressions, in which unary operators have precedence over |
| 4539 | binary operators, may be combined with the following operators (listed in |
| 4540 | increasing order of precedence): |
| 4541 | .Bd -literal -offset indent |
| 4542 | expr \-o expr Logical OR. |
| 4543 | expr \-a expr Logical AND. |
| 4544 | ! expr Logical NOT. |
| 4545 | ( expr ) Grouping. |
| 4546 | .Ed |
| 4547 | .Pp |
| 4548 | Note that a number actually may be an arithmetic expression, such as |
| 4549 | a mathematical term or the name of an integer variable: |
| 4550 | .Bd -literal -offset indent |
| 4551 | x=1; [ "x" \-eq 1 ] evaluates to true |
| 4552 | .Ed |
| 4553 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4554 | Note that some special rules are applied (courtesy of |
| 4555 | .Px |
| 4556 | ) if the number of arguments to |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4557 | .Ic test |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4558 | or inside the brackets |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4559 | .Ic \&[ ... \&] |
| 4560 | is less than five: if leading |
| 4561 | .Ql \&! |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4562 | arguments can be stripped such that only one to three arguments remain, |
| 4563 | then the lowered comparison is executed; (thanks to XSI) parentheses |
| 4564 | .Ic \e( ... \e) |
| 4565 | lower four- and three-argument forms to two- and one-argument forms, |
| 4566 | respectively; three-argument forms ultimately prefer binary operations, |
| 4567 | followed by negation and parenthesis lowering; two- and four-argument forms |
| 4568 | prefer negation followed by parenthesis; the one-argument form always implies |
| 4569 | .Fl n . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4570 | .Pp |
| 4571 | .Sy Note : |
| 4572 | A common mistake is to use |
| 4573 | .Dq if \&[ $foo = bar \&] |
| 4574 | which fails if parameter |
| 4575 | .Dq foo |
| 4576 | is |
| 4577 | .Dv NULL |
| 4578 | or unset, if it has embedded spaces (i.e.\& |
| 4579 | .Ev IFS |
| 4580 | octets), or if it is a unary operator like |
| 4581 | .Sq \&! |
| 4582 | or |
| 4583 | .Sq Fl n . |
| 4584 | Use tests like |
| 4585 | .Dq if \&[ x\&"$foo\&" = x"bar" \&] |
| 4586 | instead, or the double-bracket operator |
| 4587 | .Dq if \&[[ $foo = bar \&]] |
| 4588 | or, to avoid pattern matching (see |
| 4589 | .Ic \&[[ |
| 4590 | above): |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4591 | .Dq if \&[[ $foo = \&"$bar" \&]] |
| 4592 | .Pp |
| 4593 | The |
| 4594 | .Ic \&[[ ... ]] |
| 4595 | construct is not only more secure to use but also often faster. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4596 | .Pp |
| 4597 | .It Xo |
| 4598 | .Ic time |
| 4599 | .Op Fl p |
| 4600 | .Op Ar pipeline |
| 4601 | .Xc |
| 4602 | If a |
| 4603 | .Ar pipeline |
| 4604 | is given, the times used to execute the pipeline are reported. |
| 4605 | If no pipeline |
| 4606 | is given, then the user and system time used by the shell itself, and all the |
| 4607 | commands it has run since it was started, are reported. |
| 4608 | The times reported are the real time (elapsed time from start to finish), |
| 4609 | the user CPU time (time spent running in user mode), and the system CPU time |
| 4610 | (time spent running in kernel mode). |
| 4611 | Times are reported to standard error; the format of the output is: |
| 4612 | .Pp |
| 4613 | .Dl "0m0.00s real 0m0.00s user 0m0.00s system" |
| 4614 | .Pp |
| 4615 | If the |
| 4616 | .Fl p |
| 4617 | option is given the output is slightly longer: |
| 4618 | .Bd -literal -offset indent |
| 4619 | real 0.00 |
| 4620 | user 0.00 |
| 4621 | sys 0.00 |
| 4622 | .Ed |
| 4623 | .Pp |
| 4624 | It is an error to specify the |
| 4625 | .Fl p |
| 4626 | option unless |
| 4627 | .Ar pipeline |
| 4628 | is a simple command. |
| 4629 | .Pp |
| 4630 | Simple redirections of standard error do not affect the output of the |
| 4631 | .Ic time |
| 4632 | command: |
| 4633 | .Pp |
| 4634 | .Dl $ time sleep 1 2\*(Gtafile |
| 4635 | .Dl $ { time sleep 1; } 2\*(Gtafile |
| 4636 | .Pp |
| 4637 | Times for the first command do not go to |
| 4638 | .Dq afile , |
| 4639 | but those of the second command do. |
| 4640 | .Pp |
| 4641 | .It Ic times |
| 4642 | Print the accumulated user and system times used both by the shell |
| 4643 | and by processes that the shell started which have exited. |
| 4644 | The format of the output is: |
| 4645 | .Bd -literal -offset indent |
| 4646 | 0m0.00s 0m0.00s |
| 4647 | 0m0.00s 0m0.00s |
| 4648 | .Ed |
| 4649 | .Pp |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4650 | .It Ic trap Ar n Op Ar signal ... |
| 4651 | If the first operand is a decimal unsigned integer, this resets all |
| 4652 | specified signals to the default action, i.e. is the same as calling |
| 4653 | .Ic trap |
| 4654 | with a minus sign |
| 4655 | .Pq Sq \- |
| 4656 | as |
| 4657 | .Ar handler , |
| 4658 | followed by the arguments |
| 4659 | .Pq Ar n Op Ar signal ... , |
| 4660 | all of which are treated as signals. |
| 4661 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4662 | .It Ic trap Op Ar handler signal ... |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4663 | Sets a trap handler that is to be executed when any of the specified |
| 4664 | .Ar signal Ns s |
| 4665 | are received. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4666 | .Ar handler |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4667 | is either an empty string, indicating the signals are to be ignored, |
| 4668 | a minus sign |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4669 | .Pq Sq \- , |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4670 | indicating that the default action is to be taken for the signals |
| 4671 | .Pq see Xr signal 3 , |
| 4672 | or a string containing shell commands to be executed at the first opportunity |
| 4673 | (i.e. when the current command completes, or before printing the next |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4674 | .Ev PS1 |
| 4675 | prompt) after receipt of one of the signals. |
| 4676 | .Ar signal |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4677 | is the name of a signal |
| 4678 | .Pq e.g.\& Dv PIPE or Dv ALRM |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4679 | or the number of the signal (see the |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4680 | .Ic kill Fl l |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4681 | command above). |
| 4682 | .Pp |
| 4683 | There are two special signals: |
| 4684 | .Dv EXIT |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4685 | .Pq also known as 0 , |
| 4686 | which is executed when the shell is about to exit, and |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4687 | .Dv ERR , |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4688 | which is executed after an error occurs; an error is something |
| 4689 | that would cause the shell to exit if the |
| 4690 | .Ic set Fl e |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4691 | or |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4692 | .Ic set Fl o Ic errexit |
| 4693 | option were set. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4694 | .Dv EXIT |
| 4695 | handlers are executed in the environment of the last executed command. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4696 | .Pp |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4697 | Note that, for non-interactive shells, the trap handler cannot be changed |
| 4698 | for signals that were ignored when the shell started. |
| 4699 | .Pp |
| 4700 | With no arguments, the current state of the traps that have been set since |
| 4701 | the shell started is shown as a series of |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4702 | .Ic trap |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 4703 | commands. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4704 | Note that the output of |
| 4705 | .Ic trap |
| 4706 | cannot be usefully piped to another process (an artifact of the fact that |
| 4707 | traps are cleared when subprocesses are created). |
| 4708 | .Pp |
| 4709 | The original Korn shell's |
| 4710 | .Dv DEBUG |
| 4711 | trap and the handling of |
| 4712 | .Dv ERR |
| 4713 | and |
| 4714 | .Dv EXIT |
| 4715 | traps in functions are not yet implemented. |
| 4716 | .Pp |
| 4717 | .It Ic true |
| 4718 | A command that exits with a zero value. |
| 4719 | .Pp |
| 4720 | .It Xo |
| 4721 | .Ic global |
| 4722 | .Oo Op Ic +\-alpnrtUux |
| 4723 | .Op Fl L Ns Op Ar n |
| 4724 | .Op Fl R Ns Op Ar n |
| 4725 | .Op Fl Z Ns Op Ar n |
| 4726 | .Op Fl i Ns Op Ar n |
| 4727 | .No \*(Ba Fl f Op Fl tux Oc |
| 4728 | .Oo Ar name |
| 4729 | .Op Ns = Ns Ar value |
| 4730 | .Ar ... Oc |
| 4731 | .Xc |
| 4732 | .It Xo |
| 4733 | .Ic typeset |
| 4734 | .Oo Op Ic +\-alpnrtUux |
| 4735 | .Op Fl LRZ Ns Op Ar n |
| 4736 | .Op Fl i Ns Op Ar n |
| 4737 | .No \*(Ba Fl f Op Fl tux Oc |
| 4738 | .Oo Ar name |
| 4739 | .Op Ns = Ns Ar value |
| 4740 | .Ar ... Oc |
| 4741 | .Xc |
| 4742 | Display or set parameter attributes. |
| 4743 | With no |
| 4744 | .Ar name |
| 4745 | arguments, parameter attributes are displayed; if no options are used, the |
| 4746 | current attributes of all parameters are printed as |
| 4747 | .Ic typeset |
| 4748 | commands; if an option is given (or |
| 4749 | .Ql \- |
| 4750 | with no option letter), all parameters and their values with the specified |
| 4751 | attributes are printed; if options are introduced with |
| 4752 | .Ql + , |
| 4753 | parameter values are not printed. |
| 4754 | .Pp |
| 4755 | If |
| 4756 | .Ar name |
| 4757 | arguments are given, the attributes of the named parameters are set |
| 4758 | .Pq Ic \- |
| 4759 | or cleared |
| 4760 | .Pq Ic + . |
| 4761 | Values for parameters may optionally be specified. |
| 4762 | For |
| 4763 | .Ar name Ns \&[*] , |
| 4764 | the change affects the entire array, and no value may be specified. |
| 4765 | .Pp |
| 4766 | If |
| 4767 | .Ic typeset |
| 4768 | is used inside a function, any parameters specified are localised. |
| 4769 | This is not done by the otherwise identical |
| 4770 | .Ic global . |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 4771 | .Em Note : |
| 4772 | This means that |
| 4773 | .Nm No 's Ic global |
| 4774 | command is |
| 4775 | .Em not |
| 4776 | equivalent to other programming languages' as it does not allow a |
| 4777 | function called from another function to access a parameter at truly |
| 4778 | global scope, but only prevents putting an accessed one into local scope. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4779 | .Pp |
| 4780 | When |
| 4781 | .Fl f |
| 4782 | is used, |
| 4783 | .Ic typeset |
| 4784 | operates on the attributes of functions. |
| 4785 | As with parameters, if no |
| 4786 | .Ar name |
| 4787 | arguments are given, |
| 4788 | functions are listed with their values (i.e. definitions) unless |
| 4789 | options are introduced with |
| 4790 | .Ql + , |
| 4791 | in which case only the function names are reported. |
| 4792 | .Bl -tag -width Ds |
| 4793 | .It Fl a |
| 4794 | Indexed array attribute. |
| 4795 | .It Fl f |
| 4796 | Function mode. |
| 4797 | Display or set functions and their attributes, instead of parameters. |
| 4798 | .It Fl i Ns Op Ar n |
| 4799 | Integer attribute. |
| 4800 | .Ar n |
| 4801 | specifies the base to use when displaying the integer (if not specified, the |
| 4802 | base given in the first assignment is used). |
| 4803 | Parameters with this attribute may |
| 4804 | be assigned values containing arithmetic expressions. |
| 4805 | .It Fl L Ns Op Ar n |
| 4806 | Left justify attribute. |
| 4807 | .Ar n |
| 4808 | specifies the field width. |
| 4809 | If |
| 4810 | .Ar n |
| 4811 | is not specified, the current width of a parameter (or the width of its first |
| 4812 | assigned value) is used. |
| 4813 | Leading whitespace (and zeros, if used with the |
| 4814 | .Fl Z |
| 4815 | option) is stripped. |
| 4816 | If necessary, values are either truncated or space padded |
| 4817 | to fit the field width. |
| 4818 | .It Fl l |
| 4819 | Lower case attribute. |
| 4820 | All upper case characters in values are converted to lower case. |
| 4821 | (In the original Korn shell, this parameter meant |
| 4822 | .Dq long integer |
| 4823 | when used with the |
| 4824 | .Fl i |
| 4825 | option.) |
| 4826 | .It Fl n |
| 4827 | Create a bound variable (name reference): any access to the variable |
| 4828 | .Ar name |
| 4829 | will access the variable |
| 4830 | .Ar value |
| 4831 | in the current scope (this is different from |
| 4832 | .At |
| 4833 | .Nm ksh93 ! ) |
| 4834 | instead. |
| 4835 | Also different from |
| 4836 | .At |
| 4837 | .Nm ksh93 |
| 4838 | is that |
| 4839 | .Ar value |
| 4840 | is lazily evaluated at the time |
| 4841 | .Ar name |
| 4842 | is accessed. |
| 4843 | This can be used by functions to access variables whose names are |
| 4844 | passed as parametres, instead of using |
| 4845 | .Ic eval . |
| 4846 | .It Fl p |
| 4847 | Print complete |
| 4848 | .Ic typeset |
| 4849 | commands that can be used to re-create the attributes and values of |
| 4850 | parameters. |
| 4851 | .It Fl R Ns Op Ar n |
| 4852 | Right justify attribute. |
| 4853 | .Ar n |
| 4854 | specifies the field width. |
| 4855 | If |
| 4856 | .Ar n |
| 4857 | is not specified, the current width of a parameter (or the width of its first |
| 4858 | assigned value) is used. |
| 4859 | Trailing whitespace is stripped. |
| 4860 | If necessary, values are either stripped of leading characters or space |
| 4861 | padded to make them fit the field width. |
| 4862 | .It Fl r |
| 4863 | Read-only attribute. |
| 4864 | Parameters with this attribute may not be assigned to or unset. |
| 4865 | Once this attribute is set, it cannot be turned off. |
| 4866 | .It Fl t |
| 4867 | Tag attribute. |
| 4868 | Has no meaning to the shell; provided for application use. |
| 4869 | .Pp |
| 4870 | For functions, |
| 4871 | .Fl t |
| 4872 | is the trace attribute. |
| 4873 | When functions with the trace attribute are executed, the |
| 4874 | .Ic xtrace |
| 4875 | .Pq Fl x |
| 4876 | shell option is temporarily turned on. |
| 4877 | .It Fl U |
| 4878 | Unsigned integer attribute. |
| 4879 | Integers are printed as unsigned values (combine with the |
| 4880 | .Fl i |
| 4881 | option). |
| 4882 | This option is not in the original Korn shell. |
| 4883 | .It Fl u |
| 4884 | Upper case attribute. |
| 4885 | All lower case characters in values are converted to upper case. |
| 4886 | (In the original Korn shell, this parameter meant |
| 4887 | .Dq unsigned integer |
| 4888 | when used with the |
| 4889 | .Fl i |
| 4890 | option which meant upper case letters would never be used for bases greater |
| 4891 | than 10. |
| 4892 | See the |
| 4893 | .Fl U |
| 4894 | option.) |
| 4895 | .Pp |
| 4896 | For functions, |
| 4897 | .Fl u |
| 4898 | is the undefined attribute. |
| 4899 | See |
| 4900 | .Sx Functions |
| 4901 | above for the implications of this. |
| 4902 | .It Fl x |
| 4903 | Export attribute. |
| 4904 | Parameters (or functions) are placed in the environment of |
| 4905 | any executed commands. |
| 4906 | Exported functions are not yet implemented. |
| 4907 | .It Fl Z Ns Op Ar n |
| 4908 | Zero fill attribute. |
| 4909 | If not combined with |
| 4910 | .Fl L , |
| 4911 | this is the same as |
| 4912 | .Fl R , |
| 4913 | except zero padding is used instead of space padding. |
| 4914 | For integers, the number instead of the base is padded. |
| 4915 | .El |
| 4916 | .Pp |
| 4917 | If any of the |
| 4918 | .\" long integer , |
| 4919 | .Fl i , |
| 4920 | .Fl L , |
| 4921 | .Fl l , |
| 4922 | .Fl R , |
| 4923 | .Fl U , |
| 4924 | .Fl u , |
| 4925 | or |
| 4926 | .Fl Z |
| 4927 | options are changed, all others from this set are cleared, |
| 4928 | unless they are also given on the same command line. |
| 4929 | .Pp |
| 4930 | .It Xo |
| 4931 | .Ic ulimit |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 4932 | .Op Fl aBCcdefHilMmnOPpqrSsTtVvw |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4933 | .Op Ar value |
| 4934 | .Xc |
| 4935 | Display or set process limits. |
| 4936 | If no options are used, the file size limit |
| 4937 | .Pq Fl f |
| 4938 | is assumed. |
| 4939 | .Ar value , |
| 4940 | if specified, may be either an arithmetic expression or the word |
| 4941 | .Dq unlimited . |
| 4942 | The limits affect the shell and any processes created by the shell after a |
| 4943 | limit is imposed. |
| 4944 | Note that some systems may not allow limits to be increased |
| 4945 | once they are set. |
| 4946 | Also note that the types of limits available are system |
| 4947 | dependent \*(en some systems have only the |
| 4948 | .Fl f |
| 4949 | limit. |
| 4950 | .Bl -tag -width 5n |
| 4951 | .It Fl a |
| 4952 | Display all limits; unless |
| 4953 | .Fl H |
| 4954 | is used, soft limits are displayed. |
| 4955 | .It Fl B Ar n |
| 4956 | Set the socket buffer size to |
| 4957 | .Ar n |
| 4958 | kibibytes. |
| 4959 | .It Fl C Ar n |
| 4960 | Set the number of cached threads to |
| 4961 | .Ar n . |
| 4962 | .It Fl c Ar n |
| 4963 | Impose a size limit of |
| 4964 | .Ar n |
| 4965 | blocks on the size of core dumps. |
| 4966 | .It Fl d Ar n |
| 4967 | Impose a size limit of |
| 4968 | .Ar n |
| 4969 | kibibytes on the size of the data area. |
| 4970 | .It Fl e Ar n |
| 4971 | Set the maximum niceness to |
| 4972 | .Ar n . |
| 4973 | .It Fl f Ar n |
| 4974 | Impose a size limit of |
| 4975 | .Ar n |
| 4976 | blocks on files written by the shell and its child processes (files of any |
| 4977 | size may be read). |
| 4978 | .It Fl H |
| 4979 | Set the hard limit only (the default is to set both hard and soft limits). |
| 4980 | .It Fl i Ar n |
| 4981 | Set the number of pending signals to |
| 4982 | .Ar n . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 4983 | .It Fl l Ar n |
| 4984 | Impose a limit of |
| 4985 | .Ar n |
| 4986 | kibibytes on the amount of locked (wired) physical memory. |
| 4987 | .It Fl M Ar n |
| 4988 | Set the AIO locked memory to |
| 4989 | .Ar n |
| 4990 | kibibytes. |
| 4991 | .It Fl m Ar n |
| 4992 | Impose a limit of |
| 4993 | .Ar n |
| 4994 | kibibytes on the amount of physical memory used. |
| 4995 | .It Fl n Ar n |
| 4996 | Impose a limit of |
| 4997 | .Ar n |
| 4998 | file descriptors that can be open at once. |
| 4999 | .It Fl O Ar n |
| 5000 | Set the number of AIO operations to |
| 5001 | .Ar n . |
| 5002 | .It Fl P Ar n |
| 5003 | Limit the number of threads per process to |
| 5004 | .Ar n . |
| 5005 | .It Fl p Ar n |
| 5006 | Impose a limit of |
| 5007 | .Ar n |
| 5008 | processes that can be run by the user at any one time. |
| 5009 | .It Fl q Ar n |
| 5010 | Limit the size of |
| 5011 | .Tn POSIX |
| 5012 | message queues to |
| 5013 | .Ar n |
| 5014 | bytes. |
| 5015 | .It Fl r Ar n |
| 5016 | Set the maximum real-time priority to |
| 5017 | .Ar n . |
| 5018 | .It Fl S |
| 5019 | Set the soft limit only (the default is to set both hard and soft limits). |
| 5020 | .It Fl s Ar n |
| 5021 | Impose a size limit of |
| 5022 | .Ar n |
| 5023 | kibibytes on the size of the stack area. |
| 5024 | .It Fl T Ar n |
| 5025 | Impose a time limit of |
| 5026 | .Ar n |
| 5027 | real seconds to be used by each process. |
| 5028 | .It Fl t Ar n |
| 5029 | Impose a time limit of |
| 5030 | .Ar n |
| 5031 | CPU seconds spent in user mode to be used by each process. |
| 5032 | .It Fl V Ar n |
| 5033 | Set the number of vnode monitors on Haiku to |
| 5034 | .Ar n . |
| 5035 | .It Fl v Ar n |
| 5036 | Impose a limit of |
| 5037 | .Ar n |
| 5038 | kibibytes on the amount of virtual memory (address space) used. |
| 5039 | .It Fl w Ar n |
| 5040 | Impose a limit of |
| 5041 | .Ar n |
| 5042 | kibibytes on the amount of swap space used. |
| 5043 | .El |
| 5044 | .Pp |
| 5045 | As far as |
| 5046 | .Ic ulimit |
| 5047 | is concerned, a block is 512 bytes. |
| 5048 | .Pp |
| 5049 | .It Xo |
| 5050 | .Ic umask |
| 5051 | .Op Fl S |
| 5052 | .Op Ar mask |
| 5053 | .Xc |
| 5054 | Display or set the file permission creation mask, or umask (see |
| 5055 | .Xr umask 2 ) . |
| 5056 | If the |
| 5057 | .Fl S |
| 5058 | option is used, the mask displayed or set is symbolic; otherwise, it is an |
| 5059 | octal number. |
| 5060 | .Pp |
| 5061 | Symbolic masks are like those used by |
| 5062 | .Xr chmod 1 . |
| 5063 | When used, they describe what permissions may be made available (as opposed to |
| 5064 | octal masks in which a set bit means the corresponding bit is to be cleared). |
| 5065 | For example, |
| 5066 | .Dq ug=rwx,o= |
| 5067 | sets the mask so files will not be readable, writable, or executable by |
| 5068 | .Dq others , |
| 5069 | and is equivalent (on most systems) to the octal mask |
| 5070 | .Dq 007 . |
| 5071 | .Pp |
| 5072 | .It Xo |
| 5073 | .Ic unalias |
| 5074 | .Op Fl adt |
| 5075 | .Op Ar name ... |
| 5076 | .Xc |
| 5077 | The aliases for the given names are removed. |
| 5078 | If the |
| 5079 | .Fl a |
| 5080 | option is used, all aliases are removed. |
| 5081 | If the |
| 5082 | .Fl t |
| 5083 | or |
| 5084 | .Fl d |
| 5085 | options are used, the indicated operations are carried out on tracked or |
| 5086 | directory aliases, respectively. |
| 5087 | .Pp |
| 5088 | .It Xo |
| 5089 | .Ic unset |
| 5090 | .Op Fl fv |
| 5091 | .Ar parameter ... |
| 5092 | .Xc |
| 5093 | Unset the named parameters |
| 5094 | .Po |
| 5095 | .Fl v , |
| 5096 | the default |
| 5097 | .Pc |
| 5098 | or functions |
| 5099 | .Pq Fl f . |
| 5100 | With |
| 5101 | .Ar parameter Ns \&[*] , |
| 5102 | attributes are kept, only values are unset. |
| 5103 | .Pp |
| 5104 | The exit status is non-zero if any of the parameters have the read-only |
| 5105 | attribute set, zero otherwise. |
| 5106 | .Pp |
| 5107 | .It Ic wait Op Ar job ... |
| 5108 | Wait for the specified job(s) to finish. |
| 5109 | The exit status of |
| 5110 | .Ic wait |
| 5111 | is that of the last specified job; if the last job is killed by a signal, the |
| 5112 | exit status is 128 + the number of the signal (see |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5113 | .Ic kill Fl l Ar exit-status |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5114 | above); if the last specified job can't be found (because it never existed, or |
| 5115 | had already finished), the exit status of |
| 5116 | .Ic wait |
| 5117 | is 127. |
| 5118 | See |
| 5119 | .Sx Job control |
| 5120 | below for the format of |
| 5121 | .Ar job . |
| 5122 | .Ic wait |
| 5123 | will return if a signal for which a trap has been set is received, or if a |
| 5124 | .Dv SIGHUP , |
| 5125 | .Dv SIGINT , |
| 5126 | or |
| 5127 | .Dv SIGQUIT |
| 5128 | signal is received. |
| 5129 | .Pp |
| 5130 | If no jobs are specified, |
| 5131 | .Ic wait |
| 5132 | waits for all currently running jobs (if any) to finish and exits with a zero |
| 5133 | status. |
| 5134 | If job monitoring is enabled, the completion status of jobs is printed |
| 5135 | (this is not the case when jobs are explicitly specified). |
| 5136 | .Pp |
| 5137 | .It Xo |
| 5138 | .Ic whence |
| 5139 | .Op Fl pv |
| 5140 | .Op Ar name ... |
| 5141 | .Xc |
| 5142 | For each |
| 5143 | .Ar name , |
| 5144 | the type of command is listed (reserved word, built-in, alias, |
| 5145 | function, tracked alias, or executable). |
| 5146 | If the |
| 5147 | .Fl p |
| 5148 | option is used, a path search is performed even if |
| 5149 | .Ar name |
| 5150 | is a reserved word, alias, etc. |
| 5151 | Without the |
| 5152 | .Fl v |
| 5153 | option, |
| 5154 | .Ic whence |
| 5155 | is similar to |
| 5156 | .Ic command Fl v |
| 5157 | except that |
| 5158 | .Ic whence |
| 5159 | will find reserved words and won't print aliases as alias commands. |
| 5160 | With the |
| 5161 | .Fl v |
| 5162 | option, |
| 5163 | .Ic whence |
| 5164 | is the same as |
| 5165 | .Ic command Fl V . |
| 5166 | Note that for |
| 5167 | .Ic whence , |
| 5168 | the |
| 5169 | .Fl p |
| 5170 | option does not affect the search path used, as it does for |
| 5171 | .Ic command . |
| 5172 | If the type of one or more of the names could not be determined, the exit |
| 5173 | status is non-zero. |
| 5174 | .El |
| 5175 | .Ss Job control |
| 5176 | Job control refers to the shell's ability to monitor and control jobs which |
| 5177 | are processes or groups of processes created for commands or pipelines. |
| 5178 | At a minimum, the shell keeps track of the status of the background (i.e.\& |
| 5179 | asynchronous) jobs that currently exist; this information can be displayed |
| 5180 | using the |
| 5181 | .Ic jobs |
| 5182 | commands. |
| 5183 | If job control is fully enabled (using |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5184 | .Ic set Fl m |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5185 | or |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5186 | .Ic set Fl o Ic monitor ) , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5187 | as it is for interactive shells, the processes of a job are placed in their |
| 5188 | own process group. |
| 5189 | Foreground jobs can be stopped by typing the suspend |
| 5190 | character from the terminal (normally \*(haZ), jobs can be restarted in either the |
| 5191 | foreground or background using the |
| 5192 | .Ic fg |
| 5193 | and |
| 5194 | .Ic bg |
| 5195 | commands, and the state of the terminal is saved or restored when a foreground |
| 5196 | job is stopped or restarted, respectively. |
| 5197 | .Pp |
| 5198 | Note that only commands that create processes (e.g. asynchronous commands, |
| 5199 | subshell commands, and non-built-in, non-function commands) can be stopped; |
| 5200 | commands like |
| 5201 | .Ic read |
| 5202 | cannot be. |
| 5203 | .Pp |
| 5204 | When a job is created, it is assigned a job number. |
| 5205 | For interactive shells, this number is printed inside |
| 5206 | .Dq \&[..] , |
| 5207 | followed by the process IDs of the processes in the job when an asynchronous |
| 5208 | command is run. |
| 5209 | A job may be referred to in the |
| 5210 | .Ic bg , |
| 5211 | .Ic fg , |
| 5212 | .Ic jobs , |
| 5213 | .Ic kill , |
| 5214 | and |
| 5215 | .Ic wait |
| 5216 | commands either by the process ID of the last process in the command pipeline |
| 5217 | (as stored in the |
| 5218 | .Ic $!\& |
| 5219 | parameter) or by prefixing the job number with a percent |
| 5220 | sign |
| 5221 | .Pq Sq % . |
| 5222 | Other percent sequences can also be used to refer to jobs: |
| 5223 | .Bl -tag -width "%+ x %% x %XX" |
| 5224 | .It %+ \*(Ba %% \*(Ba % |
| 5225 | The most recently stopped job, or, if there are no stopped jobs, the oldest |
| 5226 | running job. |
| 5227 | .It %\- |
| 5228 | The job that would be the |
| 5229 | .Ic %+ |
| 5230 | job if the latter did not exist. |
| 5231 | .It % Ns Ar n |
| 5232 | The job with job number |
| 5233 | .Ar n . |
| 5234 | .It %? Ns Ar string |
| 5235 | The job with its command containing the string |
| 5236 | .Ar string |
| 5237 | (an error occurs if multiple jobs are matched). |
| 5238 | .It % Ns Ar string |
| 5239 | The job with its command starting with the string |
| 5240 | .Ar string |
| 5241 | (an error occurs if multiple jobs are matched). |
| 5242 | .El |
| 5243 | .Pp |
| 5244 | When a job changes state (e.g. a background job finishes or foreground job is |
| 5245 | stopped), the shell prints the following status information: |
| 5246 | .Pp |
| 5247 | .D1 [ Ns Ar number ] Ar flag status command |
| 5248 | .Pp |
| 5249 | where... |
| 5250 | .Bl -tag -width "command" |
| 5251 | .It Ar number |
| 5252 | is the job number of the job; |
| 5253 | .It Ar flag |
| 5254 | is the |
| 5255 | .Ql + |
| 5256 | or |
| 5257 | .Ql \- |
| 5258 | character if the job is the |
| 5259 | .Ic %+ |
| 5260 | or |
| 5261 | .Ic %\- |
| 5262 | job, respectively, or space if it is neither; |
| 5263 | .It Ar status |
| 5264 | indicates the current state of the job and can be: |
| 5265 | .Bl -tag -width "RunningXX" |
| 5266 | .It Done Op Ar number |
| 5267 | The job exited. |
| 5268 | .Ar number |
| 5269 | is the exit status of the job which is omitted if the status is zero. |
| 5270 | .It Running |
| 5271 | The job has neither stopped nor exited (note that running does not necessarily |
| 5272 | mean consuming CPU time \*(en |
| 5273 | the process could be blocked waiting for some event). |
| 5274 | .It Stopped Op Ar signal |
| 5275 | The job was stopped by the indicated |
| 5276 | .Ar signal |
| 5277 | (if no signal is given, the job was stopped by |
| 5278 | .Dv SIGTSTP ) . |
| 5279 | .It Ar signal-description Op Dq core dumped |
| 5280 | The job was killed by a signal (e.g. memory fault, hangup); use |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5281 | .Ic kill Fl l |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5282 | for a list of signal descriptions. |
| 5283 | The |
| 5284 | .Dq core dumped |
| 5285 | message indicates the process created a core file. |
| 5286 | .El |
| 5287 | .It Ar command |
| 5288 | is the command that created the process. |
| 5289 | If there are multiple processes in |
| 5290 | the job, each process will have a line showing its |
| 5291 | .Ar command |
| 5292 | and possibly its |
| 5293 | .Ar status , |
| 5294 | if it is different from the status of the previous process. |
| 5295 | .El |
| 5296 | .Pp |
| 5297 | When an attempt is made to exit the shell while there are jobs in the stopped |
| 5298 | state, the shell warns the user that there are stopped jobs and does not exit. |
| 5299 | If another attempt is immediately made to exit the shell, the stopped jobs are |
| 5300 | sent a |
| 5301 | .Dv SIGHUP |
| 5302 | signal and the shell exits. |
| 5303 | Similarly, if the |
| 5304 | .Ic nohup |
| 5305 | option is not set and there are running jobs when an attempt is made to exit |
| 5306 | a login shell, the shell warns the user and does not exit. |
| 5307 | If another attempt |
| 5308 | is immediately made to exit the shell, the running jobs are sent a |
| 5309 | .Dv SIGHUP |
| 5310 | signal and the shell exits. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 5311 | .Ss POSIX mode |
| 5312 | Entering |
| 5313 | .Ic set Fl o Ic posix |
| 5314 | mode will cause |
| 5315 | .Nm |
| 5316 | to behave even more |
| 5317 | .Tn POSIX |
| 5318 | compliant in places where the defaults or opinions differ. |
| 5319 | Note that |
| 5320 | .Nm mksh |
| 5321 | will still operate with unsigned 32-bit arithmetics; use |
| 5322 | .Nm lksh |
| 5323 | if arithmetics on the host |
| 5324 | .Vt long |
| 5325 | data type, complete with ISO C Undefined Behaviour, are required; |
| 5326 | refer to the |
| 5327 | .Xr lksh 1 |
| 5328 | manual page for details. |
| 5329 | Most other historic, |
| 5330 | .At |
| 5331 | .Nm ksh Ns -compatible , |
| 5332 | or opinionated differences can be disabled by using this mode; these are: |
| 5333 | .Bl -bullet |
| 5334 | .It |
| 5335 | The GNU |
| 5336 | .Nm bash |
| 5337 | I/O redirection |
| 5338 | .Ic &\*(Gt Ns Ar file |
| 5339 | is no longer supported. |
| 5340 | .It |
| 5341 | File descriptors created by I/O redirections are inherited by |
| 5342 | child processes. |
| 5343 | .It |
| 5344 | Numbers with a leading digit zero are interpreted as octal. |
| 5345 | .It |
| 5346 | The |
| 5347 | .Nm echo |
| 5348 | builtin does not interpret backslashes and only supports the exact option |
| 5349 | .Dq Fl n . |
| 5350 | .It |
| 5351 | \&... (list is incomplete and may change for R53) |
| 5352 | .El |
| 5353 | .Ss SH mode |
| 5354 | Compatibility mode; intended for use with legacy scripts that |
| 5355 | cannot easily be fixed; the changes are as follows: |
| 5356 | .Bl -bullet |
| 5357 | .It |
| 5358 | The GNU |
| 5359 | .Nm bash |
| 5360 | I/O redirection |
| 5361 | .Ic &\*(Gt Ns Ar file |
| 5362 | is no longer supported. |
| 5363 | .It |
| 5364 | File descriptors created by I/O redirections are inherited by |
| 5365 | child processes. |
| 5366 | .It |
| 5367 | The |
| 5368 | .Nm echo |
| 5369 | builtin does not interpret backslashes and only supports the exact option |
| 5370 | .Dq Fl n . |
| 5371 | .It |
| 5372 | \&... (list is incomplete and may change for R53) |
| 5373 | .El |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5374 | .Ss Interactive input line editing |
| 5375 | The shell supports three modes of reading command lines from a |
| 5376 | .Xr tty 4 |
| 5377 | in an interactive session, controlled by the |
| 5378 | .Ic emacs , |
| 5379 | .Ic gmacs , |
| 5380 | and |
| 5381 | .Ic vi |
| 5382 | options (at most one of these can be set at once). |
| 5383 | The default is |
| 5384 | .Ic emacs . |
| 5385 | Editing modes can be set explicitly using the |
| 5386 | .Ic set |
| 5387 | built-in. |
| 5388 | If none of these options are enabled, |
| 5389 | the shell simply reads lines using the normal |
| 5390 | .Xr tty 4 |
| 5391 | driver. |
| 5392 | If the |
| 5393 | .Ic emacs |
| 5394 | or |
| 5395 | .Ic gmacs |
| 5396 | option is set, the shell allows emacs-like editing of the command; similarly, |
| 5397 | if the |
| 5398 | .Ic vi |
| 5399 | option is set, the shell allows vi-like editing of the command. |
| 5400 | These modes are described in detail in the following sections. |
| 5401 | .Pp |
| 5402 | In these editing modes, if a line is longer than the screen width (see the |
| 5403 | .Ev COLUMNS |
| 5404 | parameter), |
| 5405 | a |
| 5406 | .Ql \*(Gt , |
| 5407 | .Ql + , |
| 5408 | or |
| 5409 | .Ql \*(Lt |
| 5410 | character is displayed in the last column indicating that there are more |
| 5411 | characters after, before and after, or before the current position, |
| 5412 | respectively. |
| 5413 | The line is scrolled horizontally as necessary. |
| 5414 | .Pp |
| 5415 | Completed lines are pushed into the history, unless they begin with an |
| 5416 | IFS octet or IFS white space, or are the same as the previous line. |
| 5417 | .Ss Emacs editing mode |
| 5418 | When the |
| 5419 | .Ic emacs |
| 5420 | option is set, interactive input line editing is enabled. |
| 5421 | Warning: This mode is |
| 5422 | slightly different from the emacs mode in the original Korn shell. |
| 5423 | In this mode, various editing commands |
| 5424 | (typically bound to one or more control characters) cause immediate actions |
| 5425 | without waiting for a newline. |
| 5426 | Several editing commands are bound to particular |
| 5427 | control characters when the shell is invoked; these bindings can be changed |
| 5428 | using the |
| 5429 | .Ic bind |
| 5430 | command. |
| 5431 | .Pp |
| 5432 | The following is a list of available editing commands. |
| 5433 | Each description starts with the name of the command, |
| 5434 | suffixed with a colon; |
| 5435 | an |
| 5436 | .Op Ar n |
| 5437 | (if the command can be prefixed with a count); and any keys the command is |
| 5438 | bound to by default, written using caret notation |
| 5439 | e.g. the ASCII ESC character is written as \*(ha[. |
| 5440 | These control sequences are not case sensitive. |
| 5441 | A count prefix for a command is entered using the sequence |
| 5442 | .Pf \*(ha[ Ns Ar n , |
| 5443 | where |
| 5444 | .Ar n |
| 5445 | is a sequence of 1 or more digits. |
| 5446 | Unless otherwise specified, if a count is |
| 5447 | omitted, it defaults to 1. |
| 5448 | .Pp |
| 5449 | Note that editing command names are used only with the |
| 5450 | .Ic bind |
| 5451 | command. |
| 5452 | Furthermore, many editing commands are useful only on terminals with |
| 5453 | a visible cursor. |
| 5454 | The default bindings were chosen to resemble corresponding |
| 5455 | Emacs key bindings. |
| 5456 | The user's |
| 5457 | .Xr tty 4 |
| 5458 | characters (e.g.\& |
| 5459 | .Dv ERASE ) |
| 5460 | are bound to |
| 5461 | reasonable substitutes and override the default bindings. |
| 5462 | .Bl -tag -width Ds |
| 5463 | .It abort: \*(haC, \*(haG |
| 5464 | Abort the current command, empty the line buffer and |
| 5465 | set the exit state to interrupted. |
| 5466 | .It auto\-insert: Op Ar n |
| 5467 | Simply causes the character to appear as literal input. |
| 5468 | Most ordinary characters are bound to this. |
| 5469 | .It Xo backward\-char: |
| 5470 | .Op Ar n |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5471 | .No \*(haB , \*(haXD , ANSI-CurLeft , PC-CurLeft |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5472 | .Xc |
| 5473 | Moves the cursor backward |
| 5474 | .Ar n |
| 5475 | characters. |
| 5476 | .It Xo backward\-word: |
| 5477 | .Op Ar n |
| 5478 | .No \*(ha[b , ANSI-Ctrl-CurLeft , ANSI-Alt-CurLeft |
| 5479 | .Xc |
| 5480 | Moves the cursor backward to the beginning of the word; words consist of |
| 5481 | alphanumerics, underscore |
| 5482 | .Pq Sq _ , |
| 5483 | and dollar sign |
| 5484 | .Pq Sq $ |
| 5485 | characters. |
| 5486 | .It beginning\-of\-history: \*(ha[\*(Lt |
| 5487 | Moves to the beginning of the history. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5488 | .It beginning\-of\-line: \*(haA, ANSI-Home, PC-Home |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5489 | Moves the cursor to the beginning of the edited input line. |
| 5490 | .It Xo capitalise\-word: |
| 5491 | .Op Ar n |
| 5492 | .No \*(ha[C , \*(ha[c |
| 5493 | .Xc |
| 5494 | Uppercase the first character in the next |
| 5495 | .Ar n |
| 5496 | words, leaving the cursor past the end of the last word. |
| 5497 | .It clear\-screen: \*(ha[\*(haL |
| 5498 | Prints a compile-time configurable sequence to clear the screen and home |
| 5499 | the cursor, redraws the entire prompt and the currently edited input line. |
| 5500 | The default sequence works for almost all standard terminals. |
| 5501 | .It comment: \*(ha[# |
| 5502 | If the current line does not begin with a comment character, one is added at |
| 5503 | the beginning of the line and the line is entered (as if return had been |
| 5504 | pressed); otherwise, the existing comment characters are removed and the cursor |
| 5505 | is placed at the beginning of the line. |
| 5506 | .It complete: \*(ha[\*(ha[ |
| 5507 | Automatically completes as much as is unique of the command name or the file |
| 5508 | name containing the cursor. |
| 5509 | If the entire remaining command or file name is |
| 5510 | unique, a space is printed after its completion, unless it is a directory name |
| 5511 | in which case |
| 5512 | .Ql / |
| 5513 | is appended. |
| 5514 | If there is no command or file name with the current partial word |
| 5515 | as its prefix, a bell character is output (usually causing a beep to be |
| 5516 | sounded). |
| 5517 | .It complete\-command: \*(haX\*(ha[ |
| 5518 | Automatically completes as much as is unique of the command name having the |
| 5519 | partial word up to the cursor as its prefix, as in the |
| 5520 | .Ic complete |
| 5521 | command above. |
| 5522 | .It complete\-file: \*(ha[\*(haX |
| 5523 | Automatically completes as much as is unique of the file name having the |
| 5524 | partial word up to the cursor as its prefix, as in the |
| 5525 | .Ic complete |
| 5526 | command described above. |
| 5527 | .It complete\-list: \*(haI, \*(ha[= |
| 5528 | Complete as much as is possible of the current word, |
| 5529 | and list the possible completions for it. |
| 5530 | If only one completion is possible, |
| 5531 | match as in the |
| 5532 | .Ic complete |
| 5533 | command above. |
| 5534 | Note that \*(haI is usually generated by the TAB (tabulator) key. |
| 5535 | .It Xo delete\-char\-backward: |
| 5536 | .Op Ar n |
| 5537 | .No ERASE , \*(ha? , \*(haH |
| 5538 | .Xc |
| 5539 | Deletes |
| 5540 | .Ar n |
| 5541 | characters before the cursor. |
| 5542 | .It Xo delete\-char\-forward: |
| 5543 | .Op Ar n |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5544 | .No ANSI-Del , PC-Del |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5545 | .Xc |
| 5546 | Deletes |
| 5547 | .Ar n |
| 5548 | characters after the cursor. |
| 5549 | .It Xo delete\-word\-backward: |
| 5550 | .Op Ar n |
| 5551 | .No WERASE , \*(ha[\*(ha? , \*(ha[\*(haH , \*(ha[h |
| 5552 | .Xc |
| 5553 | Deletes |
| 5554 | .Ar n |
| 5555 | words before the cursor. |
| 5556 | .It Xo delete\-word\-forward: |
| 5557 | .Op Ar n |
| 5558 | .No \*(ha[d |
| 5559 | .Xc |
| 5560 | Deletes characters after the cursor up to the end of |
| 5561 | .Ar n |
| 5562 | words. |
| 5563 | .It Xo down\-history: |
| 5564 | .Op Ar n |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5565 | .No \*(haN , \*(haXB , ANSI-CurDown , PC-CurDown |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5566 | .Xc |
| 5567 | Scrolls the history buffer forward |
| 5568 | .Ar n |
| 5569 | lines (later). |
| 5570 | Each input line originally starts just after the last entry |
| 5571 | in the history buffer, so |
| 5572 | .Ic down\-history |
| 5573 | is not useful until either |
| 5574 | .Ic search\-history , |
| 5575 | .Ic search\-history\-up |
| 5576 | or |
| 5577 | .Ic up\-history |
| 5578 | has been performed. |
| 5579 | .It Xo downcase\-word: |
| 5580 | .Op Ar n |
| 5581 | .No \*(ha[L , \*(ha[l |
| 5582 | .Xc |
| 5583 | Lowercases the next |
| 5584 | .Ar n |
| 5585 | words. |
| 5586 | .It Xo edit\-line: |
| 5587 | .Op Ar n |
| 5588 | .No \*(haXe |
| 5589 | .Xc |
| 5590 | Edit line |
| 5591 | .Ar n |
| 5592 | or the current line, if not specified, interactively. |
| 5593 | The actual command executed is |
| 5594 | .Ic fc \-e ${VISUAL:\-${EDITOR:\-vi}} Ar n . |
| 5595 | .It end\-of\-history: \*(ha[\*(Gt |
| 5596 | Moves to the end of the history. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5597 | .It end\-of\-line: \*(haE, ANSI-End, PC-End |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5598 | Moves the cursor to the end of the input line. |
| 5599 | .It eot: \*(ha_ |
| 5600 | Acts as an end-of-file; this is useful because edit-mode input disables |
| 5601 | normal terminal input canonicalization. |
| 5602 | .It Xo eot\-or\-delete: |
| 5603 | .Op Ar n |
| 5604 | .No \*(haD |
| 5605 | .Xc |
| 5606 | Acts as |
| 5607 | .Ic eot |
| 5608 | if alone on a line; otherwise acts as |
| 5609 | .Ic delete\-char\-forward . |
| 5610 | .It error: (not bound) |
| 5611 | Error (ring the bell). |
| 5612 | .It exchange\-point\-and\-mark: \*(haX\*(haX |
| 5613 | Places the cursor where the mark is and sets the mark to where the cursor was. |
| 5614 | .It expand\-file: \*(ha[* |
| 5615 | Appends a |
| 5616 | .Ql * |
| 5617 | to the current word and replaces the word with the result of performing file |
| 5618 | globbing on the word. |
| 5619 | If no files match the pattern, the bell is rung. |
| 5620 | .It Xo forward\-char: |
| 5621 | .Op Ar n |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5622 | .No \*(haF , \*(haXC , ANSI-CurRight , PC-CurRight |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5623 | .Xc |
| 5624 | Moves the cursor forward |
| 5625 | .Ar n |
| 5626 | characters. |
| 5627 | .It Xo forward\-word: |
| 5628 | .Op Ar n |
| 5629 | .No \*(ha[f , ANSI-Ctrl-CurRight , ANSI-Alt-CurRight |
| 5630 | .Xc |
| 5631 | Moves the cursor forward to the end of the |
| 5632 | .Ar n Ns th |
| 5633 | word. |
| 5634 | .It Xo goto\-history: |
| 5635 | .Op Ar n |
| 5636 | .No \*(ha[g |
| 5637 | .Xc |
| 5638 | Goes to history number |
| 5639 | .Ar n . |
| 5640 | .It kill\-line: KILL |
| 5641 | Deletes the entire input line. |
| 5642 | .It kill\-region: \*(haW |
| 5643 | Deletes the input between the cursor and the mark. |
| 5644 | .It Xo kill\-to\-eol: |
| 5645 | .Op Ar n |
| 5646 | .No \*(haK |
| 5647 | .Xc |
| 5648 | Deletes the input from the cursor to the end of the line if |
| 5649 | .Ar n |
| 5650 | is not specified; otherwise deletes characters between the cursor and column |
| 5651 | .Ar n . |
| 5652 | .It list: \*(ha[? |
| 5653 | Prints a sorted, columnated list of command names or file names (if any) that |
| 5654 | can complete the partial word containing the cursor. |
| 5655 | Directory names have |
| 5656 | .Ql / |
| 5657 | appended to them. |
| 5658 | .It list\-command: \*(haX? |
| 5659 | Prints a sorted, columnated list of command names (if any) that can complete |
| 5660 | the partial word containing the cursor. |
| 5661 | .It list\-file: \*(haX\*(haY |
| 5662 | Prints a sorted, columnated list of file names (if any) that can complete the |
| 5663 | partial word containing the cursor. |
| 5664 | File type indicators are appended as described under |
| 5665 | .Ic list |
| 5666 | above. |
| 5667 | .It newline: \*(haJ , \*(haM |
| 5668 | Causes the current input line to be processed by the shell. |
| 5669 | The current cursor position may be anywhere on the line. |
| 5670 | .It newline\-and\-next: \*(haO |
| 5671 | Causes the current input line to be processed by the shell, and the next line |
| 5672 | from history becomes the current line. |
| 5673 | This is only useful after an |
| 5674 | .Ic up\-history , |
| 5675 | .Ic search\-history |
| 5676 | or |
| 5677 | .Ic search\-history\-up . |
| 5678 | .It no\-op: QUIT |
| 5679 | This does nothing. |
| 5680 | .It prefix\-1: \*(ha[ |
| 5681 | Introduces a 2-character command sequence. |
| 5682 | .It prefix\-2: \*(haX , \*(ha[[ , \*(ha[O |
| 5683 | Introduces a 2-character command sequence. |
| 5684 | .It Xo prev\-hist\-word: |
| 5685 | .Op Ar n |
| 5686 | .No \*(ha[. , \*(ha[_ |
| 5687 | .Xc |
| 5688 | The last word, or, if given, the |
| 5689 | .Ar n Ns th |
| 5690 | word (zero-based) of the previous (on repeated execution, second-last, |
| 5691 | third-last, etc.) command is inserted at the cursor. |
| 5692 | Use of this editing command trashes the mark. |
| 5693 | .It quote: \*(ha\*(ha , \*(haV |
| 5694 | The following character is taken literally rather than as an editing command. |
| 5695 | .It redraw: \*(haL |
| 5696 | Reprints the last line of the prompt string and the current input line |
| 5697 | on a new line. |
| 5698 | .It Xo search\-character\-backward: |
| 5699 | .Op Ar n |
| 5700 | .No \*(ha[\*(ha] |
| 5701 | .Xc |
| 5702 | Search backward in the current line for the |
| 5703 | .Ar n Ns th |
| 5704 | occurrence of the next character typed. |
| 5705 | .It Xo search\-character\-forward: |
| 5706 | .Op Ar n |
| 5707 | .No \*(ha] |
| 5708 | .Xc |
| 5709 | Search forward in the current line for the |
| 5710 | .Ar n Ns th |
| 5711 | occurrence of the next character typed. |
| 5712 | .It search\-history: \*(haR |
| 5713 | Enter incremental search mode. |
| 5714 | The internal history list is searched |
| 5715 | backwards for commands matching the input. |
| 5716 | An initial |
| 5717 | .Ql \*(ha |
| 5718 | in the search string anchors the search. |
| 5719 | The escape key will leave search mode. |
| 5720 | Other commands, including sequences of escape as |
| 5721 | .Ic prefix\-1 |
| 5722 | followed by a |
| 5723 | .Ic prefix\-1 |
| 5724 | or |
| 5725 | .Ic prefix\-2 |
| 5726 | key will be executed after leaving search mode. |
| 5727 | The |
| 5728 | .Ic abort Pq \*(haG |
| 5729 | command will restore the input line before search started. |
| 5730 | Successive |
| 5731 | .Ic search\-history |
| 5732 | commands continue searching backward to the next previous occurrence of the |
| 5733 | pattern. |
| 5734 | The history buffer retains only a finite number of lines; the oldest |
| 5735 | are discarded as necessary. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5736 | .It search\-history\-up: ANSI-PgUp, PC-PgUp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5737 | Search backwards through the history buffer for commands whose beginning match |
| 5738 | the portion of the input line before the cursor. |
| 5739 | When used on an empty line, this has the same effect as |
| 5740 | .Ic up\-history . |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5741 | .It search\-history\-down: ANSI-PgDn, PC-PgDn |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5742 | Search forwards through the history buffer for commands whose beginning match |
| 5743 | the portion of the input line before the cursor. |
| 5744 | When used on an empty line, this has the same effect as |
| 5745 | .Ic down\-history . |
| 5746 | This is only useful after an |
| 5747 | .Ic up\-history , |
| 5748 | .Ic search\-history |
| 5749 | or |
| 5750 | .Ic search\-history\-up . |
| 5751 | .It set\-mark\-command: \*(ha[ Ns Aq space |
| 5752 | Set the mark at the cursor position. |
| 5753 | .It transpose\-chars: \*(haT |
| 5754 | If at the end of line, or if the |
| 5755 | .Ic gmacs |
| 5756 | option is set, this exchanges the two previous characters; otherwise, it |
| 5757 | exchanges the previous and current characters and moves the cursor one |
| 5758 | character to the right. |
| 5759 | .It Xo up\-history: |
| 5760 | .Op Ar n |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5761 | .No \*(haP , \*(haXA , ANSI-CurUp , PC-CurUp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5762 | .Xc |
| 5763 | Scrolls the history buffer backward |
| 5764 | .Ar n |
| 5765 | lines (earlier). |
| 5766 | .It Xo upcase\-word: |
| 5767 | .Op Ar n |
| 5768 | .No \*(ha[U , \*(ha[u |
| 5769 | .Xc |
| 5770 | Uppercase the next |
| 5771 | .Ar n |
| 5772 | words. |
| 5773 | .It version: \*(ha[\*(haV |
| 5774 | Display the version of |
| 5775 | .Nm mksh . |
| 5776 | The current edit buffer is restored as soon as a key is pressed. |
| 5777 | The restoring keypress is processed, unless it is a space. |
| 5778 | .It yank: \*(haY |
| 5779 | Inserts the most recently killed text string at the current cursor position. |
| 5780 | .It yank\-pop: \*(ha[y |
| 5781 | Immediately after a |
| 5782 | .Ic yank , |
| 5783 | replaces the inserted text string with the next previously killed text string. |
| 5784 | .El |
| 5785 | .Ss Vi editing mode |
| 5786 | .Em Note: |
| 5787 | The vi command-line editing mode is orphaned, yet still functional. |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 5788 | It is 8-bit clean but specifically does not support UTF-8 or MBCS. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5789 | .Pp |
| 5790 | The vi command-line editor in |
| 5791 | .Nm |
| 5792 | has basically the same commands as the |
| 5793 | .Xr vi 1 |
| 5794 | editor with the following exceptions: |
| 5795 | .Bl -bullet |
| 5796 | .It |
| 5797 | You start out in insert mode. |
| 5798 | .It |
| 5799 | There are file name and command completion commands: |
| 5800 | =, \e, *, \*(haX, \*(haE, \*(haF, and, optionally, |
| 5801 | .Aq tab |
| 5802 | and |
| 5803 | .Aq esc . |
| 5804 | .It |
| 5805 | The |
| 5806 | .Ic _ |
| 5807 | command is different (in |
| 5808 | .Nm mksh , |
| 5809 | it is the last argument command; in |
| 5810 | .Xr vi 1 |
| 5811 | it goes to the start of the current line). |
| 5812 | .It |
| 5813 | The |
| 5814 | .Ic / |
| 5815 | and |
| 5816 | .Ic G |
| 5817 | commands move in the opposite direction to the |
| 5818 | .Ic j |
| 5819 | command. |
| 5820 | .It |
| 5821 | Commands which don't make sense in a single line editor are not available |
| 5822 | (e.g. screen movement commands and |
| 5823 | .Xr ex 1 Ns -style |
| 5824 | colon |
| 5825 | .Pq Ic \&: |
| 5826 | commands). |
| 5827 | .El |
| 5828 | .Pp |
| 5829 | Like |
| 5830 | .Xr vi 1 , |
| 5831 | there are two modes: |
| 5832 | .Dq insert |
| 5833 | mode and |
| 5834 | .Dq command |
| 5835 | mode. |
| 5836 | In insert mode, most characters are simply put in the buffer at the |
| 5837 | current cursor position as they are typed; however, some characters are |
| 5838 | treated specially. |
| 5839 | In particular, the following characters are taken from current |
| 5840 | .Xr tty 4 |
| 5841 | settings |
| 5842 | (see |
| 5843 | .Xr stty 1 ) |
| 5844 | and have their usual meaning (normal values are in parentheses): kill (\*(haU), |
| 5845 | erase (\*(ha?), werase (\*(haW), eof (\*(haD), intr (\*(haC), and quit (\*(ha\e). |
| 5846 | In addition to |
| 5847 | the above, the following characters are also treated specially in insert mode: |
| 5848 | .Bl -tag -width XJXXXXM |
| 5849 | .It \*(haE |
| 5850 | Command and file name enumeration (see below). |
| 5851 | .It \*(haF |
| 5852 | Command and file name completion (see below). |
| 5853 | If used twice in a row, the |
| 5854 | list of possible completions is displayed; if used a third time, the completion |
| 5855 | is undone. |
| 5856 | .It \*(haH |
| 5857 | Erases previous character. |
| 5858 | .It \*(haJ \*(Ba \*(haM |
| 5859 | End of line. |
| 5860 | The current line is read, parsed, and executed by the shell. |
| 5861 | .It \*(haV |
| 5862 | Literal next. |
| 5863 | The next character typed is not treated specially (can be used |
| 5864 | to insert the characters being described here). |
| 5865 | .It \*(haX |
| 5866 | Command and file name expansion (see below). |
| 5867 | .It Aq esc |
| 5868 | Puts the editor in command mode (see below). |
| 5869 | .It Aq tab |
| 5870 | Optional file name and command completion (see |
| 5871 | .Ic \*(haF |
| 5872 | above), enabled with |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5873 | .Ic set Fl o Ic vi\-tabcomplete . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5874 | .El |
| 5875 | .Pp |
| 5876 | In command mode, each character is interpreted as a command. |
| 5877 | Characters that |
| 5878 | don't correspond to commands, are illegal combinations of commands, or are |
| 5879 | commands that can't be carried out, all cause beeps. |
| 5880 | In the following command descriptions, an |
| 5881 | .Op Ar n |
| 5882 | indicates the command may be prefixed by a number (e.g.\& |
| 5883 | .Ic 10l |
| 5884 | moves right 10 characters); if no number prefix is used, |
| 5885 | .Ar n |
| 5886 | is assumed to be 1 unless otherwise specified. |
| 5887 | The term |
| 5888 | .Dq current position |
| 5889 | refers to the position between the cursor and the character preceding the |
| 5890 | cursor. |
| 5891 | A |
| 5892 | .Dq word |
| 5893 | is a sequence of letters, digits, and underscore characters or a sequence of |
| 5894 | non-letter, non-digit, non-underscore, and non-whitespace characters (e.g.\& |
| 5895 | .Dq ab2*&\*(ha |
| 5896 | contains two words) and a |
| 5897 | .Dq big-word |
| 5898 | is a sequence of non-whitespace characters. |
| 5899 | .Pp |
| 5900 | Special |
| 5901 | .Nm |
| 5902 | vi commands: |
| 5903 | .Pp |
| 5904 | The following commands are not in, or are different from, the normal vi file |
| 5905 | editor: |
| 5906 | .Bl -tag -width 10n |
| 5907 | .It Xo |
| 5908 | .Oo Ar n Oc Ns _ |
| 5909 | .Xc |
| 5910 | Insert a space followed by the |
| 5911 | .Ar n Ns th |
| 5912 | big-word from the last command in the history at the current position and enter |
| 5913 | insert mode; if |
| 5914 | .Ar n |
| 5915 | is not specified, the last word is inserted. |
| 5916 | .It # |
| 5917 | Insert the comment character |
| 5918 | .Pq Sq # |
| 5919 | at the start of the current line and return the line to the shell (equivalent |
| 5920 | to |
| 5921 | .Ic I#\*(haJ ) . |
| 5922 | .It Xo |
| 5923 | .Oo Ar n Oc Ns g |
| 5924 | .Xc |
| 5925 | Like |
| 5926 | .Ic G , |
| 5927 | except if |
| 5928 | .Ar n |
| 5929 | is not specified, it goes to the most recent remembered line. |
| 5930 | .It Xo |
| 5931 | .Oo Ar n Oc Ns v |
| 5932 | .Xc |
| 5933 | Edit line |
| 5934 | .Ar n |
| 5935 | using the |
| 5936 | .Xr vi 1 |
| 5937 | editor; if |
| 5938 | .Ar n |
| 5939 | is not specified, the current line is edited. |
| 5940 | The actual command executed is |
| 5941 | .Ic fc \-e ${VISUAL:\-${EDITOR:\-vi}} Ar n . |
| 5942 | .It * and \*(haX |
| 5943 | Command or file name expansion is applied to the current big-word (with an |
| 5944 | appended |
| 5945 | .Ql * |
| 5946 | if the word contains no file globbing characters) \*(en the big-word is replaced |
| 5947 | with the resulting words. |
| 5948 | If the current big-word is the first on the line |
| 5949 | or follows one of the characters |
| 5950 | .Ql \&; , |
| 5951 | .Ql \*(Ba , |
| 5952 | .Ql & , |
| 5953 | .Ql \&( , |
| 5954 | or |
| 5955 | .Ql \&) , |
| 5956 | and does not contain a slash |
| 5957 | .Pq Sq / , |
| 5958 | then command expansion is done; otherwise file name expansion is done. |
| 5959 | Command expansion will match the big-word against all aliases, functions, and |
| 5960 | built-in commands as well as any executable files found by searching the |
| 5961 | directories in the |
| 5962 | .Ev PATH |
| 5963 | parameter. |
| 5964 | File name expansion matches the big-word against the files in the |
| 5965 | current directory. |
| 5966 | After expansion, the cursor is placed just past the last |
| 5967 | word and the editor is in insert mode. |
| 5968 | .It Xo |
| 5969 | .Oo Ar n Oc Ns \e , |
| 5970 | .Oo Ar n Oc Ns \*(haF , |
| 5971 | .Oo Ar n Oc Ns Aq tab , |
| 5972 | .No and |
| 5973 | .Oo Ar n Oc Ns Aq esc |
| 5974 | .Xc |
| 5975 | Command/file name completion. |
| 5976 | Replace the current big-word with the |
| 5977 | longest unique match obtained after performing command and file name expansion. |
| 5978 | .Aq tab |
| 5979 | is only recognised if the |
| 5980 | .Ic vi\-tabcomplete |
| 5981 | option is set, while |
| 5982 | .Aq esc |
| 5983 | is only recognised if the |
| 5984 | .Ic vi\-esccomplete |
| 5985 | option is set (see |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 5986 | .Ic set Fl o ) . |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 5987 | If |
| 5988 | .Ar n |
| 5989 | is specified, the |
| 5990 | .Ar n Ns th |
| 5991 | possible completion is selected (as reported by the command/file name |
| 5992 | enumeration command). |
| 5993 | .It = and \*(haE |
| 5994 | Command/file name enumeration. |
| 5995 | List all the commands or files that match the current big-word. |
| 5996 | .It \*(haV |
| 5997 | Display the version of |
| 5998 | .Nm mksh . |
| 5999 | The current edit buffer is restored as soon as a key is pressed. |
| 6000 | The restoring keypress is ignored. |
| 6001 | .It @ Ns Ar c |
| 6002 | Macro expansion. |
| 6003 | Execute the commands found in the alias |
| 6004 | .Ar c . |
| 6005 | .El |
| 6006 | .Pp |
| 6007 | Intra-line movement commands: |
| 6008 | .Bl -tag -width Ds |
| 6009 | .It Xo |
| 6010 | .Oo Ar n Oc Ns h and |
| 6011 | .Oo Ar n Oc Ns \*(haH |
| 6012 | .Xc |
| 6013 | Move left |
| 6014 | .Ar n |
| 6015 | characters. |
| 6016 | .It Xo |
| 6017 | .Oo Ar n Oc Ns l and |
| 6018 | .Oo Ar n Oc Ns Aq space |
| 6019 | .Xc |
| 6020 | Move right |
| 6021 | .Ar n |
| 6022 | characters. |
| 6023 | .It 0 |
| 6024 | Move to column 0. |
| 6025 | .It \*(ha |
| 6026 | Move to the first non-whitespace character. |
| 6027 | .It Xo |
| 6028 | .Oo Ar n Oc Ns \*(Ba |
| 6029 | .Xc |
| 6030 | Move to column |
| 6031 | .Ar n . |
| 6032 | .It $ |
| 6033 | Move to the last character. |
| 6034 | .It Xo |
| 6035 | .Oo Ar n Oc Ns b |
| 6036 | .Xc |
| 6037 | Move back |
| 6038 | .Ar n |
| 6039 | words. |
| 6040 | .It Xo |
| 6041 | .Oo Ar n Oc Ns B |
| 6042 | .Xc |
| 6043 | Move back |
| 6044 | .Ar n |
| 6045 | big-words. |
| 6046 | .It Xo |
| 6047 | .Oo Ar n Oc Ns e |
| 6048 | .Xc |
| 6049 | Move forward to the end of the word, |
| 6050 | .Ar n |
| 6051 | times. |
| 6052 | .It Xo |
| 6053 | .Oo Ar n Oc Ns E |
| 6054 | .Xc |
| 6055 | Move forward to the end of the big-word, |
| 6056 | .Ar n |
| 6057 | times. |
| 6058 | .It Xo |
| 6059 | .Oo Ar n Oc Ns w |
| 6060 | .Xc |
| 6061 | Move forward |
| 6062 | .Ar n |
| 6063 | words. |
| 6064 | .It Xo |
| 6065 | .Oo Ar n Oc Ns W |
| 6066 | .Xc |
| 6067 | Move forward |
| 6068 | .Ar n |
| 6069 | big-words. |
| 6070 | .It % |
| 6071 | Find match. |
| 6072 | The editor looks forward for the nearest parenthesis, bracket, or |
| 6073 | brace and then moves the cursor to the matching parenthesis, bracket, or brace. |
| 6074 | .It Xo |
| 6075 | .Oo Ar n Oc Ns f Ns Ar c |
| 6076 | .Xc |
| 6077 | Move forward to the |
| 6078 | .Ar n Ns th |
| 6079 | occurrence of the character |
| 6080 | .Ar c . |
| 6081 | .It Xo |
| 6082 | .Oo Ar n Oc Ns F Ns Ar c |
| 6083 | .Xc |
| 6084 | Move backward to the |
| 6085 | .Ar n Ns th |
| 6086 | occurrence of the character |
| 6087 | .Ar c . |
| 6088 | .It Xo |
| 6089 | .Oo Ar n Oc Ns t Ns Ar c |
| 6090 | .Xc |
| 6091 | Move forward to just before the |
| 6092 | .Ar n Ns th |
| 6093 | occurrence of the character |
| 6094 | .Ar c . |
| 6095 | .It Xo |
| 6096 | .Oo Ar n Oc Ns T Ns Ar c |
| 6097 | .Xc |
| 6098 | Move backward to just before the |
| 6099 | .Ar n Ns th |
| 6100 | occurrence of the character |
| 6101 | .Ar c . |
| 6102 | .It Xo |
| 6103 | .Oo Ar n Oc Ns \&; |
| 6104 | .Xc |
| 6105 | Repeats the last |
| 6106 | .Ic f , F , t , |
| 6107 | or |
| 6108 | .Ic T |
| 6109 | command. |
| 6110 | .It Xo |
| 6111 | .Oo Ar n Oc Ns \&, |
| 6112 | .Xc |
| 6113 | Repeats the last |
| 6114 | .Ic f , F , t , |
| 6115 | or |
| 6116 | .Ic T |
| 6117 | command, but moves in the opposite direction. |
| 6118 | .El |
| 6119 | .Pp |
| 6120 | Inter-line movement commands: |
| 6121 | .Bl -tag -width Ds |
| 6122 | .It Xo |
| 6123 | .Oo Ar n Oc Ns j , |
| 6124 | .Oo Ar n Oc Ns + , |
| 6125 | .No and |
| 6126 | .Oo Ar n Oc Ns \*(haN |
| 6127 | .Xc |
| 6128 | Move to the |
| 6129 | .Ar n Ns th |
| 6130 | next line in the history. |
| 6131 | .It Xo |
| 6132 | .Oo Ar n Oc Ns k , |
| 6133 | .Oo Ar n Oc Ns \- , |
| 6134 | .No and |
| 6135 | .Oo Ar n Oc Ns \*(haP |
| 6136 | .Xc |
| 6137 | Move to the |
| 6138 | .Ar n Ns th |
| 6139 | previous line in the history. |
| 6140 | .It Xo |
| 6141 | .Oo Ar n Oc Ns G |
| 6142 | .Xc |
| 6143 | Move to line |
| 6144 | .Ar n |
| 6145 | in the history; if |
| 6146 | .Ar n |
| 6147 | is not specified, the number of the first remembered line is used. |
| 6148 | .It Xo |
| 6149 | .Oo Ar n Oc Ns g |
| 6150 | .Xc |
| 6151 | Like |
| 6152 | .Ic G , |
| 6153 | except if |
| 6154 | .Ar n |
| 6155 | is not specified, it goes to the most recent remembered line. |
| 6156 | .It Xo |
| 6157 | .Oo Ar n Oc Ns / Ns Ar string |
| 6158 | .Xc |
| 6159 | Search backward through the history for the |
| 6160 | .Ar n Ns th |
| 6161 | line containing |
| 6162 | .Ar string ; |
| 6163 | if |
| 6164 | .Ar string |
| 6165 | starts with |
| 6166 | .Ql \*(ha , |
| 6167 | the remainder of the string must appear at the start of the history line for |
| 6168 | it to match. |
| 6169 | .It Xo |
| 6170 | .Oo Ar n Oc Ns \&? Ns Ar string |
| 6171 | .Xc |
| 6172 | Same as |
| 6173 | .Ic / , |
| 6174 | except it searches forward through the history. |
| 6175 | .It Xo |
| 6176 | .Oo Ar n Oc Ns n |
| 6177 | .Xc |
| 6178 | Search for the |
| 6179 | .Ar n Ns th |
| 6180 | occurrence of the last search string; |
| 6181 | the direction of the search is the same as the last search. |
| 6182 | .It Xo |
| 6183 | .Oo Ar n Oc Ns N |
| 6184 | .Xc |
| 6185 | Search for the |
| 6186 | .Ar n Ns th |
| 6187 | occurrence of the last search string; |
| 6188 | the direction of the search is the opposite of the last search. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6189 | .It Ar ANSI-CurUp , PC-PgUp |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6190 | Take the characters from the beginning of the line to the current |
| 6191 | cursor position as search string and do a backwards history search |
| 6192 | for lines beginning with this string; keep the cursor position. |
| 6193 | This works only in insert mode and keeps it enabled. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6194 | .El |
| 6195 | .Pp |
| 6196 | Edit commands |
| 6197 | .Bl -tag -width Ds |
| 6198 | .It Xo |
| 6199 | .Oo Ar n Oc Ns a |
| 6200 | .Xc |
| 6201 | Append text |
| 6202 | .Ar n |
| 6203 | times; goes into insert mode just after the current position. |
| 6204 | The append is |
| 6205 | only replicated if command mode is re-entered i.e.\& |
| 6206 | .Aq esc |
| 6207 | is used. |
| 6208 | .It Xo |
| 6209 | .Oo Ar n Oc Ns A |
| 6210 | .Xc |
| 6211 | Same as |
| 6212 | .Ic a , |
| 6213 | except it appends at the end of the line. |
| 6214 | .It Xo |
| 6215 | .Oo Ar n Oc Ns i |
| 6216 | .Xc |
| 6217 | Insert text |
| 6218 | .Ar n |
| 6219 | times; goes into insert mode at the current position. |
| 6220 | The insertion is only |
| 6221 | replicated if command mode is re-entered i.e.\& |
| 6222 | .Aq esc |
| 6223 | is used. |
| 6224 | .It Xo |
| 6225 | .Oo Ar n Oc Ns I |
| 6226 | .Xc |
| 6227 | Same as |
| 6228 | .Ic i , |
| 6229 | except the insertion is done just before the first non-blank character. |
| 6230 | .It Xo |
| 6231 | .Oo Ar n Oc Ns s |
| 6232 | .Xc |
| 6233 | Substitute the next |
| 6234 | .Ar n |
| 6235 | characters (i.e. delete the characters and go into insert mode). |
| 6236 | .It S |
| 6237 | Substitute whole line. |
| 6238 | All characters from the first non-blank character to the |
| 6239 | end of the line are deleted and insert mode is entered. |
| 6240 | .It Xo |
| 6241 | .Oo Ar n Oc Ns c Ns Ar move-cmd |
| 6242 | .Xc |
| 6243 | Change from the current position to the position resulting from |
| 6244 | .Ar n move-cmd Ns s |
| 6245 | (i.e. delete the indicated region and go into insert mode); if |
| 6246 | .Ar move-cmd |
| 6247 | is |
| 6248 | .Ic c , |
| 6249 | the line starting from the first non-blank character is changed. |
| 6250 | .It C |
| 6251 | Change from the current position to the end of the line (i.e. delete to the |
| 6252 | end of the line and go into insert mode). |
| 6253 | .It Xo |
| 6254 | .Oo Ar n Oc Ns x |
| 6255 | .Xc |
| 6256 | Delete the next |
| 6257 | .Ar n |
| 6258 | characters. |
| 6259 | .It Xo |
| 6260 | .Oo Ar n Oc Ns X |
| 6261 | .Xc |
| 6262 | Delete the previous |
| 6263 | .Ar n |
| 6264 | characters. |
| 6265 | .It D |
| 6266 | Delete to the end of the line. |
| 6267 | .It Xo |
| 6268 | .Oo Ar n Oc Ns d Ns Ar move-cmd |
| 6269 | .Xc |
| 6270 | Delete from the current position to the position resulting from |
| 6271 | .Ar n move-cmd Ns s ; |
| 6272 | .Ar move-cmd |
| 6273 | is a movement command (see above) or |
| 6274 | .Ic d , |
| 6275 | in which case the current line is deleted. |
| 6276 | .It Xo |
| 6277 | .Oo Ar n Oc Ns r Ns Ar c |
| 6278 | .Xc |
| 6279 | Replace the next |
| 6280 | .Ar n |
| 6281 | characters with the character |
| 6282 | .Ar c . |
| 6283 | .It Xo |
| 6284 | .Oo Ar n Oc Ns R |
| 6285 | .Xc |
| 6286 | Replace. |
| 6287 | Enter insert mode but overwrite existing characters instead of |
| 6288 | inserting before existing characters. |
| 6289 | The replacement is repeated |
| 6290 | .Ar n |
| 6291 | times. |
| 6292 | .It Xo |
| 6293 | .Oo Ar n Oc Ns \*(TI |
| 6294 | .Xc |
| 6295 | Change the case of the next |
| 6296 | .Ar n |
| 6297 | characters. |
| 6298 | .It Xo |
| 6299 | .Oo Ar n Oc Ns y Ns Ar move-cmd |
| 6300 | .Xc |
| 6301 | Yank from the current position to the position resulting from |
| 6302 | .Ar n move-cmd Ns s |
| 6303 | into the yank buffer; if |
| 6304 | .Ar move-cmd |
| 6305 | is |
| 6306 | .Ic y , |
| 6307 | the whole line is yanked. |
| 6308 | .It Y |
| 6309 | Yank from the current position to the end of the line. |
| 6310 | .It Xo |
| 6311 | .Oo Ar n Oc Ns p |
| 6312 | .Xc |
| 6313 | Paste the contents of the yank buffer just after the current position, |
| 6314 | .Ar n |
| 6315 | times. |
| 6316 | .It Xo |
| 6317 | .Oo Ar n Oc Ns P |
| 6318 | .Xc |
| 6319 | Same as |
| 6320 | .Ic p , |
| 6321 | except the buffer is pasted at the current position. |
| 6322 | .El |
| 6323 | .Pp |
| 6324 | Miscellaneous vi commands |
| 6325 | .Bl -tag -width Ds |
| 6326 | .It \*(haJ and \*(haM |
| 6327 | The current line is read, parsed, and executed by the shell. |
| 6328 | .It \*(haL and \*(haR |
| 6329 | Redraw the current line. |
| 6330 | .It Xo |
| 6331 | .Oo Ar n Oc Ns \&. |
| 6332 | .Xc |
| 6333 | Redo the last edit command |
| 6334 | .Ar n |
| 6335 | times. |
| 6336 | .It u |
| 6337 | Undo the last edit command. |
| 6338 | .It U |
| 6339 | Undo all changes that have been made to the current line. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6340 | .It PC Home, End, Del, and cursor keys |
| 6341 | They move as expected, both in insert and command mode. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6342 | .It Ar intr No and Ar quit |
| 6343 | The interrupt and quit terminal characters cause the current line to be |
| 6344 | deleted and a new prompt to be printed. |
| 6345 | .El |
| 6346 | .Sh FILES |
| 6347 | .Bl -tag -width XetcXsuid_profile -compact |
| 6348 | .It Pa \*(TI/.mkshrc |
| 6349 | User mkshrc profile (non-privileged interactive shells); see |
| 6350 | .Sx Startup files. |
| 6351 | The location can be changed at compile time (for embedded systems); |
| 6352 | AOSP Android builds use |
| 6353 | .Pa /system/etc/mkshrc . |
| 6354 | .It Pa \*(TI/.profile |
| 6355 | User profile (non-privileged login shells); see |
| 6356 | .Sx Startup files |
| 6357 | near the top of this manual. |
| 6358 | .It Pa /etc/profile |
| 6359 | System profile (login shells); see |
| 6360 | .Sx Startup files. |
| 6361 | .It Pa /etc/shells |
| 6362 | Shell database. |
| 6363 | .It Pa /etc/suid_profile |
| 6364 | Suid profile (privileged shells); see |
| 6365 | .Sx Startup files. |
| 6366 | .El |
| 6367 | .Pp |
| 6368 | Note: On Android, |
| 6369 | .Pa /system/etc/ |
| 6370 | contains the system and suid profile. |
| 6371 | .Sh SEE ALSO |
| 6372 | .Xr awk 1 , |
| 6373 | .Xr cat 1 , |
| 6374 | .Xr ed 1 , |
| 6375 | .Xr getopt 1 , |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6376 | .Xr lksh 1 , |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6377 | .Xr sed 1 , |
| 6378 | .Xr sh 1 , |
| 6379 | .Xr stty 1 , |
| 6380 | .Xr dup 2 , |
| 6381 | .Xr execve 2 , |
| 6382 | .Xr getgid 2 , |
| 6383 | .Xr getuid 2 , |
| 6384 | .Xr mknod 2 , |
| 6385 | .Xr mkfifo 2 , |
| 6386 | .Xr open 2 , |
| 6387 | .Xr pipe 2 , |
| 6388 | .Xr rename 2 , |
| 6389 | .Xr wait 2 , |
| 6390 | .Xr getopt 3 , |
| 6391 | .Xr nl_langinfo 3 , |
| 6392 | .Xr setlocale 3 , |
| 6393 | .Xr signal 3 , |
| 6394 | .Xr system 3 , |
| 6395 | .Xr tty 4 , |
| 6396 | .Xr shells 5 , |
| 6397 | .Xr environ 7 , |
| 6398 | .Xr script 7 , |
| 6399 | .Xr utf\-8 7 , |
| 6400 | .Xr mknod 8 |
| 6401 | .Pp |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 6402 | .Pa https://www.mirbsd.org/ksh\-chan.htm |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6403 | .Rs |
| 6404 | .%A Morris Bolsky |
| 6405 | .%B "The KornShell Command and Programming Language" |
| 6406 | .%D 1989 |
| 6407 | .%I "Prentice Hall PTR" |
| 6408 | .%P "xvi\ +\ 356 pages" |
| 6409 | .%O "ISBN 978\-0\-13\-516972\-8 (0\-13\-516972\-0)" |
| 6410 | .Re |
| 6411 | .Rs |
| 6412 | .%A Morris I. Bolsky |
| 6413 | .%A David G. Korn |
| 6414 | .%B "The New KornShell Command and Programming Language (2nd Edition)" |
| 6415 | .%D 1995 |
| 6416 | .%I "Prentice Hall PTR" |
| 6417 | .%P "xvi\ +\ 400 pages" |
| 6418 | .%O "ISBN 978\-0\-13\-182700\-4 (0\-13\-182700\-6)" |
| 6419 | .Re |
| 6420 | .Rs |
| 6421 | .%A Stephen G. Kochan |
| 6422 | .%A Patrick H. Wood |
| 6423 | .%B "\\*(tNUNIX\\*(sP Shell Programming" |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6424 | .%V "3rd Edition" |
| 6425 | .%D 2003 |
| 6426 | .%I "Sams" |
| 6427 | .%P "xiii\ +\ 437 pages" |
| 6428 | .%O "ISBN 978\-0\-672\-32490\-1 (0\-672\-32490\-3)" |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6429 | .Re |
| 6430 | .Rs |
| 6431 | .%A "IEEE Inc." |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6432 | .%T "\\*(tNIEEE\\*(sP Standard for Information Technology \*(en Portable Operating System Interface (POSIX)" |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6433 | .%V "Part 2: Shell and Utilities" |
| 6434 | .%D 1993 |
| 6435 | .%I "IEEE Press" |
| 6436 | .%P "xvii\ +\ 1195 pages" |
| 6437 | .%O "ISBN 978\-1\-55937\-255\-8 (1\-55937\-255\-9)" |
| 6438 | .Re |
| 6439 | .Rs |
| 6440 | .%A Bill Rosenblatt |
| 6441 | .%B "Learning the Korn Shell" |
| 6442 | .%D 1993 |
| 6443 | .%I "O'Reilly" |
| 6444 | .%P "360 pages" |
| 6445 | .%O "ISBN 978\-1\-56592\-054\-5 (1\-56592\-054\-6)" |
| 6446 | .Re |
| 6447 | .Rs |
| 6448 | .%A Bill Rosenblatt |
| 6449 | .%A Arnold Robbins |
| 6450 | .%B "Learning the Korn Shell, Second Edition" |
| 6451 | .%D 2002 |
| 6452 | .%I "O'Reilly" |
| 6453 | .%P "432 pages" |
| 6454 | .%O "ISBN 978\-0\-596\-00195\-7 (0\-596\-00195\-9)" |
| 6455 | .Re |
| 6456 | .Rs |
| 6457 | .%A Barry Rosenberg |
| 6458 | .%B "KornShell Programming Tutorial" |
| 6459 | .%D 1991 |
| 6460 | .%I "Addison-Wesley Professional" |
| 6461 | .%P "xxi\ +\ 324 pages" |
| 6462 | .%O "ISBN 978\-0\-201\-56324\-5 (0\-201\-56324\-X)" |
| 6463 | .Re |
| 6464 | .Sh AUTHORS |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6465 | .An -nosplit |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6466 | .Nm "The MirBSD Korn Shell" |
| 6467 | is developed by |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6468 | .An mirabilos Aq Mt m@mirbsd.org |
| 6469 | as part of The MirOS Project. |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6470 | This shell is based on the public domain 7th edition Bourne shell clone by |
| 6471 | .An Charles Forsyth , |
| 6472 | who kindly agreed to, in countries where the Public Domain status of the work |
| 6473 | may not be valid, grant a copyright licence to the general public to deal in |
| 6474 | the work without restriction and permission to sublicence derivates under the |
| 6475 | terms of any (OSI approved) Open Source licence, |
| 6476 | and parts of the BRL shell by |
| 6477 | .An Doug A. Gwyn , |
| 6478 | .An Doug Kingston , |
| 6479 | .An Ron Natalie , |
| 6480 | .An Arnold Robbins , |
| 6481 | .An Lou Salkind , |
| 6482 | and others. |
| 6483 | The first release of |
| 6484 | .Nm pdksh |
| 6485 | was created by |
| 6486 | .An Eric Gisin , |
| 6487 | and it was subsequently maintained by |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6488 | .An John R. MacMillan , |
| 6489 | .An Simon J. Gerraty , |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6490 | and |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6491 | .An Michael Rendell . |
Elliott Hughes | 737fdce | 2014-08-07 12:59:26 -0700 | [diff] [blame] | 6492 | The effort of several projects, such as Debian and OpenBSD, and other |
| 6493 | contributors including our users, to improve the shell is appreciated. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6494 | See the documentation, CVS, and web site for details. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6495 | .Pp |
| 6496 | The BSD daemon is Copyright \(co Marshall Kirk McKusick. |
| 6497 | The complete legalese is at: |
| 6498 | .Pa https://www.mirbsd.org/TaC\-mksh.txt |
| 6499 | .\" |
| 6500 | .\" This boils down to: feel free to use mksh.ico as application icon |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6501 | .\" or shortcut for mksh or mksh/Win32 or OS/2; distro patches are ok |
| 6502 | .\" (but we request they amend $KSH_VERSION when modifying mksh). |
| 6503 | .\" Authors are Marshall Kirk McKusick (UCB), Rick Collette (ekkoBSD), |
| 6504 | .\" mirabilos, Benny Siegert (MirBSD), Michael Langguth (mksh/Win32), |
| 6505 | .\" KO Myung-Hun (mksh for OS/2). |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6506 | .\" |
| 6507 | .\" As far as MirBSD is concerned, the files themselves are free |
| 6508 | .\" to modification and distribution under BSD/MirOS Licence, the |
| 6509 | .\" restriction on use stems only from trademark law's requirement |
| 6510 | .\" to protect it or lose it, which McKusick almost did. |
| 6511 | .\" |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6512 | .Sh CAVEATS |
| 6513 | .Nm |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6514 | has a different scope model from |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6515 | .At |
| 6516 | .Nm ksh , |
| 6517 | which leads to subtile differences in semantics for identical builtins. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6518 | This can cause issues with a |
| 6519 | .Ic nameref |
| 6520 | to suddenly point to a local variable by accident; fixing this is hard. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6521 | .Pp |
| 6522 | The parts of a pipeline, like below, are executed in subshells. |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6523 | Thus, variable assignments inside them are not visible in the |
| 6524 | surrounding execution environment. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6525 | Use co-processes instead. |
| 6526 | .Bd -literal -offset indent |
| 6527 | foo \*(Ba bar \*(Ba read baz # will not change $baz |
| 6528 | foo \*(Ba bar \*(Ba& read \-p baz # will, however, do so |
| 6529 | .Ed |
Thorsten Glaser | 811a575 | 2013-07-25 14:24:45 +0000 | [diff] [blame] | 6530 | .Pp |
| 6531 | .Nm mksh |
| 6532 | provides a consistent set of 32-bit integer arithmetics, both signed |
Elliott Hughes | 56b517d | 2014-10-06 11:30:44 -0700 | [diff] [blame] | 6533 | and unsigned, with defined wraparound and sign of the result of a |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6534 | remainder operation, even (defying POSIX) on 36-bit and 64-bit systems. |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 6535 | .Pp |
| 6536 | .Nm mksh |
| 6537 | provides a consistent, clear interface normally. |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6538 | This may deviate from POSIX in historic or opinionated places. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6539 | .Ic set Fl o Ic posix |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6540 | (see |
| 6541 | .Sx POSIX mode |
| 6542 | for details) |
| 6543 | will cause the shell to behave more conformant. |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 6544 | .Pp |
| 6545 | For the purpose of |
| 6546 | .Tn POSIX , |
| 6547 | .Nm mksh |
| 6548 | supports only the |
| 6549 | .Dq C |
| 6550 | locale. |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6551 | .Nm mksh Ns 's |
| 6552 | .Ic utf8\-mode |
| 6553 | only supports the Unicode BMP (Basic Multilingual Plane) and maps |
| 6554 | raw octets into the U+EF80..U+EFFF wide character range; compare |
| 6555 | .Sx Arithmetic expressions . |
| 6556 | The following |
| 6557 | .Tn POSIX |
| 6558 | .Nm sh |
| 6559 | code toggles the |
| 6560 | .Ic utf8\-mode |
| 6561 | option dependent on the current |
| 6562 | .Tn POSIX |
| 6563 | locale for mksh to allow using the UTF-8 mode, within the constraints |
| 6564 | outlined above, in code portable across various shell implementations: |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 6565 | .Bd -literal -offset indent |
| 6566 | case ${KSH_VERSION:\-} in |
| 6567 | *MIRBSD\ KSH*\*(Ba*LEGACY\ KSH*) |
| 6568 | case ${LC_ALL:\-${LC_CTYPE:\-${LANG:\-}}} in |
| 6569 | *[Uu][Tt][Ff]8*\*(Ba*[Uu][Tt][Ff]\-8*) set \-U ;; |
| 6570 | *) set +U ;; |
| 6571 | esac ;; |
| 6572 | esac |
| 6573 | .Ed |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6574 | In near future, (Unicode) locale tracking will be implemented though. |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6575 | .Sh BUGS |
| 6576 | Suspending (using \*(haZ) pipelines like the one below will only suspend |
| 6577 | the currently running part of the pipeline; in this example, |
| 6578 | .Dq fubar |
| 6579 | is immediately printed on suspension (but not later after an |
| 6580 | .Ic fg ) . |
| 6581 | .Bd -literal -offset indent |
| 6582 | $ /bin/sleep 666 && echo fubar |
| 6583 | .Ed |
| 6584 | .Pp |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 6585 | The truncation process involved when changing |
| 6586 | .Ev HISTFILE |
| 6587 | does not free old history entries (leaks memory) and leaks |
| 6588 | old entries into the new history if their line numbers are |
| 6589 | not overwritten by same-numer entries from the persistent |
| 6590 | history file; truncating the on-disc file to |
| 6591 | .Ev HISTSIZE |
| 6592 | lines has always been broken and prone to history file corruption |
| 6593 | when multiple shells are accessing the file; the rollover process |
| 6594 | for the in-memory portion of the history is slow, should use |
| 6595 | .Xr memmove 3 . |
| 6596 | .Pp |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6597 | Handling of backslash plus double-quote inside the (deprecated) |
| 6598 | .Pf \` Ns Ar command Ns \` |
| 6599 | form of command substitution when the substitution itself is |
| 6600 | also inside double quotes currently deliberately violates |
| 6601 | .Tn POSIX |
| 6602 | even in |
| 6603 | .Fl o Ic posix |
| 6604 | mode until Austin group bug 1015 has been resolved either way, |
| 6605 | as the current wording of the standard prohibits the current |
| 6606 | and historic practice of several shells which several scripts |
| 6607 | (admittedly wrongly) depend on. |
| 6608 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6609 | This document attempts to describe |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6610 | .Nm mksh\ R52b |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6611 | and up, |
Elliott Hughes | b27ce95 | 2015-04-21 13:39:18 -0700 | [diff] [blame] | 6612 | .\" with vendor patches from insert-your-name-here, |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6613 | compiled without any options impacting functionality, such as |
| 6614 | .Dv MKSH_SMALL , |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 6615 | when not called as |
| 6616 | .Pa /bin/sh |
| 6617 | which, on some systems only, enables |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6618 | .Ic set Fl o Ic posix |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 6619 | or |
Elliott Hughes | 96b4363 | 2015-07-17 11:39:41 -0700 | [diff] [blame] | 6620 | .Ic set Fl o Ic sh |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 6621 | automatically (whose behaviour differs across targets), |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6622 | for an operating environment supporting all of its advanced needs. |
Elliott Hughes | 5001206 | 2015-03-10 22:22:24 -0700 | [diff] [blame] | 6623 | .Pp |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6624 | Please report bugs in |
| 6625 | .Nm |
| 6626 | to the |
| 6627 | .Mx |
| 6628 | mailing list at |
Elliott Hughes | fc0307d | 2016-02-02 15:26:47 -0800 | [diff] [blame] | 6629 | .Aq Mt miros\-mksh@mirbsd.org |
Geremy Condra | 03ebf06 | 2011-10-12 18:17:24 -0700 | [diff] [blame] | 6630 | or in the |
| 6631 | .Li \&#\&!/bin/mksh |
| 6632 | .Pq or Li \&#ksh |
| 6633 | IRC channel at |
Thorsten Glaser | c2dc5de | 2013-02-18 23:02:51 +0000 | [diff] [blame] | 6634 | .Pa irc.freenode.net |
| 6635 | .Pq Port 6697 SSL, 6667 unencrypted , |
| 6636 | or at: |
| 6637 | .Pa https://launchpad.net/mksh |