1 .\" $MirOS: src/bin/mksh/mksh.1,v 1.420 2016/11/11 23:31:36 tg Exp $
2 .\" $OpenBSD: ksh.1,v 1.160 2015/07/04 13:27:04 feinerer Exp $
4 .\" Copyright © 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
5 .\" 2010, 2011, 2012, 2013, 2014, 2015, 2016
6 .\" mirabilos <m@mirbsd.org>
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.
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.
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
31 .\" * <>| are problematic, so redefine and use \*(Lt\*(Gt\*(Ba
32 .\" Also make sure to use \& *before* a punctuation char that is to not
33 .\" be interpreted as punctuation, and especially with two-letter words
34 .\" but also (after) a period that does not end a sentence (“e.g.\&”).
35 .\" The section after the "doc" macropackage has been loaded contains
36 .\" additional code to convene between the UCB mdoc macropackage (and
37 .\" its variant as BSD mdoc in groff) and the GNU mdoc macropackage.
40 . if
\ 1\*[.T]
\ 1ascii
\ 1 .tr \-\N'45'
41 . if
\ 1\*[.T]
\ 1latin1
\ 1 .tr \-\N'45'
42 . if
\ 1\*[.T]
\ 1utf8
\ 1 .tr \-\N'45'
49 . if
\ 1\*[.T]
\ 1utf8
\ 1 .ds sL `
50 . if
\ 1\*[.T]
\ 1ps
\ 1 .ds sL `
51 . if
\ 1\*[.T]
\ 1utf8
\ 1 .ds sR '
52 . if
\ 1\*[.T]
\ 1ps
\ 1 .ds sR '
65 .\" Implement .Dd with the Mdocdate RCS keyword
69 .ie
\a\\$1
\a$Mdocdate:
\a \{\
72 .el .xD \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8
75 .\" .Dd must come before definition of .Mx, because when called
76 .\" with -mandoc, it might implement .Mx itself, but we want to
77 .\" use our own definition. And .Dd must come *first*, always.
79 .Dd $Mdocdate: November 11 2016 $
81 .\" Check which macro package we use, and do other -mdoc setup.
84 . if
\ 1\*[.T]
\ 1utf8
\ 1 .tr \[la]\*(Lt
85 . if
\ 1\*[.T]
\ 1utf8
\ 1 .tr \[ra]\*(Gt
86 . ie d volume-ds-1 .ds tT gnu
91 .\" Implement .Mx (MirBSD)
97 . nr curr-size \n[.ps]
98 . ds str-Mx \f[\n[curr-font]]\s[\n[curr-size]u]
99 . ds str-Mx1 \*[Tn-font-size]\%MirOS\*[str-Mx]
100 . if !\n[arg-limit] \
105 . if (\n[arg-limit] > \n[arg-ptr]) \{\
107 . ie (\n[type\n[arg-ptr]] == 2) \
108 . as str-Mx1 \~\*[arg\n[arg-ptr]]
112 . ds arg\n[arg-ptr] "\*[str-Mx1]
113 . nr type\n[arg-ptr] 2
114 . ds space\n[arg-ptr] "\*[space]
115 . nr num-args (\n[arg-limit] - \n[arg-ptr])
116 . nr arg-limit \n[arg-ptr]
123 . ds tN \*[Tn-font-size]
129 . ds aa \&\f\\n(cF\s\\n(cZ
131 . ie \\n(.$==0 \&MirOS\\*(aa
132 . el .aV \\$1 \\$2 \\$3 \\$4 \\$5 \\$6 \\$7 \\$8 \\$9
134 . if \\n(aC>\\n(aP \{\
136 . ie \\n(C\\n(aP==2 \{\
137 . as b1 \&MirOS\ #\&\\*(A\\n(aP\\*(aa
138 . ie \\n(aC>\\n(aP \{\
145 . as b1 \&MirOS\\*(aa
157 .Nd MirBSD Korn shell
161 .Op Fl +abCefhiklmnprUuvXx
163 .Fl T Oo Ar \&! Oc Ns Ar tty
169 .Fl c Ar string \*(Ba
179 is a command interpreter intended for both interactive and shell
181 Its command language is a superset of the
183 shell language and largely compatible to the original Korn shell.
184 At times, this manual page may give scripting advice; while it
185 sometimes does take portable shell scripting or various standards
186 into account all information is first and foremost presented with
188 in mind and should be taken as such.
189 .Ss I'm an Android user, so what's mksh?
193 shell / command interpreter, similar to
197 which has been included with
198 .Tn Android Open Source Project
200 Basically, it's a program that runs in a terminal (console window),
201 takes user input and runs commands or scripts, which it can also
202 be asked to do by other programs, even in the background.
203 Any privilege pop-ups you might be encountering are thus not
205 issues but questions by some other program utilising it.
207 Most builtins can be called directly, for example if a link points from its
208 name to the shell; not all make sense, have been tested or work at all though.
210 The options are as follows:
211 .Bl -tag -width XcXstring
214 will execute the command(s) contained in
218 A shell that reads commands from standard input is
221 option is used or if both standard input and standard error are attached
224 An interactive shell has job control enabled, ignores the
229 signals, and prints prompts before reading input (see the
234 It also processes the
239 For non-interactive shells, the
241 option is on by default (see the
246 If the basename the shell is called with (i.e. argv[0])
249 or if this option is used,
250 the shell is assumed to be a login shell; see
257 if the real user ID or group ID does not match the
258 effective user ID or group ID (see
262 Clearing the privileged option causes the shell to set
263 its effective user ID (group ID) to its real user ID (group ID).
264 For further implications, see
266 If the shell is privileged and this flag is not explicitly set, the
268 option is cleared automatically after processing the startup files.
275 The following restrictions come into effect after the shell processes any
292 parameters cannot be changed.
294 Command names can't be specified with absolute or relative paths.
298 option of the built-in command
302 Redirections that create files can't be used (i.e.\&
306 .Dq Li \*(Lt\*(Gt ) .
309 The shell reads commands from standard input; all non-option arguments
310 are positional parameters.
319 .Pa /dev/ttyC Ns Ar name
321 .Pa /dev/tty Ns Ar name
322 are attempted in order.
325 begins with an exclamation mark
327 this is done in a subshell and returns immediately.
332 detach from controlling terminal (daemonise) instead.
335 In addition to the above, the options described in the
337 built-in command can also be used on the command line:
339 .Op Fl +abCefhkmnuvXx
342 can be used for single letter or long options, respectively.
348 option is specified, the first non-option argument specifies the name
349 of a file the shell reads commands from.
350 If there are no non-option
351 arguments, the shell reads commands from the standard input.
352 The name of the shell (i.e. the contents of $0)
353 is determined as follows: if the
355 option is used and there is a non-option argument, it is used as the name;
356 if commands are being read from a file, the file is used as the name;
357 otherwise, the basename the shell was called with (i.e. argv[0]) is used.
359 The exit status of the shell is 127 if the command file specified on the
360 command line could not be opened, or non-zero if a fatal syntax error
361 occurred during the execution of a script.
362 In the absence of fatal errors,
363 the exit status is that of the last command executed, or zero if no
366 For the actual location of these files, see
368 A login shell processes the system profile first.
369 A privileged shell then processes the suid profile.
370 A non-privileged login shell processes the user profile next.
371 A non-privileged interactive shell checks the value of the
373 parameter after subjecting it to parameter, command, arithmetic and tilde
375 substitution; if unset or empty, the user mkshrc profile is processed;
376 otherwise, if a file whose name is the substitution result exists,
377 it is processed; non-existence is silently ignored.
378 A privileged shell then drops privileges if neither was the
380 option given on the command line nor set during execution of the startup files.
382 The shell begins parsing its input by removing any backslash-newline
383 combinations, then breaking it into
385 Words (which are sequences of characters) are delimited by unquoted whitespace
386 characters (space, tab and newline) or meta-characters
397 Aside from delimiting words, spaces and tabs are ignored, while newlines
398 usually delimit commands.
399 The meta-characters are used in building the following
404 .Dq Li \*(Lt\*(Lt\*(Lt ,
409 etc. are used to specify redirections (see
410 .Sx Input/output redirection
413 is used to create pipelines;
415 is used to create co-processes (see
419 is used to separate commands;
421 is used to create asynchronous pipelines;
425 are used to specify conditional execution;
434 is used in arithmetic expressions;
437 is used to create subshells.
439 Whitespace and meta-characters can be quoted individually using a backslash
441 or in groups using double
446 Note that the following characters are also treated specially by the
447 shell and must be quoted if they are to represent themselves:
461 The first three of these are the above mentioned quoting characters (see
465 if used at the beginning of a word, introduces a comment \*(en everything after
468 up to the nearest newline is ignored;
470 is used to introduce parameter, command and arithmetic substitutions (see
474 introduces an old-style command substitution (see
478 begins a directory expansion (see
494 are used in file name generation (see
495 .Sx File name patterns
498 As words and tokens are parsed, the shell builds commands, of which there
500 .Em simple-commands ,
501 typically programmes that are executed, and
502 .Em compound-commands ,
507 statements, grouping constructs and function definitions.
509 A simple-command consists of some combination of parameter assignments
513 input/output redirections (see
514 .Sx Input/output redirections
516 and command words; the only restriction is that parameter assignments come
517 before any command words.
518 The command words, if any, define the command
519 that is to be executed and its arguments.
520 The command may be a shell built-in command, a function
521 or an external command
522 (i.e. a separate executable file that is located using the
525 .Sx Command execution
527 Note that all command constructs have an exit status: for external commands,
528 this is related to the status returned by
530 (if the command could not be found, the exit status is 127; if it could not
531 be executed, the exit status is 126); the exit status of other command
532 constructs (built-in commands, functions, compound-commands, pipelines, lists,
533 etc.) are all well-defined and are described where the construct is
535 The exit status of a command consisting only of parameter
536 assignments is that of the last command substitution performed during the
537 parameter assignment or 0 if there were no command substitutions.
539 Commands can be chained together using the
541 token to form pipelines, in which the standard output of each command but the
544 to the standard input of the following command.
545 The exit status of a pipeline is that of its last command, unless the
547 option is set (see there).
548 All commands of a pipeline are executed in separate subshells;
549 this is allowed by POSIX but differs from both variants of
552 where all but the last command were executed in subshells; see the
554 builtin's description for implications and workarounds.
555 A pipeline may be prefixed by the
557 reserved word which causes the exit status of the pipeline to be logically
558 complemented: if the original status was 0, the complemented status will be 1;
559 if the original status was not 0, the complemented status will be 0.
562 of commands can be created by separating pipelines by any of the following
570 The first two are for conditional execution:
571 .Dq Ar cmd1 No && Ar cmd2
574 only if the exit status of
578 is the opposite \*(en
580 is executed only if the exit status of
586 have equal precedence which is higher than that of
591 which also have equal precedence.
597 .Qq left-associative .
598 For example, both of these commands will print only
600 .Bd -literal -offset indent
601 $ false && echo foo \*(Ba\*(Ba echo bar
602 $ true \*(Ba\*(Ba echo foo && echo bar
607 token causes the preceding command to be executed asynchronously; that is,
608 the shell starts the command but does not wait for it to complete (the shell
609 does keep track of the status of asynchronous commands; see
612 When an asynchronous command is started when job control is disabled
613 (i.e. in most scripts), the command is started with signals
617 ignored and with input redirected from
619 (however, redirections specified in the asynchronous command have precedence).
622 operator starts a co-process which is a special kind of asynchronous process
626 Note that a command must follow the
630 operators, while it need not follow
635 The exit status of a list is that of the last command executed, with the
636 exception of asynchronous lists, for which the exit status is 0.
638 Compound commands are created using the following reserved words.
640 are only recognised if they are unquoted and if they are used as the first
641 word of a command (i.e. they can't be preceded by parameter assignments or
643 .Bd -literal -offset indent
644 case else function then ! (
645 do esac if time [[ ((
647 elif for select while }
650 In the following compound command descriptions, command lists (denoted as
652 that are followed by reserved words must end with a semicolon, a newline or
653 a (syntactically correct) reserved word.
654 For example, the following are all valid:
655 .Bd -literal -offset indent
656 $ { echo foo; echo bar; }
657 $ { echo foo; echo bar\*(Ltnewline\*(Gt}
658 $ { { echo foo; echo bar; } }
663 .Dl $ { echo foo; echo bar }
669 There is no implicit way to pass environment changes from a
670 subshell back to its parent.
674 is executed, but not in a subshell.
679 are reserved words, not meta-characters.
680 .It Xo case Ar word No in
691 statement attempts to match
697 associated with the first successfully matched pattern is executed.
700 statements are the same as those used for file name patterns except that the
701 restrictions regarding
706 Note that any unquoted space before and after a pattern is
707 stripped; any space within a pattern must be quoted.
708 Both the word and the
709 patterns are subject to parameter, command and arithmetic substitution, as
710 well as tilde substitution.
712 For historical reasons, open and close braces may be used instead of
717 .Ic case $foo { *) echo bar ;; } .
724 Terminate after the list.
726 Fall through into the next list.
728 Evaluate the remaining pattern-list tuples.
733 statement is that of the executed
737 is executed, the exit status is zero.
739 .Oo in Ar word No ... Oc ;
740 .No do Ar list ; No done
744 in the specified word list, the parameter
746 is set to the word and
751 is not used to specify a word list, the positional parameters ($1, $2,
752 etc.) are used instead.
753 For historical reasons, open and close braces may be used instead of
758 .Ic for i; { echo $i; } .
761 statement is the last exit status of
765 is never executed, the exit status is zero.
769 .No then Ar list ; Oc
771 .Oo else Ar list ; Oc
774 If the exit status of the first
778 is executed; otherwise, the
782 if any, is executed with similar consequences.
783 If all the lists following the
787 fail (i.e. exit with non-zero status), the
792 The exit status of an
794 statement is that of non-conditional
796 that is executed; if no non-conditional
798 is executed, the exit status is zero.
799 .It Xo select Ar name
800 .Oo in Ar word No ... Oc ;
801 .No do Ar list ; No done
805 statement provides an automatic method of presenting the user with a menu and
807 An enumerated list of the specified
809 is printed on standard error, followed by a prompt
815 A number corresponding to one of the enumerated words is then read from
818 is set to the selected word (or unset if the selection is not valid),
820 is set to what was read (leading/trailing space is stripped), and
823 If a blank line (i.e. zero or more
825 octets) is entered, the menu is reprinted without executing
830 completes, the enumerated list is printed if
832 is empty, 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
836 statement is executed inside the loop.
839 is omitted, the positional parameters are used
841 For historical reasons, open and close braces may be used instead of
846 .Ic select i; { echo $i; } .
849 statement is zero if a
851 statement is used to exit the loop, non-zero otherwise.
852 .It Xo until Ar list ;
858 except that the body is executed only while the exit status of the first
861 .It Xo while Ar list ;
867 is a pre-checked loop.
868 Its body is executed as often as the exit status of the first
873 statement is the last exit status of the
875 in the body of the loop; if the body is not executed, the exit status is zero.
876 .It Xo function Ar name
884 Note that redirections specified after a function definition are
885 performed whenever the function is executed, not when the function definition
887 .It Ar name Ns \&() Ar command
893 Whitespace (space or tab) after
895 will be ignored most of the time.
896 .It Xo function Ar name Ns \&()
905 .It Xo Ic time Op Fl p
909 .Sx Command execution
910 section describes the
913 .It \&(( Ar expression No ))
914 The arithmetic expression
916 is evaluated; equivalent to
917 .Dq Li let \&" Ns Ar expression Ns \&"
919 .Sx Arithmetic expressions
922 command, below) in a compound construct.
923 .It Bq Bq Ar \ \&expression\ \&
928 commands (described later), with the following exceptions:
931 Field splitting and file name generation are not performed on arguments.
939 operators are replaced with
951 Parameter, command and arithmetic substitutions are performed as expressions
952 are evaluated and lazy expression evaluation is used for the
957 This means that in the following statement,
959 is evaluated if and only if the file
961 exists and is readable:
962 .Bd -literal -offset indent
963 $ [[ \-r foo && $(\*(Ltfoo) = b*r ]]
966 The second operand of the
970 expressions are a subset of patterns (e.g. the comparison
971 .Ic \&[[ foobar = f*r ]]
973 This even works indirectly:
974 .Bd -literal -offset indent
975 $ bar=foobar; baz=\*(aqf*r\*(aq
976 $ [[ $bar = $baz ]]; echo $?
977 $ [[ $bar = \&"$baz" ]]; echo $?
980 Perhaps surprisingly, the first comparison succeeds,
981 whereas the second doesn't.
982 This does not apply to all extglob metacharacters, currently.
986 Quoting is used to prevent the shell from treating characters or words
988 There are three methods of quoting.
991 quotes the following character, unless it is at the end of a line, in which
994 and the newline are stripped.
995 Second, a single quote
997 quotes everything up to the next single quote (this may span lines).
998 Third, a double quote
1000 quotes all characters, except
1005 up to the next unescaped double quote.
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
1011 results of double-quoted substitutions, and the old-style form of command
1012 substitution has backslash-quoting for double quotes enabled.
1015 inside a double-quoted string is followed by
1023 is removed, i.e. the combination is replaced by the second character;
1024 if it is followed by a newline, both the
1026 and the newline are stripped; otherwise, both the
1028 and the character following are unchanged.
1030 If a single-quoted string is preceded by an unquoted
1032 C style backslash expansion (see below) is applied (even single quote
1033 characters inside can be escaped and do not terminate the string then);
1034 the expanded result is treated as any other single-quoted string.
1035 If a double-quoted string is preceded by an unquoted
1040 .Ss Backslash expansion
1041 In places where backslashes are expanded, certain C and
1046 style escapes are translated.
1054 .Dq Li \eU######## ,
1063 means a hexadecimal digit, of which there may be none up to four or eight;
1064 these escapes translate a Unicode codepoint to UTF-8.
1069 expand to the escape character.
1078 are explicitly excluded;
1079 octal sequences must have the none up to three octal digits
1081 prefixed with the digit zero
1083 hexadecimal sequences
1085 are limited to none up to two hexadecimal digits
1087 both octal and hexadecimal sequences convert to raw octets;
1089 where # is none of the above, translates to \e# (backslashes are retained).
1091 Backslash expansion in the C style mode slightly differs: octal sequences
1093 must have no digit zero prefixing the one up to three octal digits
1095 and yield raw octets; hexadecimal sequences
1097 greedily eat up as many hexadecimal digits
1099 as they can and terminate with the first non-hexadecimal digit;
1100 these translate a Unicode codepoint to UTF-8.
1105 is any octet, translates to Ctrl-# (which basically means,
1107 becomes DEL, everything else is bitwise ANDed with 0x1F).
1110 where # is none of the above, translates to # (has the backslash trimmed),
1111 even if it is a newline.
1113 There are two types of aliases: normal command aliases and tracked aliases.
1114 Command aliases are normally used as a short hand for a long or often used
1116 The shell expands command aliases (i.e. substitutes the alias name
1117 for its value) when it reads the first word of a command.
1118 An expanded alias is re-processed to check for more aliases.
1119 If a command alias ends in a
1120 space or tab, the following word is also checked for alias expansion.
1121 The alias expansion process stops when a word that is not an alias is found,
1122 when a quoted word is found, or when an alias word that is currently being
1124 Aliases are specifically an interactive feature: while they do happen
1125 to work in scripts and on the command line in some cases, aliases are
1126 expanded during lexing, so their use must be in a separate command tree
1127 from their definition; otherwise, the alias will not be found.
1128 Noticeably, command lists (separated by semicolon, in command substitutions
1129 also by newline) may be one same parse tree.
1131 The following command aliases are defined automatically by the shell:
1132 .Bd -literal -offset indent
1133 autoload=\*(aq\etypeset \-fu\*(aq
1134 functions=\*(aq\etypeset \-f\*(aq
1135 hash=\*(aq\ebuiltin alias \-t\*(aq
1136 history=\*(aq\ebuiltin fc \-l\*(aq
1137 integer=\*(aq\etypeset \-i\*(aq
1138 local=\*(aq\etypeset\*(aq
1139 login=\*(aq\eexec login\*(aq
1140 nameref=\*(aq\etypeset \-n\*(aq
1141 nohup=\*(aqnohup \*(aq
1142 r=\*(aq\ebuiltin fc \-e \-\*(aq
1143 type=\*(aq\ebuiltin whence \-v\*(aq
1146 Tracked aliases allow the shell to remember where it found a particular
1148 The first time the shell does a path search for a command that is
1149 marked as a tracked alias, it saves the full path of the command.
1151 time the command is executed, the shell checks the saved path to see that it
1152 is still valid, and if so, avoids repeating the path search.
1153 Tracked aliases can be listed and created using
1155 Note that changing the
1157 parameter clears the saved paths for all tracked aliases.
1160 option is set (i.e.\&
1161 .Ic set Fl o Ic trackall
1164 the shell tracks all commands.
1165 This option is set automatically for non-interactive shells.
1166 For interactive shells, only the following commands are
1167 automatically tracked:
1187 The first step the shell takes in executing a simple-command is to perform
1188 substitutions on the words of the command.
1189 There are three kinds of
1190 substitution: parameter, command and arithmetic.
1191 Parameter substitutions,
1192 which are described in detail in the next section, take the form
1195 .Pf ${ Ns Ar ... Ns } ;
1196 command substitutions take the form
1197 .Pf $( Ns Ar command Ns \&)
1199 .Pf \` Ns Ar command Ns \`
1200 or (executed in the current environment)
1201 .Pf ${\ \& Ar command Ns \&;}
1202 and strip trailing newlines;
1203 and arithmetic substitutions take the form
1204 .Pf $(( Ns Ar expression Ns )) .
1205 Parsing the current-environment command substitution requires a space,
1206 tab or newline after the opening brace and that the closing brace be
1207 recognised as a keyword (i.e. is preceded by a newline or semicolon).
1208 They are also called funsubs (function substitutions) and behave like
1215 terminates the parent shell; shell options are shared.
1217 Another variant of substitution are the valsubs (value substitutions)
1218 .Pf ${\*(Ba\& Ns Ar command Ns \&;}
1219 which are also executed in the current environment, like funsubs, but
1220 share their I/O with the parent; instead, they evaluate to whatever
1221 the, initially empty, expression-local variable
1223 is set to within the
1226 If a substitution appears outside of double quotes, the results of the
1227 substitution are generally subject to word or field splitting according to
1228 the current value of the
1233 parameter specifies a list of octets which are used to break a string up
1234 into several words; any octets from the set space, tab and newline that
1238 .Dq IFS whitespace .
1239 Sequences of one or more
1241 whitespace octets, in combination with zero or one
1243 whitespace octets, delimit a field.
1244 As a special case, leading and trailing
1246 whitespace is stripped (i.e. no leading or trailing empty field
1247 is created by it); leading or trailing
1249 whitespace does create an empty field.
1254 .Dq Li \*(Ltspace\*(Gt:
1256 .Dq Li \*(Ltspace\*(GtA\*(Ltspace\*(Gt:\*(Ltspace\*(Gt\*(Ltspace\*(GtB::D ,
1257 the substitution for $VAR results in four fields:
1261 (an empty field) and
1265 parameter is set to the empty string, no field splitting is done;
1266 if it is unset, the default value of space, tab and newline is used.
1268 Also, note that the field splitting applies only to the immediate result of
1270 Using the previous example, the substitution for $VAR:E
1271 results in the fields:
1284 This behavior is POSIX compliant, but incompatible with some other shell
1285 implementations which do field splitting on the word which contained the
1288 as a general whitespace delimiter.
1290 The results of substitution are, unless otherwise specified, also subject to
1291 brace expansion and file name expansion (see the relevant sections below).
1293 A command substitution is replaced by the output generated by the specified
1294 command which is run in a subshell.
1296 .Pf $( Ns Ar command Ns \&)
1298 .Pf ${\*(Ba\& Ns Ar command Ns \&;}
1300 .Pf ${\ \& Ar command Ns \&;}
1301 substitutions, normal quoting rules are used when
1303 is parsed; however, for the deprecated
1304 .Pf \` Ns Ar command Ns \`
1314 when the substitution is part of a double-quoted string); a backslash
1316 followed by any other character is unchanged.
1317 As a special case in command substitutions, a command of the form
1319 is interpreted to mean substitute the contents of
1323 has the same effect as
1326 Note that some shells do not use a recursive parser for command substitutions,
1327 leading to failure for certain constructs; to be portable, use as workaround
1328 .Dq Li x=$(cat) \*(Lt\*(Lt\eEOF
1329 (or the newline-keeping
1330 .Dq Li x=\*(Lt\*(Lt\eEOF
1331 extension) instead to merely slurp the string.
1333 recommends using case statements of the form
1334 .Li "x=$(case $foo in (bar) echo $bar ;; (*) echo $baz ;; esac)"
1335 instead, which would work but not serve as example for this portability issue.
1336 .Bd -literal -offset indent
1337 x=$(case $foo in bar) echo $bar ;; *) echo $baz ;; esac)
1338 # above fails to parse on old shells; below is the workaround
1339 x=$(eval $(cat)) \*(Lt\*(Lt\eEOF
1340 case $foo in bar) echo $bar ;; *) echo $baz ;; esac
1344 Arithmetic substitutions are replaced by the value of the specified expression.
1345 For example, the command
1346 .Ic print $((2+3*4))
1349 .Sx Arithmetic expressions
1350 for a description of an expression.
1352 Parameters are shell variables; they can be assigned values and their values
1353 can be accessed using a parameter substitution.
1354 A parameter name is either one
1355 of the special single punctuation or digit character parameters described
1356 below, or a letter followed by zero or more letters or digits
1361 The latter form can be treated as arrays by appending an array index of the
1366 is an arithmetic expression.
1369 are limited to the range 0 through 4294967295, inclusive.
1370 That is, they are a 32-bit unsigned integer.
1372 Parameter substitutions take the form
1374 .Pf ${ Ns Ar name Ns }
1377 .Pf ${ Ar name Oo Ar expr Oc }
1381 is a parameter name.
1382 Substitution of all array elements with
1383 .Pf ${ Ns Ar name Ns \&[*]}
1385 .Pf ${ Ns Ar name Ns \&[@]}
1386 works equivalent to $* and $@ for positional parameters.
1387 If substitution is performed on a parameter
1388 (or an array parameter element)
1389 that is not set, an empty string is substituted unless the
1393 is set, in which case an error occurs.
1395 Parameters can be assigned values in a number of ways.
1396 First, the shell implicitly sets some parameters like
1401 this is the only way the special single character parameters are set.
1402 Second, parameters are imported from the shell's environment at startup.
1403 Third, parameters can be assigned values on the command line: for example,
1409 multiple parameter assignments can be given on a single command line and they
1410 can be followed by a simple-command, in which case the assignments are in
1411 effect only for the duration of the command (such assignments are also
1412 exported; see below for the implications of this).
1413 Note that both the parameter name and the
1415 must be unquoted for the shell to recognise a parameter assignment.
1418 is also recognised; the old and new values are immediately concatenated.
1419 The fourth way of setting a parameter is with the
1425 commands; see their descriptions in the
1426 .Sx Command execution
1432 loops set parameters as well as the
1438 Lastly, parameters can be assigned values using assignment operators
1439 inside arithmetic expressions (see
1440 .Sx Arithmetic expressions
1443 .Pf ${ Ar name No = Ar value No }
1445 form of the parameter substitution (see below).
1447 Parameters with the export attribute (set using the
1451 commands, or by parameter assignments followed by simple commands) are put in
1452 the environment (see
1454 of commands run by the shell as
1455 .Ar name Ns = Ns Ar value
1457 The order in which parameters appear in the environment of a command is
1459 When the shell starts up, it extracts parameters and their values
1460 from its environment and automatically sets the export attribute for those
1463 Modifiers can be applied to the
1464 .Pf ${ Ns Ar name Ns }
1465 form of parameter substitution:
1468 .It ${ Ar name No :\- Ar word No }
1472 is set and not empty,
1473 it is substituted; otherwise,
1477 .It ${ Ar name No :+ Ar word No }
1481 is set and not empty,
1483 is substituted; otherwise, nothing is substituted.
1485 .It ${ Ar name No := Ar word No }
1489 is set and not empty,
1490 it is substituted; otherwise, it is assigned
1492 and the resulting value of
1496 .It ${ Ar name No :? Ar word No }
1500 is set and not empty,
1501 it is substituted; otherwise,
1503 is printed on standard error (preceded by
1505 and an error occurs (normally causing termination of a shell script, function,
1506 or a script sourced using the
1511 is omitted, the string
1512 .Dq Li parameter null or not set
1516 Note that, for all of the above,
1518 is actually considered quoted, and special parsing rules apply.
1519 The parsing rules also differ on whether the expression is double-quoted:
1521 then uses double-quoting rules, except for the double quote itself
1523 and the closing brace, which, if backslash escaped, gets quote removal applied.
1525 In the above modifiers, the
1527 can be omitted, in which case the conditions only depend on
1529 being set (as opposed to set and not empty).
1532 is needed, parameter, command, arithmetic and tilde substitution are performed
1535 is not needed, it is not evaluated.
1537 The following forms of parameter substitution can also be used (if
1539 is an array, the element with the key
1541 will be substituted in scalar context):
1543 .Bl -tag -width Ds -compact
1544 .It Pf ${# Ns Ar name Ns \&}
1545 The number of positional parameters if
1550 or not specified; otherwise the length
1552 of the string value of parameter
1555 .It Pf ${# Ns Ar name Ns \&[*]}
1556 .It Pf ${# Ns Ar name Ns \&[@]}
1557 The number of elements in the array
1560 .It Pf ${% Ns Ar name Ns \&}
1562 .Pq in screen columns
1563 of the string value of parameter
1566 .Pf ${ Ns Ar name Ns }
1567 contains a control character.
1569 .It Pf ${! Ns Ar name Ns }
1570 The name of the variable referred to by
1576 is a name reference (bound variable), created by the
1578 command (which is an alias for
1579 .Ic typeset Fl n ) .
1581 cannot be one of most special parameters (see below).
1583 .It Pf ${! Ns Ar name Ns \&[*]}
1584 .It Pf ${! Ns Ar name Ns \&[@]}
1585 The names of indices (keys) in the array
1591 .Pf # Ar pattern No }
1595 .Pf ## Ar pattern No }
1600 matches the beginning of the value of parameter
1602 the matched text is deleted from the result of substitution.
1605 results in the shortest match, and two
1606 of them result in the longest match.
1607 Cannot be applied to a vector
1608 .Pq ${*} or ${@} or ${array[*]} or ${array[@]} .
1613 .Pf % Ar pattern No }
1617 .Pf %% Ar pattern No }
1620 Like ${...#...} substitution, but it deletes from the end of the value.
1621 Cannot be applied to a vector.
1626 .Pf / Ar pattern / Ar string No }
1630 .Pf /# Ar pattern / Ar string No }
1634 .Pf /% Ar pattern / Ar string No }
1638 .Pf // Ar pattern / Ar string No }
1641 The longest match of
1643 in the value of parameter
1649 is empty; the trailing slash
1651 may be omitted in that case).
1652 A leading slash followed by
1656 causes the pattern to be anchored at the beginning or end of
1657 the value, respectively; empty unanchored
1659 cause no replacement; a single leading slash or use of a
1661 that matches the empty string causes the replacement to
1662 happen only once; two leading slashes cause all occurrences
1663 of matches in the value to be replaced.
1664 Cannot be applied to a vector.
1665 Inefficiently implemented, may be slow.
1670 .Pf @/ Ar pattern / Ar string No }
1677 .Pf // Ar pattern / Ar string No } ,
1684 are expanded anew for each iteration.
1688 .Pf ${ Ar name : Ns Ar pos
1689 .Pf : Ns Ar len Ns }
1696 starting at position
1706 is negative, counting starts at the end of the string; if it
1707 is omitted, it defaults to 0.
1710 is omitted or greater than the length of the remaining string,
1711 all of it is substituted.
1716 are evaluated as arithmetic expressions.
1719 must start with a space, opening parenthesis or digit to be recognised.
1720 Cannot be applied to a vector.
1722 .It Pf ${ Ns Ar name Ns @#}
1723 The hash (using the BAFH algorithm) of the expansion of
1725 This is also used internally for the shell's hashtables.
1727 .It Pf ${ Ns Ar name Ns @Q}
1728 A quoted expression safe for re-entry, whose value is the value of the
1730 parameter, is substituted.
1735 may need extended globbing pattern
1738 .Pq \&\*(aq...\&\*(aq
1741 quote escaping unless
1745 The following special parameters are implicitly set by the shell and cannot be
1746 set directly using assignments:
1747 .Bl -tag -width "1 .. 9"
1749 Process ID of the last background process started.
1750 If no background processes have been started, the parameter is not set.
1752 The number of positional parameters ($1, $2, etc.).
1754 The PID of the shell or, if it is a subshell, the PID of the original shell.
1757 use this mechanism for generating temporary file names; see
1761 The concatenation of the current single letter options (see the
1763 command below for a list of options).
1765 The exit status of the last non-asynchronous command executed.
1766 If the last command was killed by a signal,
1768 is set to 128 plus the signal number, but at most 255.
1770 The name of the shell, determined as follows:
1771 the first argument to
1773 if it was invoked with the
1775 option and arguments were given; otherwise the
1777 argument, if it was supplied;
1778 or else the basename the shell was invoked with (i.e.\&
1781 is also set to the name of the current script or
1782 the name of the current function, if it was defined with the
1784 keyword (i.e. a Korn shell style function).
1786 The first nine positional parameters that were supplied to the shell, function,
1787 or script sourced using the
1790 Further positional parameters may be accessed using
1791 .Pf ${ Ar number Ns } .
1793 All positional parameters (except 0), i.e. $1, $2, $3, ...
1796 outside of double quotes, parameters are separate words (which are subjected
1797 to word splitting); if used within double quotes, parameters are separated
1798 by the first character of the
1800 parameter (or the empty string if
1806 unless it is used inside double quotes, in which case a separate word is
1807 generated for each positional parameter.
1808 If there are no positional parameters, no word is generated.
1810 can be used to access arguments, verbatim, without losing
1811 empty arguments or splitting arguments with spaces (IFS, actually).
1814 The following parameters are set and/or used by the shell:
1815 .Bl -tag -width "KSH_VERSION"
1818 When an external command is executed by the shell, this parameter is set in the
1819 environment of the new process to the path of the executed command.
1820 In interactive use, this parameter is also set in the parent shell to the last
1821 word of the previous command.
1823 The PID of the shell or subshell.
1827 but used to resolve the argument to the
1832 is set and does not contain
1834 or an empty string element, the current directory is not searched.
1837 built-in command will display the resulting directory when a match is found
1838 in any search path other than the empty path.
1840 Set to the number of columns on the terminal or window.
1841 Always set, defaults to 80, unless the
1842 value as reported by
1844 is non-zero and sane enough (minimum is 12x3); similar for
1846 This parameter is used by the interactive line editing modes and by the
1851 commands to format information columns.
1852 Importing from the environment or unsetting this parameter removes the
1853 binding to the actual terminal size in favour of the provided value.
1855 If this parameter is found to be set after any profile files are executed, the
1856 expanded value is used as a shell startup file.
1857 It typically contains function and alias definitions.
1858 .It Ev EPOCHREALTIME
1859 Time since the epoch, as returned by
1860 .Xr gettimeofday 2 ,
1861 formatted as decimal
1867 padded to exactly six decimal digits.
1869 If set, this parameter is assumed to contain the shell that is to be used to
1870 execute commands that
1872 fails to execute and which do not start with a
1873 .Dq Li #! Ns Ar shell
1876 The editor used by the
1878 command (see below).
1882 but used when an undefined function is executed to locate the file defining the
1884 It is also searched when a command can't be found using
1888 below for more information.
1890 The name of the file used to store command history.
1891 When assigned to or unset, the file is opened, history is truncated
1892 then loaded from the file; subsequent new commands (possibly consisting
1893 of several lines) are appended once they successfully compiled.
1894 Also, several invocations of the shell will share history if their
1896 parameters all point to the same file.
1901 is unset or empty, no history file is used.
1902 This is different from
1906 The number of commands normally stored for history.
1907 The default is 2047.
1908 Do not set this value to insanely high values such as 1000000000 because
1910 can then not allocate enough memory for the history and will not start.
1912 The default directory for the
1914 command and the value substituted for an unqualified
1920 Internal field separator, used during substitution and by the
1922 command, to split values into distinct arguments; normally set to space, tab
1929 This parameter is not imported from the environment when the shell is
1932 The effective group id of the shell.
1934 The real group id of the shell.
1936 The real user id of the shell.
1938 The last matched string.
1939 In a future version, this will be an indexed array,
1940 with indexes 1 and up capturing matching groups.
1941 Set by string comparisons (== and !=) in double-bracket test
1942 expressions when a match is found (when != returns false), by
1944 when a match is encountered, and by the substitution operations
1954 .Pf ## Ar pat No } ,
1966 .Pf %% Ar pat No } ,
1972 .Pf / Ar pat / Ar rpl No } ,
1978 .Pf /# Ar pat / Ar rpl No } ,
1984 .Pf /% Ar pat / Ar rpl No } ,
1990 .Pf // Ar pat / Ar rpl No } ,
1997 .Pf @/ Ar pat / Ar rpl No } .
2000 See the end of the Emacs editing mode documentation for an example.
2002 The name and version of the shell (read-only).
2003 See also the version commands in
2004 .Sx Emacs editing mode
2009 The line number of the function or shell script that is currently being
2012 Set to the number of lines on the terminal or window.
2013 Always set, defaults to 24.
2017 The previous working directory.
2020 has not successfully changed directories since the shell started or if the
2021 shell doesn't know where it is.
2025 it contains the argument for a parsed option, if it requires one.
2027 The index of the next argument to be processed when using
2029 Assigning 1 to this parameter causes
2031 to process arguments from the beginning the next time it is invoked.
2033 A colon (semicolon on OS/2) separated list of directories that are
2034 searched when looking for commands and files sourced using the
2036 command (see below).
2037 An empty string resulting from a leading or trailing
2038 colon, or two adjacent colons, is treated as a
2040 (the current directory).
2042 The process ID of the shell's process group leader.
2044 An array containing the errorlevel (exit status) codes,
2045 one by one, of the last pipeline run in the foreground.
2047 The process ID of the shell's parent.
2049 The primary prompt for interactive shells.
2050 Parameter, command and arithmetic
2051 substitutions are performed, and
2053 is replaced with the current command number (see the
2058 can be put in the prompt by placing
2063 The default prompt is
2070 is invoked by root and
2074 character, the default value will be used even if
2076 already exists in the environment.
2080 distribution comes with a sample
2082 containing a sophisticated example, but you might like the following one
2083 (note that ${HOSTNAME:=$(hostname)} and the
2084 root-vs-user distinguishing clause are (in this example) executed at
2086 assignment time, while the $USER and $PWD are escaped
2087 and thus will be evaluated each time a prompt is displayed):
2089 PS1=\*(aq${USER:=$(id \-un)}\*(aq"@${HOSTNAME:=$(hostname)}:\e$PWD $(
2090 if (( USER_ID )); then print \e$; else print \e#; fi) "
2093 Note that since the command-line editors try to figure out how long the prompt
2094 is (so they know how far it is to the edge of the screen), escape codes in
2095 the prompt tend to mess things up.
2096 You can tell the shell not to count certain
2097 sequences (such as escape codes) by prefixing your prompt with a
2098 character (such as Ctrl-A) followed by a carriage return and then delimiting
2099 the escape codes with this character.
2100 Any occurrences of that character in the prompt are not printed.
2101 By the way, don't blame me for
2102 this hack; it's derived from the original
2104 which did print the delimiter character so you were out of luck
2105 if you did not have any non-printing characters.
2107 Since Backslashes and other special characters may be
2108 interpreted by the shell, to set
2110 either escape the backslash itself
2111 or use double quotes.
2112 The latter is more practical.
2113 This is a more complex example,
2114 avoiding to directly enter special characters (for example with
2116 in the emacs editing mode),
2117 which embeds the current working directory,
2119 .Pq colour would work, too ,
2120 in the prompt string:
2121 .Bd -literal -offset indent
2123 PS1="$x$(print \e\er)$x$(tput so)$x\e$PWD$x$(tput se)$x\*(Gt "
2126 Due to a strong suggestion from David G. Korn,
2128 now also supports the following form:
2129 .Bd -literal -offset indent
2130 PS1=$'\e1\er\e1\ee[7m\e1$PWD\e1\ee[0m\e1\*(Gt '
2133 Secondary prompt string, by default
2135 used when more input is needed to complete a command.
2139 statement when reading a menu selection.
2143 Used to prefix commands that are printed during execution tracing (see the
2146 Parameter, command and arithmetic substitutions are performed
2147 before it is printed.
2150 You may want to set it to
2151 .Dq Li \&[$EPOCHREALTIME]\ \&
2152 instead, to include timestamps.
2154 The current working directory.
2155 May be unset or empty if the shell doesn't know where it is.
2159 is referenced, it is assigned a number between 0 and 32767 from
2160 a Linear Congruential PRNG first.
2162 Default parameter for the
2164 command if no names are given.
2167 loops to store the value that is read from standard input.
2169 The number of seconds since the shell started or, if the parameter has been
2170 assigned an integer value, the number of seconds since the assignment plus the
2171 value that was assigned.
2173 If set to a positive integer in an interactive shell, it specifies the maximum
2174 number of seconds the shell will wait for input after printing the primary
2177 If the time is exceeded, the shell exits.
2179 The directory temporary shell files are created in.
2180 If this parameter is not
2181 set or does not contain the absolute path of a writable directory, temporary
2182 files are created in
2185 The effective user id of the shell.
2188 Tilde expansion which is done in parallel with parameter substitution, is done
2189 on words starting with an unquoted
2191 The characters following the tilde, up to the first
2193 if any, are assumed to be a login name.
2194 If the login name is empty,
2198 the simplified value of the
2203 parameter is substituted, respectively.
2204 Otherwise, the password file is
2205 searched for the login name, and the tilde expression is substituted with the
2206 user's home directory.
2207 If the login name is not found in the password file or
2208 if any quoting or parameter substitution occurs in the login name, no
2209 substitution is performed.
2211 In parameter assignments
2212 (such as those preceding a simple-command or those occurring
2220 tilde expansion is done after any assignment
2221 (i.e. after the equals sign)
2222 or after an unquoted colon
2224 login names are also delimited by colons.
2226 The home directory of previously expanded login names are cached and re-used.
2229 command may be used to list, change and add to this cache (e.g.\&
2230 .Ic alias \-d fac=/usr/local/facilities; cd \*(TIfac/bin ) .
2231 .Ss Brace expansion (alternation)
2232 Brace expressions take the following form:
2233 .Bd -unfilled -offset indent
2236 .Ar prefix No { Ar str1 No ,...,
2237 .Ar strN No } Ar suffix
2242 The expressions are expanded to
2244 words, each of which is the concatenation of
2250 .Dq Li a{c,b{X,Y},d}e
2251 expands to four words:
2257 As noted in the example, brace expressions can be nested and the resulting
2258 words are not sorted.
2259 Brace expressions must contain an unquoted comma
2261 for expansion to occur (e.g.\&
2266 Brace expansion is carried out after parameter substitution
2267 and before file name generation.
2268 .Ss File name patterns
2269 A file name pattern is a word containing one or more unquoted
2279 Once brace expansion has been performed, the shell replaces file
2280 name patterns with the sorted names of all the files that match the pattern
2281 (if no files match, the word is left unchanged).
2282 The pattern elements have the following meaning:
2285 Matches any single character.
2287 Matches any sequence of octets.
2289 Matches any of the octets inside the brackets.
2290 Ranges of octets can be specified by separating two octets by a
2297 In order to represent itself, a
2299 must either be quoted or the first or last octet in the octet list.
2302 must be quoted or the first octet in the list if it is to represent itself
2303 instead of the end of the list.
2306 appearing at the start of the list has special meaning (see below), so to
2307 represent itself it must be quoted or appear later in the list.
2310 except it matches any octet not inside the brackets.
2312 .It *( Ar pattern\*(Ba No ...\*(Ba Ar pattern )
2314 Matches any string of octets that matches zero or more occurrences of the
2316 Example: The pattern
2325 .It +( Ar pattern\*(Ba No ...\*(Ba Ar pattern )
2327 Matches any string of octets that matches one or more occurrences of the
2329 Example: The pattern
2337 .It ?( Ar pattern\*(Ba No ...\*(Ba Ar pattern )
2339 Matches the empty string or a string that matches one of the specified
2341 Example: The pattern
2343 only matches the strings
2349 .It @( Ar pattern\*(Ba No ...\*(Ba Ar pattern )
2351 Matches a string that matches one of the specified patterns.
2352 Example: The pattern
2354 only matches the strings
2359 .It !( Ar pattern\*(Ba No ...\*(Ba Ar pattern )
2361 Matches any string that does not match one of the specified patterns.
2362 Examples: The pattern
2364 matches all strings except
2370 matches no strings; the pattern
2372 matches all strings (think about it).
2375 Note that complicated globbing, especially with alternatives,
2376 is slow; using separate comparisons may (or may not) be faster.
2394 Note that none of the above pattern elements match either a period
2396 at the start of a file name or a slash
2398 even if they are explicitly used in a [...] sequence; also, the names
2402 are never matched, even by the pattern
2407 option is set, any directories that result from file name generation are marked
2410 .Ss Input/output redirection
2411 When a command is executed, its standard input, standard output and standard
2412 error (file descriptors 0, 1 and 2, respectively) are normally inherited from
2414 Three exceptions to this are commands in pipelines, for which
2415 standard input and/or standard output are those set up by the pipeline,
2416 asynchronous commands created when job control is disabled, for which standard
2417 input is initially set to
2419 and commands for which any of the following redirections have been specified:
2420 .Bl -tag -width XXxxmarker
2421 .It \*(Gt Ns Ar file
2422 Standard output is redirected to
2426 does not exist, it is created; if it does exist, is a regular file, and the
2428 option is set, an error occurs; otherwise, the file is truncated.
2429 Note that this means the command
2430 .Ic cmd \*(Ltfoo \*(Gtfoo
2433 for reading and then truncate it when it opens it for writing, before
2435 gets a chance to actually read
2437 .It \*(Gt\*(Ba Ns Ar file
2440 except the file is truncated, even if the
2443 .It \*(Gt\*(Gt Ns Ar file
2448 exists it is appended to instead of being truncated.
2449 Also, the file is opened
2450 in append mode, so writes always go to the end of the file (see
2452 .It \*(Lt Ns Ar file
2453 Standard input is redirected from
2455 which is opened for reading.
2456 .It \*(Lt\*(Gt Ns Ar file
2459 except the file is opened for reading and writing.
2460 .It \*(Lt\*(Lt Ns Ar marker
2461 After reading the command line containing this kind of redirection (called a
2462 .Dq here document ) ,
2463 the shell copies lines from the command source into a temporary file until a
2467 When the command is executed, standard input is redirected from the
2471 contains no quoted characters, the contents of the temporary file are processed
2472 as if enclosed in double quotes each time the command is executed, so
2473 parameter, command and arithmetic substitutions are performed, along with
2484 If multiple here documents are used on the same command line, they are saved in
2489 is given, the here document ends at the next
2491 and substitution will be performed.
2494 is only a set of either single
2498 quotes with nothing in between, the here document ends at the next empty line
2499 and substitution will not be performed.
2500 .It \*(Lt\*(Lt\- Ns Ar marker
2503 except leading tabs are stripped from lines in the here document.
2504 .It \*(Lt\*(Lt\*(Lt Ns Ar word
2511 This is called a here string.
2513 Standard input is duplicated from file descriptor
2516 can be a single digit, indicating the number of an existing file descriptor;
2519 indicating the file descriptor associated with the output of the current
2520 co-process; or the character
2522 indicating standard input is to be closed.
2526 except the operation is done on standard output.
2527 .It &\*(Gt Ns Ar file
2529 .Ic \*(Gt Ns Ar file 2\*(Gt&1 .
2530 This is a deprecated (legacy) GNU
2532 extension supported by
2534 which also supports the preceding explicit fd digit, for example,
2535 .Ic 3&\*(Gt Ns Ar file
2537 .Ic 3\*(Gt Ns Ar file 2\*(Gt&3
2540 but a syntax error in GNU
2543 .No &\*(Gt\*(Ba Ns Ar file ,
2544 .No &\*(Gt\*(Gt Ns Ar file ,
2545 .No &\*(Gt& Ns Ar fd
2548 .Ic \*(Gt\*(Ba Ns Ar file ,
2549 .Ic \*(Gt\*(Gt Ns Ar file
2551 .Ic \*(Gt& Ns Ar fd ,
2560 In any of the above redirections, the file descriptor that is redirected
2561 (i.e. standard input or standard output)
2562 can be explicitly given by preceding the
2563 redirection with a single digit.
2564 Parameter, command and arithmetic
2565 substitutions, tilde substitutions, and, if the shell is interactive,
2566 file name generation are all performed on the
2571 arguments of redirections.
2572 Note, however, that the results of any file name
2573 generation are only used if a single file is matched; if multiple files match,
2574 the word with the expanded file name generation characters is used.
2576 that in restricted shells, redirections which can create files cannot be used.
2578 For simple-commands, redirections may appear anywhere in the command; for
2584 any redirections must appear at the end.
2585 Redirections are processed after
2586 pipelines are created and in the order they are given, so the following
2587 will print an error with a line number prepended to it:
2589 .D1 $ cat /foo/bar 2\*(Gt&1 \*(Gt/dev/null \*(Ba pr \-n \-t
2591 File descriptors created by I/O redirections are private to the shell.
2592 .Ss Arithmetic expressions
2593 Integer arithmetic expressions can be used with the
2595 command, inside $((...)) expressions, inside array references (e.g.\&
2596 .Ar name Ns Bq Ar expr ) ,
2597 as numeric arguments to the
2599 command, and as the value of an assignment to an integer parameter.
2601 This also affects implicit conversion to integer, for example as done by the
2605 use unchecked user input, e.g. from the environment, in an arithmetic context!
2607 Expressions are calculated using signed arithmetic and the
2609 type (a 32-bit signed integer), unless they begin with a sole
2611 character, in which case they use
2613 .Po a 32-bit unsigned integer Pc .
2615 Expressions may contain alpha-numeric parameter identifiers, array references
2616 and integer constants and may be combined with the following C operators
2617 (listed and grouped in increasing order of precedence):
2620 .Bd -literal -offset indent
2621 + \- ! \*(TI ++ \-\-
2625 .Bd -literal -offset indent
2627 = += \-= *= /= %= \*(Lt\*(Lt= \*(Gt\*(Gt= \*(ha\*(Lt= \*(ha\*(Gt= &= \*(ha= \*(Ba=
2634 \*(Lt \*(Lt= \*(Gt \*(Gt=
2635 \*(Lt\*(Lt \*(Gt\*(Gt \*(ha\*(Lt \*(ha\*(Gt
2641 .Bd -literal -offset indent
2642 ?: (precedence is immediately higher than assignment)
2646 .Bd -literal -offset indent
2650 Integer constants and expressions are calculated using an exactly 32-bit
2651 wide, signed or unsigned, type with silent wraparound on integer overflow.
2652 Integer constants may be specified with arbitrary bases using the notation
2653 .Ar base Ns # Ns Ar number ,
2656 is a decimal integer specifying the base (up to 36), and
2658 is a number in the specified base.
2659 Additionally, base-16 integers may be specified by prefixing them with
2661 .Pq case-insensitive
2662 in all forms of arithmetic expressions, except as numeric arguments to the
2665 Prefixing numbers with a sole digit zero
2667 does not cause interpretation as octal (except in POSIX mode,
2668 as required by the standard), as that's unsafe to do.
2672 extension, numbers to the base of one are treated as either (8-bit
2673 transparent) ASCII or Unicode codepoints, depending on the shell's
2675 flag (current setting).
2684 Note that NUL bytes (integral value of zero) cannot be used.
2685 An unset or empty parameter evaluates to 0 in integer context.
2686 In Unicode mode, raw octets are mapped into the range EF80..EFFF as in
2687 OPTU-8, which is in the PUA and has been assigned by CSUR for this use.
2688 If more than one octet in ASCII mode, or a sequence of more than one
2689 octet not forming a valid and minimal CESU-8 sequence is passed, the
2690 behaviour is undefined (usually, the shell aborts with a parse error,
2691 but rarely, it succeeds, e.g. on the sequence C2 20).
2692 That's why you should always use ASCII mode unless you know that the
2693 input is well-formed UTF-8 in the range of 0000..FFFD if you use this
2694 feature, as opposed to
2697 The operators are evaluated as follows:
2698 .Bl -tag -width Ds -offset indent
2700 Result is the argument (included for completeness).
2705 the result is 1 if argument is zero, 0 if not.
2707 Arithmetic (bit-wise) NOT.
2709 Increment; must be applied to a parameter (not a literal or other expression).
2710 The parameter is incremented by 1.
2711 When used as a prefix operator, the result
2712 is the incremented value of the parameter; when used as a postfix operator, the
2713 result is the original value of the parameter.
2717 except the parameter is decremented by 1.
2719 Separates two arithmetic expressions; the left-hand side is evaluated first,
2721 The result is the value of the expression on the right-hand side.
2723 Assignment; the variable on the left is set to the value on the right.
2725 .No += \-= *= /= %= \*(Lt\*(Lt= \*(Gt\*(Gt=
2726 .No \*(ha\*(Lt= \*(ha\*(Gt= &= \*(ha= \*(Ba=
2728 Assignment operators.
2743 with any operator precedence in
2747 .Dq Li var1 *= 5 + 3
2748 is the same as specifying
2749 .Dq Li var1 = var1 * (5 + 3) .
2752 the result is 1 if either argument is non-zero, 0 if not.
2753 The right argument is evaluated only if the left argument is zero.
2756 the result is 1 if both arguments are non-zero, 0 if not.
2757 The right argument is evaluated only if the left argument is non-zero.
2759 Arithmetic (bit-wise) OR.
2761 Arithmetic (bit-wise) XOR
2764 Arithmetic (bit-wise) AND.
2766 Equal; the result is 1 if both arguments are equal, 0 if not.
2768 Not equal; the result is 0 if both arguments are equal, 1 if not.
2770 Less than; the result is 1 if the left argument is less than the right, 0 if
2772 .It \*(Lt= \*(Gt \*(Gt=
2773 Less than or equal, greater than, greater than or equal.
2776 .It \*(Lt\*(Lt \*(Gt\*(Gt
2777 Shift left (right); the result is the left argument with its bits
2778 arithmetically (signed operation) or logically (unsigned expression)
2779 shifted left (right) by the amount given in the right argument.
2780 .It \*(ha\*(Lt \*(ha\*(Gt
2781 Rotate left (right); the result is similar to shift,
2782 except that the bits shifted out at one end are shifted in
2783 at the other end, instead of zero or sign bits.
2785 Addition, subtraction, multiplication and division.
2787 Remainder; the result is the symmetric remainder of the division of the left
2788 argument by the right.
2789 To get the mathematical modulus of
2805 is non-zero, the result is
2807 otherwise the result is
2809 The non-result argument is not evaluated.
2812 A co-process (which is a pipeline created with the
2814 operator) is an asynchronous process that the shell can both write to (using
2816 and read from (using
2818 The input and output of the co-process can also be manipulated using
2822 redirections, respectively.
2823 Once a co-process has been started, another can't
2824 be started until the co-process exits, or until the co-process's input has been
2826 .Ic exec Ar n Ns Ic \*(Gt&p
2828 If a co-process's input is redirected in this way, the next
2829 co-process to be started will share the output with the first co-process,
2830 unless the output of the initial co-process has been redirected using an
2831 .Ic exec Ar n Ns Ic \*(Lt&p
2834 Some notes concerning co-processes:
2837 The only way to close the co-process's input (so the co-process reads an
2838 end-of-file) is to redirect the input to a numbered file descriptor and then
2839 close that file descriptor:
2840 .Ic exec 3\*(Gt&p; exec 3\*(Gt&\-
2842 In order for co-processes to share a common output, the shell must keep the
2843 write portion of the output pipe open.
2844 This means that end-of-file will not be
2845 detected until all co-processes sharing the co-process's output have exited
2846 (when they all exit, the shell closes its copy of the pipe).
2848 avoided by redirecting the output to a numbered file descriptor (as this also
2849 causes the shell to close its copy).
2850 Note that this behaviour is slightly
2851 different from the original Korn shell which closes its copy of the write
2852 portion of the co-process output when the most recently started co-process
2853 (instead of when all sharing co-processes) exits.
2858 signals during writes if the signal is not being trapped or ignored; the same
2859 is true if the co-process input has been duplicated to another file descriptor
2861 .Ic print Fl u Ns Ar n
2865 Functions are defined using either Korn shell
2866 .Ic function Ar function-name
2867 syntax or the Bourne/POSIX shell
2868 .Ar function-name Ns \&()
2869 syntax (see below for the difference between the two forms).
2872 (i.e. scripts sourced using the
2875 in that they are executed in the current environment.
2878 shell arguments (i.e. positional parameters $1, $2, etc.)\&
2879 are never visible inside them.
2880 When the shell is determining the location of a command, functions
2881 are searched after special built-in commands, before builtins and the
2885 An existing function may be deleted using
2886 .Ic unset Fl f Ar function-name .
2887 A list of functions can be obtained using
2889 and the function definitions can be listed using
2893 command (which is an alias for
2895 may be used to create undefined functions: when an undefined function is
2896 executed, the shell searches the path specified in the
2898 parameter for a file with the same name as the function which, if found, is
2900 If after executing the file the named function is found to
2901 be defined, the function is executed; otherwise, the normal command search is
2902 continued (i.e. the shell searches the regular built-in command table and
2904 Note that if a command is not found using
2906 an attempt is made to autoload a function using
2908 (this is an undocumented feature of the original Korn shell).
2910 Functions can have two attributes,
2914 which can be set with
2919 When a traced function is executed, the shell's
2921 option is turned on for the function's duration.
2924 attribute of functions is currently not used.
2925 In the original Korn shell,
2926 exported functions are visible to shell scripts that are executed.
2928 Since functions are executed in the current shell environment, parameter
2929 assignments made inside functions are visible after the function completes.
2930 If this is not the desired effect, the
2932 command can be used inside a function to create a local parameter.
2936 uses static scoping (one global scope, one local scope per function)
2937 and allows local variables only on Korn style functions, whereas
2939 uses dynamic scoping (nested scopes of varying locality).
2940 Note that special parameters (e.g.\&
2942 can't be scoped in this way.
2944 The exit status of a function is that of the last command executed in the
2946 A function can be made to finish immediately using the
2948 command; this may also be used to explicitly specify the exit status.
2950 Functions defined with the
2952 reserved word are treated differently in the following ways from functions
2958 The $0 parameter is set to the name of the function
2959 (Bourne-style functions leave $0 untouched).
2961 Parameter assignments preceding function calls are not kept in the shell
2962 environment (executing Bourne-style functions will keep assignments).
2965 is saved/reset and restored on entry and exit from the function so
2967 can be used properly both inside and outside the function (Bourne-style
2972 inside a function interferes with using
2974 outside the function).
2978 have local scope, i.e. changes inside a function are reset upon its exit.
2981 In the future, the following differences may also be added:
2984 A separate trap/signal environment will be used during the execution of
2986 This will mean that traps set inside a function will not affect the
2987 shell's traps and signals that are not ignored in the shell (but may be
2988 trapped) will have their default effect in a function.
2990 The EXIT trap, if set in a function, will be executed after the function
2993 .Ss Command execution
2994 After evaluation of command-line arguments, redirections and parameter
2995 assignments, the type of command is determined: a special built-in command,
2996 a function, a normal builtin or the name of a file to execute found using the
2999 The checks are made in the above order.
3000 Special built-in commands differ from other commands in that the
3002 parameter is not used to find them, an error during their execution can
3003 cause a non-interactive shell to exit, and parameter assignments that are
3004 specified before the command are kept after the command completes.
3005 Regular built-in commands are different only in that the
3007 parameter is not used to find them.
3011 and POSIX differ somewhat in which commands are considered
3014 POSIX special built-in utilities:
3016 .Ic \&. , \&: , break , continue ,
3017 .Ic eval , exec , exit , export ,
3018 .Ic readonly , return , set , shift ,
3019 .Ic times , trap , unset
3023 commands keeping assignments:
3025 .Ic builtin , global , source , typeset ,
3028 Builtins that are not special:
3030 .Ic [ , alias , bg , bind ,
3031 .Ic cat , cd , command , echo ,
3032 .Ic false , fc , fg , getopts ,
3033 .Ic jobs , kill , let , print ,
3034 .Ic pwd , read , realpath , rename ,
3035 .Ic sleep , suspend , test , true ,
3036 .Ic ulimit , umask , unalias , whence
3038 Once the type of command has been determined, any command-line parameter
3039 assignments are performed and exported for the duration of the command.
3041 The following describes the special and regular built-in commands and
3042 builtin-like reserved words:
3044 .Bl -tag -width false -compact
3045 .It Ic \&. Ar file Op Ar arg ...
3049 Execute the commands in
3051 in the current environment.
3052 The file is searched for in the directories of
3054 If arguments are given, the positional parameters may be used to access them
3058 If no arguments are given, the positional parameters are
3059 those of the environment the command is used in.
3061 .It Ic \&: Op Ar ...
3063 Exit status is set to zero.
3065 .It Ic \&[ Ar expression Ic \&]
3070 .Oo Fl d \*(Ba t Oo Fl r Oc \*(Ba
3075 .Op Ns = Ns Ar value
3081 For any name without a value, the existing alias is listed.
3082 Any name with a value defines an alias (see
3086 When listing aliases, one of two formats is used.
3087 Normally, aliases are listed as
3088 .Ar name Ns = Ns Ar value ,
3092 If options were preceded with
3096 is given on the command line, only
3102 option causes directory aliases which are used in tilde expansion to be
3109 option is used, each alias is prefixed with the string
3114 option indicates that tracked aliases are to be listed/set (values specified on
3115 the command line are ignored for tracked aliases).
3118 option indicates that all tracked aliases are to be reset.
3124 the export attribute of an alias, or, if no names are given, lists the aliases
3125 with the export attribute (exporting an alias has no effect).
3127 .It Ic bg Op Ar job ...
3128 Resume the specified stopped job(s) in the background.
3129 If no jobs are specified,
3134 below for more information.
3137 The current bindings are listed.
3142 instead lists the names of the functions to which keys may be bound.
3144 .Sx Emacs editing mode
3145 for more information.
3147 .It Xo Ic bind Op Fl m
3148 .Ar string Ns = Ns Op Ar substitute
3152 .Ar string Ns = Ns Op Ar editing-command
3155 The specified editing command is bound to the given
3157 which should consist of a control character
3158 optionally preceded by one of the two prefix characters
3159 and optionally succeeded by a tilde character.
3162 will cause the editing command to be immediately invoked.
3165 flag is given, the specified input
3167 will afterwards be immediately replaced by the given
3169 string which may contain editing commands but not other macros.
3170 If a tilde postfix is given, a tilde trailing the one or
3171 two prefices and the control character is ignored, any
3172 other trailing character will be processed afterwards.
3174 Control characters may be written using caret notation
3175 i.e. \*(haX represents Ctrl-X.
3176 Note that although only two prefix characters (usually ESC and \*(haX)
3177 are supported, some multi-character sequences can be supported.
3179 The following default bindings show how the arrow keys, the home, end and
3180 delete key on a BSD wsvt25, xterm\-xfree86 or GNU screen terminal are bound
3181 (of course some escape sequences won't work out quite this nicely):
3182 .Bd -literal -offset indent
3183 bind \*(aq\*(haX\*(aq=prefix\-2
3184 bind \*(aq\*(ha[[\*(aq=prefix\-2
3185 bind \*(aq\*(haXA\*(aq=up\-history
3186 bind \*(aq\*(haXB\*(aq=down\-history
3187 bind \*(aq\*(haXC\*(aq=forward\-char
3188 bind \*(aq\*(haXD\*(aq=backward\-char
3189 bind \*(aq\*(haX1\*(TI\*(aq=beginning\-of\-line
3190 bind \*(aq\*(haX7\*(TI\*(aq=beginning\-of\-line
3191 bind \*(aq\*(haXH\*(aq=beginning\-of\-line
3192 bind \*(aq\*(haX4\*(TI\*(aq=end\-of\-line
3193 bind \*(aq\*(haX8\*(TI\*(aq=end\-of\-line
3194 bind \*(aq\*(haXF\*(aq=end\-of\-line
3195 bind \*(aq\*(haX3\*(TI\*(aq=delete\-char\-forward
3198 .It Ic break Op Ar level
3214 .Ar command Op Ar arg ...
3216 Execute the built-in command
3224 Read files sequentially, in command line order, and write them to
3230 or absent, read from standard input.
3231 For direct builtin calls, the
3234 option is supported as a no-op.
3235 For calls from shell, if any options are given, an external
3237 utility is preferred over the builtin.
3254 Set the working directory to
3258 is set, it lists the search path for the directory containing
3260 An unset or empty path means the current directory.
3263 is found in any component of the
3265 search path other than an unset or empty path,
3266 the name of the new working directory will be written to standard output.
3269 is missing, the home directory
3276 the previous working directory is used (see the
3282 option (logical path) is used or if the
3284 option isn't set (see the
3286 command below), references to
3290 are relative to the path used to get to the directory.
3293 option (physical path) is used or if the
3297 is relative to the filesystem directory tree.
3302 parameters are updated to reflect the current and old working directory,
3306 option is set for physical filesystem traversal and
3308 could not be set, the exit code is 1; greater than 1 if an
3309 error occurred, 0 otherwise.
3325 in the current directory, and the shell attempts to change to the new
3340 is executed exactly as if
3342 had not been specified, with two exceptions:
3345 cannot be a shell function;
3346 and secondly, special built-in commands lose their specialness
3347 (i.e. redirection and utility errors do not cause the shell to
3348 exit, and command assignments are not permanent).
3352 option is given, a default search path is used instead of the current value of
3354 the actual value of which is system dependent.
3358 option is given, instead of executing
3360 information about what would be executed is given (and the same is done for
3362 For builtins, functions and keywords, their names are simply printed;
3363 for aliases, a command that defines them is printed;
3364 for utilities found by searching the
3366 parameter, the full path of the command is printed.
3367 If no command is found
3368 (i.e. the path search fails), nothing is printed and
3370 exits with a non-zero status.
3375 option, except it is more verbose.
3377 .It Ic continue Op Ar level
3378 Jumps to the beginning of the
3396 this utility is not portable; use the Korn shell builtin
3400 Prints its arguments (separated by spaces) followed by a newline, to the
3402 The newline is suppressed if any of the arguments contain the
3407 command below for a list of other backslash sequences that are recognised.
3409 The options are provided for compatibility with
3414 option suppresses the trailing newline,
3416 enables backslash interpretation (a no-op, since this is normally done), and
3418 suppresses backslash interpretation.
3424 option is set or this is a direct builtin call, only the first argument
3425 is treated as an option, and only if it is exactly
3427 Backslash interpretation is disabled.
3429 .It Ic eval Ar command ...
3430 The arguments are concatenated (with spaces between them) to form a single
3431 string which the shell then parses and executes in the current environment.
3437 .Op Ar command Op Ar arg ...
3439 The command is executed without forking, replacing the shell process.
3440 This is currently absolute, i.e.\&
3442 never returns, even if the
3447 option permits setting a different
3451 clears the environment before executing the child process, except for the
3453 variable and direct assignments.
3455 If no command is given except for I/O redirection, the I/O redirection is
3456 permanent and the shell is
3458 Any file descriptors greater than 2 which are opened or
3460 in this way are not made available to other executed commands (i.e. commands
3461 that are not built-in to the shell).
3462 Note that the Bourne shell differs here;
3463 it does pass these file descriptors on.
3465 .It Ic exit Op Ar status
3466 The shell exits with the specified exit status.
3469 is not specified, the exit status is the current value of the
3476 .Op Ar parameter Ns Op = Ns Ar value
3478 Sets the export attribute of the named parameters.
3479 Exported parameters are passed in the environment to executed commands.
3480 If values are specified, the named parameters are also assigned.
3482 If no parameters are specified, all parameters with the export attribute
3483 set are printed one per line; either their names, or, if a
3485 with no option letter is specified, name=value pairs, or, with
3488 commands suitable for re-entry.
3491 A command that exits with a non-zero status.
3495 .Oo Fl e Ar editor \*(Ba
3498 .Op Ar first Op Ar last
3503 select commands from the history.
3504 Commands can be selected by history number
3505 (negative numbers go backwards from the current, most recent, line)
3506 or a string specifying the most recent command starting with that string.
3509 option lists the command on standard output, and
3511 inhibits the default command numbers.
3514 option reverses the order of the list.
3517 the selected commands are edited by the editor specified with the
3521 is specified, the editor specified by the
3523 parameter (if this parameter is not set,
3525 is used), and then executed by the shell.
3529 .Cm \-e \- \*(Ba Fl s
3531 .Op Ar old Ns = Ns Ar new
3534 Re-execute the selected command (the previous command by default) after
3535 performing the optional substitution of
3541 is specified, all occurrences of
3549 is identical: re-execute the selected command without invoking an editor.
3550 This command is usually accessed with the predefined:
3551 .Ic alias r=\*(aqfc \-e \-\*(aq
3553 .It Ic fg Op Ar job ...
3554 Resume the specified job(s) in the foreground.
3555 If no jobs are specified,
3560 below for more information.
3567 Used by shell procedures to parse the specified arguments (or positional
3568 parameters, if no arguments are given) and to check for legal options.
3570 contains the option letters that
3573 If a letter is followed by a colon, the option is expected to
3575 Options that do not take arguments may be grouped in a single argument.
3576 If an option takes an argument and the option character is not the
3577 last character of the argument it is found in, the remainder of the argument is
3578 taken to be the option's argument; otherwise, the next argument is the option's
3583 is invoked, it places the next option in the shell parameter
3585 and the index of the argument to be processed by the next call to
3587 in the shell parameter
3589 If the option was introduced with a
3591 the option placed in
3595 When an option requires an argument,
3597 places it in the shell parameter
3600 When an illegal option or a missing option argument is encountered, a question
3601 mark or a colon is placed in
3603 (indicating an illegal option or missing argument, respectively) and
3605 is set to the option character that caused the problem.
3608 does not begin with a colon, a question mark is placed in
3611 is unset, and an error message is printed to standard error.
3613 When the end of the options is encountered,
3615 exits with a non-zero exit status.
3616 Options end at the first (non-option
3617 argument) argument that does not start with a
3621 argument is encountered.
3623 Option parsing can be reset by setting
3625 to 1 (this is done automatically whenever the shell or a shell procedure is
3628 Warning: Changing the value of the shell parameter
3630 to a value other than 1 or parsing different sets of arguments without
3633 may lead to unexpected results.
3644 Without arguments, any hashed executable command pathnames are listed.
3647 option causes all hashed commands to be removed from the hash table.
3650 is searched as if it were a command name and added to the hash table if it is
3651 an executable command.
3658 Display information about the specified job(s); if no jobs are specified, all
3662 option causes information to be displayed only for jobs that have changed
3663 state since the last notification.
3666 option is used, the process ID of each process in a job is also listed.
3669 option causes only the process group of each job to be printed.
3672 below for the format of
3674 and the displayed job.
3678 .Oo Fl s Ar signame \*(Ba
3679 .No \- Ns Ar signum \*(Ba
3680 .No \- Ns Ar signame Oc
3681 .No { Ar job \*(Ba pid \*(Ba pgrp No }
3684 Send the specified signal to the specified jobs, process IDs or process
3686 If no signal is specified, the
3689 If a job is specified, the signal is sent to the job's process group.
3692 below for the format of
3698 .Op Ar exit-status ...
3700 Print the signal name corresponding to
3702 If no arguments are specified, a list of all the signals with their numbers
3703 and a short description of each are printed.
3705 .It Ic let Op Ar expression ...
3706 Each expression is evaluated (see
3707 .Sx Arithmetic expressions
3709 If all expressions are successfully evaluated, the exit status is 0 (1)
3710 if the last expression evaluated to non-zero (zero).
3711 If an error occurs during
3712 the parsing or evaluation of an expression, the exit status is greater than 1.
3713 Since expressions may need to be quoted,
3714 .No \&(( Ar expr No ))
3715 is syntactic sugar for
3716 .No "{ let '" Ns Ar expr Ns "'; }" .
3719 Internally used alias for
3735 Create a device special file.
3736 The file type may be
3738 (block type device),
3740 (character type device)
3743 .Pq named pipe , Tn FIFO .
3744 The file created may be modified according to its
3750 (major device number),
3753 (minor device number).
3754 This is not normally part of
3756 however, distributors may have added this as builtin as a speed hack.
3760 .Oo Fl AclNnprsu Ns Oo Ar n Oc \*(Ba
3764 Print the specified argument(s) on the standard output,
3765 separated by spaces, terminated with a newline.
3766 The C escapes mentioned in
3767 .Sx Backslash expansion
3770 which is equivalent to using the
3772 option, are interpreted.
3774 The options are as follows:
3779 is arithmetically evaluated; the character corresponding to the
3780 resulting value is printed.
3783 separate input words.
3785 The output is printed columnised, line by line, similar to how the
3787 utility, tab completion, the
3789 built-in utility and the
3793 Change the output word separator to newline.
3795 Change the output word and line separator to ASCII NUL.
3797 Do not print the trailing line separator.
3799 Print to the co-process (see
3803 Inhibit backslash expansion.
3805 Print to the history file instead of standard output.
3807 Print to the file descriptor
3808 .Ar n Pq defaults to 1 if omitted
3809 instead of standard output.
3814 option is used to emulate, to some degree, the
3817 command which does not process
3819 sequences unless the
3824 option suppresses the trailing newline.
3826 .It Ic printf Ar format Op Ar arguments ...
3828 Approximately the same as the
3830 utility, except it uses the same
3831 .Sx Backslash expansion
3832 and I/O code and does not handle floating point as the rest of
3834 An external utility is preferred over the builtin.
3835 This is not normally part of
3837 however, distributors may have added this as builtin as a speed hack.
3838 Do not use in new code.
3841 Print the present working directory.
3844 option is used or if the
3846 option isn't set (see the
3848 command below), the logical path is printed (i.e. the path used to
3850 to the current directory).
3853 option (physical path) is used or if the
3855 option is set, the path determined from the filesystem (by following
3857 directories to the root directory) is printed.
3871 Reads a line of input, separates the input into fields using the
3875 above), and assigns each field to the specified parameters
3877 If no parameters are specified, the
3879 parameter is used to store the result.
3884 options, only no or one parameter is accepted.
3885 If there are more parameters than fields, the extra parameters are set to
3886 the empty string or 0; if there are more fields than parameters, the last
3887 parameter is assigned the remaining fields (including the word separators).
3889 The options are as follows:
3890 .Bl -tag -width XuXnX
3892 Store the result into the parameter
3898 Store the result without word splitting into the parameter
3902 as array of characters (wide characters if the
3904 option is enacted, octets otherwise); the codepoints are
3905 encoded as decimal numbers by default.
3907 Use the first byte of
3910 if empty, instead of the ASCII newline character as input line delimiter.
3912 Instead of reading till end-of-line, read exactly
3915 Upon EOF, a partial read is returned with exit status 1.
3916 After timeout, a partial read is returned with an exit status as if
3920 Instead of reading till end-of-line, read up to
3922 bytes but return as soon as any bytes are read, e.g.\& from a
3923 slow terminal device, or if EOF or a timeout occurs.
3925 Read from the currently active co-process, see
3927 above for details on this.
3929 Read from the file descriptor
3931 (defaults to 0, i.e.\& standard input).
3932 The argument must immediately follow the option character.
3934 Interrupt reading after
3936 seconds (specified as positive decimal value with an optional fractional part).
3941 were caught if the timeout occurred, but partial reads may still be returned.
3943 Normally, the ASCII backslash character escapes the special
3944 meaning of the following character and is stripped from the input;
3946 does not stop when encountering a backslash-newline sequence and
3947 does not store that newline in the result.
3948 This option enables raw mode, in which backslashes are not processed.
3950 The input line is saved to the history.
3953 If the input is a terminal, both the
3957 options set it into raw mode;
3958 they read an entire file if \-1 is passed as
3962 The first parameter may have a question mark and a string appended to it, in
3963 which case the string is used as a prompt (printed to standard error before
3964 any input is read) if the input is a
3967 .Ic read nfoo?\*(aqnumber of foos: \*(aq ) .
3969 If no input is read or a timeout occurred,
3971 exits with a non-zero status.
3973 Another handy set of tricks:
3976 is run in a loop such as
3977 .Ic while read foo; do ...; done
3978 then leading whitespace will be removed (IFS) and backslashes processed.
3979 You might want to use
3980 .Ic while IFS= read \-r foo; do ...; done
3982 Similarly, when using the
3986 option might be prudent; the same applies for:
3987 .Bd -literal -offset indent
3988 find . \-type f \-print0 \*(Ba& \e
3989 while IFS= read \-d \*(aq\*(aq \-pr filename; do
3990 print \-r \-\- "found \*(Lt${filename#./}\*(Gt"
3994 The inner loop will be executed in a subshell and variable changes
3995 cannot be propagated if executed in a pipeline:
3996 .Bd -literal -offset indent
3997 bar \*(Ba baz \*(Ba while read foo; do ...; done
4000 Use co-processes instead:
4001 .Bd -literal -offset indent
4002 bar \*(Ba baz \*(Ba&
4003 while read \-p foo; do ...; done
4004 exec 3\*(Gt&p; exec 3\*(Gt&\-
4011 .Op Ns = Ns Ar value
4014 Sets the read-only attribute of the named parameters.
4015 If values are given,
4016 parameters are set to them before setting the attribute.
4018 made read-only, it cannot be unset and its value cannot be changed.
4020 If no parameters are specified, the names of all parameters with the read-only
4021 attribute are printed one per line, unless the
4023 option is used, in which case
4025 commands defining all read-only parameters, including their values, are
4033 Prints the resolved absolute pathname corresponding to
4039 it's also checked for existence and whether it is a directory; otherwise,
4041 returns 0 if the pathname either exists or can be created immediately,
4042 i.e. all but the last component exist and are directories.
4043 For calls from the shell, if any options are given, an external
4045 utility is preferred over the builtin.
4056 Both must be complete pathnames and on the same device.
4057 An external utility is preferred over this builtin,
4058 which is intended for emergency situations
4059 .Pq where Pa /bin/mv No becomes unusable
4063 .It Ic return Op Ar status
4064 Returns from a function or
4066 script, with exit status
4070 is given, the exit status of the last executed command is used.
4071 If used outside of a function or
4073 script, it has the same effect as
4077 treats both profile and
4081 scripts, while the original Korn shell only treats profiles as
4086 .Ic set Op Ic +\-abCefhiklmnprsUuvXx
4087 .Op Ic +\-o Ar option
4094 command can be used to set
4098 shell options, set the positional parameters, or set an array parameter.
4099 Options can be changed using the
4103 is the long name of an option, or using the
4104 .Cm +\- Ns Ar letter
4107 is the option's single letter name (not all options have a single letter name).
4108 The following table lists both option letters (if they exist) and long names
4109 along with a description of what the option does:
4112 Sets the elements of the array parameter
4118 is used, the array is reset (i.e. emptied) first; if
4120 is used, the first N elements are set (where N is the number of arguments);
4121 the rest are left untouched.
4123 An alternative syntax for the command
4124 .Ic set \-A foo \-\- a b c
4125 which is compatible to
4128 and also supported by
4132 .Ic foo=(a b c); foo+=(d e)
4133 .It Fl a \*(Ba Fl o Ic allexport
4134 All new parameters are created with the export attribute.
4135 .It Fl b \*(Ba Fl o Ic notify
4136 Print job notification messages asynchronously, instead of just before the
4138 Only used if job control is enabled
4140 .It Fl C \*(Ba Fl o Ic noclobber
4141 Prevent \*(Gt redirection from overwriting existing files.
4142 Instead, \*(Gt\*(Ba must be used to force an overwrite.
4143 Note that this is not safe to use for creation of temporary files or
4144 lockfiles due to a TOCTOU in a check allowing one to redirect output to
4146 or other device files even in
4149 .It Fl e \*(Ba Fl o Ic errexit
4150 Exit (after executing the
4152 trap) as soon as an error occurs or a command fails (i.e. exits with a
4154 This does not apply to commands whose exit status is
4155 explicitly tested by a shell construct such as
4166 only the status of the last command is tested.
4167 .It Fl f \*(Ba Fl o Ic noglob
4168 Do not expand file name patterns.
4169 .It Fl h \*(Ba Fl o Ic trackall
4170 Create tracked aliases for all executed commands (see
4173 Enabled by default for non-interactive shells.
4174 .It Fl i \*(Ba Fl o Ic interactive
4175 The shell is an interactive shell.
4176 This option can only be used when the shell is invoked.
4177 See above for a description of what this means.
4178 .It Fl k \*(Ba Fl o Ic keyword
4179 Parameter assignments are recognised anywhere in a command.
4180 .It Fl l \*(Ba Fl o Ic login
4181 The shell is a login shell.
4182 This option can only be used when the shell is invoked.
4183 See above for a description of what this means.
4184 .It Fl m \*(Ba Fl o Ic monitor
4185 Enable job control (default for interactive shells).
4186 .It Fl n \*(Ba Fl o Ic noexec
4187 Do not execute any commands.
4188 Useful for checking the syntax of scripts
4189 (ignored if interactive).
4190 .It Fl p \*(Ba Fl o Ic privileged
4191 The shell is a privileged shell.
4192 It is set automatically if, when the shell starts,
4193 the real UID or GID does not match
4194 the effective UID (EUID) or GID (EGID), respectively.
4195 See above for a description of what this means.
4196 .It Fl r \*(Ba Fl o Ic restricted
4197 The shell is a restricted shell.
4198 This option can only be used when the shell is invoked.
4199 See above for a description of what this means.
4200 .It Fl s \*(Ba Fl o Ic stdin
4201 If used when the shell is invoked, commands are read from standard input.
4202 Set automatically if the shell is invoked with no arguments.
4208 command it causes the specified arguments to be sorted before assigning them to
4209 the positional parameters (or to array
4214 .It Fl U \*(Ba Fl o Ic utf8\-mode
4215 Enable UTF-8 support in the
4216 .Sx Emacs editing mode
4217 and internal string handling functions.
4218 This flag is disabled by default, but can be enabled by setting it on the
4219 shell command line; is enabled automatically for interactive shells if
4220 requested at compile time, your system supports
4221 .Fn setlocale LC_CTYPE \&""
4223 .Fn nl_langinfo CODESET ,
4229 environment variables,
4230 and at least one of these returns something that matches
4234 case-insensitively; for direct builtin calls depending on the
4235 aforementioned environment variables; or for stdin or scripts,
4236 if the input begins with a UTF-8 Byte Order Mark.
4238 In near future, locale tracking will be implemented, which means that
4240 is changed whenever one of the
4242 locale-related environment variables changes.
4243 .It Fl u \*(Ba Fl o Ic nounset
4244 Referencing of an unset parameter, other than
4248 is treated as an error, unless one of the
4254 .It Fl v \*(Ba Fl o Ic verbose
4255 Write shell input to standard error as it is read.
4256 .It Fl X \*(Ba Fl o Ic markdirs
4257 Mark directories with a trailing
4259 during file name generation.
4260 .It Fl x \*(Ba Fl o Ic xtrace
4261 Print command trees when they are executed, preceded by
4265 Background jobs are run with lower priority.
4266 .It Fl o Ic braceexpand
4267 Enable brace expansion (a.k.a. alternation).
4268 This is enabled by default.
4269 If disabled, tilde expansion after an equals sign is disabled as a side effect.
4271 Enable BRL emacs-like command-line editing (interactive shells only); see
4272 .Sx Emacs editing mode .
4274 Enable gmacs-like command-line editing (interactive shells only).
4275 Currently identical to emacs editing except that transpose\-chars (\*(haT) acts
4276 slightly differently.
4277 .It Fl o Ic ignoreeof
4278 The shell will not (easily) exit when end-of-file is read;
4281 To avoid infinite loops, the shell will exit if
4283 is read 13 times in a row.
4284 .It Fl o Ic inherit\-xtrace
4287 upon entering functions.
4288 This is enabled by default.
4290 Do not kill running jobs with a
4292 signal when a login shell exits.
4293 Currently set by default, but this may
4294 change in the future to be compatible with
4298 doesn't have this option, but does send the
4303 In the original Korn shell, this prevents function definitions from
4304 being stored in the history file.
4305 .It Fl o Ic physical
4312 (i.e. the filesystem's)
4314 directories instead of
4316 directories (i.e. the shell handles
4318 which allows the user to be oblivious of symbolic links to directories).
4320 Note that setting this option does not affect the current value of the
4330 commands above for more details.
4331 .It Fl o Ic pipefail
4332 Make the exit status of a pipeline (before logically complementing) the
4333 rightmost non-zero errorlevel, or zero if all commands exited with zero.
4335 Behave closer to the standards
4339 Automatically enabled if the basename of the shell invocation begins with
4341 and this autodetection feature is compiled in
4343 As a side effect, setting this flag turns off
4345 mode, which can be turned back on manually, and
4347 mode (unless both are enabled at the same time).
4354 Automatically enabled if the basename of the shell invocation begins with
4356 and this autodetection feature is compiled in
4358 As a side effect, setting this flag turns off
4360 mode, which can be turned back on manually, and
4362 mode (unless both are enabled at the same time).
4366 command-line editing (interactive shells only).
4369 for documentation and limitations.
4370 .It Fl o Ic vi\-esccomplete
4371 In vi command-line editing, do command and file name completion when escape
4372 (\*(ha[) is entered in command mode.
4373 .It Fl o Ic vi\-tabcomplete
4374 In vi command-line editing, do command and file name completion when tab (\*(haI)
4375 is entered in insert mode.
4376 This is the default.
4379 In the original Korn shell, unless
4381 was set, the vi command-line mode would let the
4383 driver do the work until ESC (\*(ha[) was entered.
4385 is always in viraw mode.
4388 These options can also be used upon invocation of the shell.
4390 options (with single letter names) can be found in the parameter
4393 with no option name will list all the options and whether each is on or off;
4395 will print the long names of all options that are currently on.
4396 In a future version,
4400 compliant and print commands to restore the current options instead.
4402 Remaining arguments, if any, are positional parameters and are assigned, in
4403 order, to the positional parameters (i.e. $1, $2, etc.).
4406 and there are no remaining arguments, all positional parameters are cleared.
4407 If no options or arguments are given, the values of all names are printed.
4408 For unknown historical reasons, a lone
4410 option is treated specially \*(en it clears both the
4416 .It Ic shift Op Ar number
4417 The positional parameters
4420 etc. are renamed to 1, 2, etc.
4424 .It Ic sleep Ar seconds
4425 Suspends execution for a minimum of the
4427 specified as positive decimal value with an optional fractional part.
4428 Signal delivery may continue execution earlier.
4430 .It Ic source Ar file Op Ar arg ...
4432 .Ic \&. Po Do dot Dc Pc ,
4433 except that the current working directory is appended to the
4439 Stops the shell as if it had received the suspend character from
4441 It is not possible to suspend a login shell unless the parent process
4442 is a member of the same terminal session but is a member of a different
4444 As a general rule, if the shell was started by another shell or via
4446 it can be suspended.
4448 .It Ic test Ar expression
4449 .It Ic \&[ Ar expression Ic \&]
4453 and returns zero status if true, 1 if false, or greater than 1 if there
4455 It is normally used as the condition command of
4460 Symbolic links are followed for all
4467 The following basic expressions are available:
4474 is a block special device.
4477 is a character special device.
4489 group is the shell's effective group ID.
4492 mode has the setgid bit set.
4495 is a context dependent directory (only useful on HP-UX).
4509 owner is the shell's effective user ID.
4515 command above for a list of options).
4516 As a non-standard extension, if the option starts with a
4518 the test is negated; the test always fails if
4520 doesn't exist (so [ \-o foo \-o \-o !foo ] returns true if and only if option
4523 The same can be achieved with [ \-o ?foo ] like in
4527 can also be the short flag led by either
4531 .Pq no logical negation ,
4544 exists and is readable.
4548 .Xr unix 4 Ns -domain
4561 mode has the setuid bit set.
4564 exists and is writable.
4567 exists and is executable.
4568 .It Ar file1 Fl nt Ar file2
4577 .It Ar file1 Fl ot Ar file2
4586 .It Ar file1 Fl ef Ar file2
4592 has non-zero length.
4599 .It Ar string No = Ar string
4601 .It Ar string No == Ar string
4603 .It Ar string No \*(Gt Ar string
4604 First string operand is greater than second string operand.
4605 .It Ar string No \*(Lt Ar string
4606 First string operand is less than second string operand.
4607 .It Ar string No != Ar string
4608 Strings are not equal.
4609 .It Ar number Fl eq Ar number
4610 Numbers compare equal.
4611 .It Ar number Fl ne Ar number
4612 Numbers compare not equal.
4613 .It Ar number Fl ge Ar number
4614 Numbers compare greater than or equal.
4615 .It Ar number Fl gt Ar number
4616 Numbers compare greater than.
4617 .It Ar number Fl le Ar number
4618 Numbers compare less than or equal.
4619 .It Ar number Fl \< Ar number
4620 Numbers compare less than.
4623 The above basic expressions, in which unary operators have precedence over
4624 binary operators, may be combined with the following operators (listed in
4625 increasing order of precedence):
4626 .Bd -literal -offset indent
4627 expr \-o expr Logical OR.
4628 expr \-a expr Logical AND.
4633 Note that a number actually may be an arithmetic expression, such as
4634 a mathematical term or the name of an integer variable:
4635 .Bd -literal -offset indent
4636 x=1; [ "x" \-eq 1 ] evaluates to true
4639 Note that some special rules are applied (courtesy of
4641 ) if the number of arguments to
4643 or inside the brackets
4645 is less than five: if leading
4647 arguments can be stripped such that only one to three arguments remain,
4648 then the lowered comparison is executed; (thanks to XSI) parentheses
4650 lower four- and three-argument forms to two- and one-argument forms,
4651 respectively; three-argument forms ultimately prefer binary operations,
4652 followed by negation and parenthesis lowering; two- and four-argument forms
4653 prefer negation followed by parenthesis; the one-argument form always implies
4657 A common mistake is to use
4658 .Dq Li if \&[ $foo = bar \&]
4659 which fails if parameter
4661 is empty or unset, if it has embedded spaces (i.e.\&
4663 octets) or if it is a unary operator like
4668 .Dq Li if \&[ x\&"$foo\&" = x"bar" \&]
4669 instead, or the double-bracket operator
4670 .Dq Li if \&[[ $foo = bar \&]]
4671 or, to avoid pattern matching (see
4674 .Dq Li if \&[[ $foo = \&"$bar" \&]]
4678 construct is not only more secure to use but also often faster.
4687 is given, the times used to execute the pipeline are reported.
4689 is given, then the user and system time used by the shell itself, and all the
4690 commands it has run since it was started, are reported.
4691 The times reported are the real time (elapsed time from start to finish),
4692 the user CPU time (time spent running in user mode), and the system CPU time
4693 (time spent running in kernel mode).
4694 Times are reported to standard error; the format of the output is:
4696 .Dl "0m0.00s real 0m0.00s user 0m0.00s system"
4700 option is given the output is slightly longer:
4701 .Bd -literal -offset indent
4707 It is an error to specify the
4711 is a simple command.
4713 Simple redirections of standard error do not affect the output of the
4717 .Dl $ time sleep 1 2\*(Gtafile
4718 .Dl $ { time sleep 1; } 2\*(Gtafile
4720 Times for the first command do not go to
4722 but those of the second command do.
4725 Print the accumulated user and system times used both by the shell
4726 and by processes that the shell started which have exited.
4727 The format of the output is:
4728 .Bd -literal -offset indent
4733 .It Ic trap Ar n Op Ar signal ...
4734 If the first operand is a decimal unsigned integer, this resets all
4735 specified signals to the default action, i.e. is the same as calling
4741 followed by the arguments
4742 .Pq Ar n Op Ar signal ... ,
4743 all of which are treated as signals.
4745 .It Ic trap Op Ar handler signal ...
4746 Sets a trap handler that is to be executed when any of the specified
4750 is either an empty string, indicating the signals are to be ignored, a dash
4752 indicating that the default action is to be taken for the signals
4753 .Pq see Xr signal 3 ,
4754 or a string containing shell commands to be executed at the first opportunity
4755 (i.e. when the current command completes or before printing the next
4757 prompt) after receipt of one of the signals.
4759 is the name of a signal
4760 .Pq e.g.\& Dv PIPE or Dv ALRM
4761 or the number of the signal (see the
4765 There are two special signals:
4767 .Pq also known as 0 ,
4768 which is executed when the shell is about to exit, and
4770 which is executed after an error occurs; an error is something
4771 that would cause the shell to exit if the
4774 .Ic set Fl o Ic errexit
4777 handlers are executed in the environment of the last executed command.
4779 Note that, for non-interactive shells, the trap handler cannot be changed
4780 for signals that were ignored when the shell started.
4782 With no arguments, the current state of the traps that have been set since
4783 the shell started is shown as a series of
4786 Note that the output of
4788 cannot be usefully piped to another process (an artifact of the fact that
4789 traps are cleared when subprocesses are created).
4791 The original Korn shell's
4793 trap and the handling of
4797 traps in functions are not yet implemented.
4800 A command that exits with a zero value.
4804 .Oo Op Ic +\-alpnrtUux
4809 .No \*(Ba Fl f Op Fl tux Oc
4811 .Op Ns = Ns Ar value
4816 .Oo Op Ic +\-alpnrtUux
4817 .Op Fl LRZ Ns Op Ar n
4819 .No \*(Ba Fl f Op Fl tux Oc
4821 .Op Ns = Ns Ar value
4824 Display or set parameter attributes.
4827 arguments, parameter attributes are displayed; if no options are used, the
4828 current attributes of all parameters are printed as
4830 commands; if an option is given (or
4832 with no option letter), all parameters and their values with the specified
4833 attributes are printed; if options are introduced with
4835 parameter values are not printed.
4839 arguments are given, the attributes of the named parameters are set
4843 Values for parameters may optionally be specified.
4846 the change affects the entire array, and no value may be specified.
4850 is used inside a function, any parameters specified are localised.
4851 This is not done by the otherwise identical
4858 equivalent to other programming languages' as it does not allow a
4859 function called from another function to access a parameter at truly
4860 global scope, but only prevents putting an accessed one into local scope.
4866 operates on the attributes of functions.
4867 As with parameters, if no
4869 arguments are given,
4870 functions are listed with their values (i.e. definitions) unless
4871 options are introduced with
4873 in which case only the function names are reported.
4876 Indexed array attribute.
4879 Display or set functions and their attributes, instead of parameters.
4883 specifies the base to use when displaying the integer (if not specified, the
4884 base given in the first assignment is used).
4885 Parameters with this attribute may
4886 be assigned values containing arithmetic expressions.
4888 Left justify attribute.
4890 specifies the field width.
4893 is not specified, the current width of a parameter (or the width of its first
4894 assigned value) is used.
4895 Leading whitespace (and zeros, if used with the
4897 option) is stripped.
4898 If necessary, values are either truncated or space padded
4899 to fit the field width.
4901 Lower case attribute.
4902 All upper case ASCII characters in values are converted to lower case.
4903 (In the original Korn shell, this parameter meant
4909 Create a bound variable (name reference): any access to the variable
4911 will access the variable
4913 in the current scope (this is different from
4922 is lazily evaluated at the time
4925 This can be used by functions to access variables whose names are
4926 passed as parameters, instead of using
4931 commands that can be used to re-create the attributes and values of
4934 Right justify attribute.
4936 specifies the field width.
4939 is not specified, the current width of a parameter (or the width of its first
4940 assigned value) is used.
4941 Trailing whitespace is stripped.
4942 If necessary, values are either stripped of leading characters or space
4943 padded to make them fit the field width.
4945 Read-only attribute.
4946 Parameters with this attribute may not be assigned to or unset.
4947 Once this attribute is set, it cannot be turned off.
4950 Has no meaning to the shell; provided for application use.
4954 is the trace attribute.
4955 When functions with the trace attribute are executed, the
4958 shell option is temporarily turned on.
4960 Unsigned integer attribute.
4961 Integers are printed as unsigned values (combine with the
4964 This option is not in the original Korn shell.
4966 Upper case attribute.
4967 All lower case ASCII characters in values are converted to upper case.
4968 (In the original Korn shell, this parameter meant
4969 .Dq unsigned integer
4972 option which meant upper case letters would never be used for bases greater
4980 is the undefined attribute.
4983 above for the implications of this.
4986 Parameters (or functions) are placed in the environment of
4987 any executed commands.
4988 Exported functions are not yet implemented.
4990 Zero fill attribute.
4991 If not combined with
4995 except zero padding is used instead of space padding.
4996 For integers, the number instead of the base is padded.
5009 options are changed, all others from this set are cleared,
5010 unless they are also given on the same command line.
5014 .Op Fl aBCcdefHilMmnOPpqrSsTtVvw
5017 Display or set process limits.
5018 If no options are used, the file size limit
5022 if specified, may be either an arithmetic expression or the word
5024 The limits affect the shell and any processes created by the shell after a
5026 Note that some systems may not allow limits to be increased
5028 Also note that the types of limits available are system
5029 dependent \*(en some systems have only the
5034 Display all limits; unless
5036 is used, soft limits are displayed.
5038 Set the socket buffer size to
5042 Set the number of cached threads to
5045 Impose a size limit of
5047 blocks on the size of core dumps.
5049 Impose a size limit of
5051 kibibytes on the size of the data area.
5053 Set the maximum niceness to
5056 Impose a size limit of
5058 blocks on files written by the shell and its child processes (files of any
5061 Set the hard limit only (the default is to set both hard and soft limits).
5063 Set the number of pending signals to
5068 kibibytes on the amount of locked (wired) physical memory.
5070 Set the AIO locked memory to
5076 kibibytes on the amount of physical memory used.
5080 file descriptors that can be open at once.
5082 Set the number of AIO operations to
5085 Limit the number of threads per process to
5090 processes that can be run by the user at any one time.
5098 Set the maximum real-time priority to
5101 Set the soft limit only (the default is to set both hard and soft limits).
5103 Impose a size limit of
5105 kibibytes on the size of the stack area.
5107 Impose a time limit of
5109 real seconds to be used by each process.
5111 Impose a time limit of
5113 CPU seconds spent in user mode to be used by each process.
5115 Set the number of vnode monitors on Haiku to
5120 kibibytes on the amount of virtual memory (address space) used.
5124 kibibytes on the amount of swap space used.
5129 is concerned, a block is 512 bytes.
5136 Display or set the file permission creation mask or umask (see
5140 option is used, the mask displayed or set is symbolic; otherwise, it is an
5143 Symbolic masks are like those used by
5145 When used, they describe what permissions may be made available (as opposed to
5146 octal masks in which a set bit means the corresponding bit is to be cleared).
5149 sets the mask so files will not be readable, writable or executable by
5151 and is equivalent (on most systems) to the octal mask
5159 The aliases for the given names are removed.
5162 option is used, all aliases are removed.
5167 options are used, the indicated operations are carried out on tracked or
5168 directory aliases, respectively.
5175 Unset the named parameters
5183 .Ar parameter Ns \&[*] ,
5184 attributes are kept, only values are unset.
5186 The exit status is non-zero if any of the parameters have the read-only
5187 attribute set, zero otherwise.
5189 .It Ic wait Op Ar job ...
5190 Wait for the specified job(s) to finish.
5193 is that of the last specified job; if the last job is killed by a signal, the
5194 exit status is 128 + the number of the signal (see
5195 .Ic kill Fl l Ar exit-status
5196 above); if the last specified job can't be found (because it never existed or
5197 had already finished), the exit status of
5202 below for the format of
5205 will return if a signal for which a trap has been set is received or if a
5212 If no jobs are specified,
5214 waits for all currently running jobs (if any) to finish and exits with a zero
5216 If job monitoring is enabled, the completion status of jobs is printed
5217 (this is not the case when jobs are explicitly specified).
5226 option, it is the same as
5228 except aliases are not printed as alias command.
5231 option, it is exactly the same as
5235 option differs: the search path is not affected in
5237 but the search is restricted to the path.
5240 Job control refers to the shell's ability to monitor and control jobs which
5241 are processes or groups of processes created for commands or pipelines.
5242 At a minimum, the shell keeps track of the status of the background (i.e.\&
5243 asynchronous) jobs that currently exist; this information can be displayed
5247 If job control is fully enabled (using
5250 .Ic set Fl o Ic monitor ) ,
5251 as it is for interactive shells, the processes of a job are placed in their
5253 Foreground jobs can be stopped by typing the suspend
5254 character from the terminal (normally \*(haZ), jobs can be restarted in either the
5255 foreground or background using the
5259 commands, and the state of the terminal is saved or restored when a foreground
5260 job is stopped or restarted, respectively.
5262 Note that only commands that create processes (e.g. asynchronous commands,
5263 subshell commands and non-built-in, non-function commands) can be stopped;
5268 When a job is created, it is assigned a job number.
5269 For interactive shells, this number is printed inside
5271 followed by the process IDs of the processes in the job when an asynchronous
5273 A job may be referred to in the
5280 commands either by the process ID of the last process in the command pipeline
5283 parameter) or by prefixing the job number with a percent sign
5285 Other percent sequences can also be used to refer to jobs:
5286 .Bl -tag -width "%+ x %% x %XX"
5287 .It %+ \*(Ba %% \*(Ba %
5288 The most recently stopped job or, if there are no stopped jobs, the oldest
5291 The job that would be the
5293 job if the latter did not exist.
5295 The job with job number
5298 The job with its command containing the string
5300 (an error occurs if multiple jobs are matched).
5302 The job with its command starting with the string
5304 (an error occurs if multiple jobs are matched).
5307 When a job changes state (e.g. a background job finishes or foreground job is
5308 stopped), the shell prints the following status information:
5310 .D1 [ Ns Ar number ] Ar flag status command
5313 .Bl -tag -width "command"
5315 is the job number of the job;
5321 character if the job is the
5325 job, respectively, or space if it is neither;
5327 indicates the current state of the job and can be:
5328 .Bl -tag -width "RunningXX"
5329 .It Done Op Ar number
5332 is the exit status of the job which is omitted if the status is zero.
5334 The job has neither stopped nor exited (note that running does not necessarily
5335 mean consuming CPU time \*(en
5336 the process could be blocked waiting for some event).
5337 .It Stopped Op Ar signal
5338 The job was stopped by the indicated
5340 (if no signal is given, the job was stopped by
5342 .It Ar signal-description Op Dq core dumped
5343 The job was killed by a signal (e.g. memory fault, hangup); use
5345 for a list of signal descriptions.
5348 message indicates the process created a core file.
5351 is the command that created the process.
5352 If there are multiple processes in
5353 the job, each process will have a line showing its
5357 if it is different from the status of the previous process.
5360 When an attempt is made to exit the shell while there are jobs in the stopped
5361 state, the shell warns the user that there are stopped jobs and does not exit.
5362 If another attempt is immediately made to exit the shell, the stopped jobs are
5365 signal and the shell exits.
5368 option is not set and there are running jobs when an attempt is made to exit
5369 a login shell, the shell warns the user and does not exit.
5371 is immediately made to exit the shell, the running jobs are sent a
5373 signal and the shell exits.
5376 .Ic set Fl o Ic posix
5381 compliant in places where the defaults or opinions differ.
5384 will still operate with unsigned 32-bit arithmetic; use
5386 if arithmetic on the host
5388 data type, complete with ISO C Undefined Behaviour, is required;
5391 manual page for details.
5392 Most other historic,
5394 .Nm ksh Ns -compatible
5395 or opinionated differences can be disabled by using this mode; these are:
5401 .Ic &\*(Gt Ns Ar file
5402 is no longer supported.
5404 File descriptors created by I/O redirections are inherited by
5407 Numbers with a leading digit zero are interpreted as octal.
5411 builtin does not interpret backslashes and only supports the exact option
5414 \&... (list is incomplete and may change for R54)
5417 Compatibility mode; intended for use with legacy scripts that
5418 cannot easily be fixed; the changes are as follows:
5424 .Ic &\*(Gt Ns Ar file
5425 is no longer supported.
5427 File descriptors created by I/O redirections are inherited by
5432 builtin does not interpret backslashes and only supports the exact option
5435 The substitution operations
5445 .Pf ## Ar pat No } ,
5461 wrongly do not require a parenthesis to be escaped and do not parse extglobs.
5463 \&... (list is incomplete and may change for R54)
5465 .Ss Interactive input line editing
5466 The shell supports three modes of reading command lines from a
5468 in an interactive session, controlled by the
5473 options (at most one of these can be set at once).
5476 Editing modes can be set explicitly using the
5479 If none of these options are enabled,
5480 the shell simply reads lines using the normal
5487 option is set, the shell allows emacs-like editing of the command; similarly,
5490 option is set, the shell allows vi-like editing of the command.
5491 These modes are described in detail in the following sections.
5493 In these editing modes, if a line is longer than the screen width (see the
5501 character is displayed in the last column indicating that there are more
5502 characters after, before and after, or before the current position,
5504 The line is scrolled horizontally as necessary.
5506 Completed lines are pushed into the history, unless they begin with an
5507 IFS octet or IFS white space or are the same as the previous line.
5508 .Ss Emacs editing mode
5511 option is set, interactive input line editing is enabled.
5512 Warning: This mode is
5513 slightly different from the emacs mode in the original Korn shell.
5514 In this mode, various editing commands
5515 (typically bound to one or more control characters) cause immediate actions
5516 without waiting for a newline.
5517 Several editing commands are bound to particular
5518 control characters when the shell is invoked; these bindings can be changed
5523 The following is a list of available editing commands.
5524 Each description starts with the name of the command,
5525 suffixed with a colon;
5528 (if the command can be prefixed with a count); and any keys the command is
5529 bound to by default, written using caret notation
5530 e.g. the ASCII ESC character is written as \*(ha[.
5531 These control sequences are not case sensitive.
5532 A count prefix for a command is entered using the sequence
5533 .Pf \*(ha[ Ns Ar n ,
5536 is a sequence of 1 or more digits.
5537 Unless otherwise specified, if a count is
5538 omitted, it defaults to 1.
5540 Note that editing command names are used only with the
5543 Furthermore, many editing commands are useful only on terminals with
5550 reasonable substitutes and override the default bindings;
5551 their customary values are shown in parentheses below.
5552 The default bindings were chosen to resemble corresponding
5556 .No INTR Pq \*(haC ,
5559 Abort the current command, empty the line buffer and
5560 set the exit state to interrupted.
5561 .It auto\-insert: Op Ar n
5562 Simply causes the character to appear as literal input.
5563 Most ordinary characters are bound to this.
5564 .It Xo backward\-char:
5566 .No \*(haB , \*(haXD , ANSI-CurLeft , PC-CurLeft
5568 Moves the cursor backward
5571 .It Xo backward\-word:
5573 .No \*(ha[b , ANSI-Ctrl-CurLeft , ANSI-Alt-CurLeft
5575 Moves the cursor backward to the beginning of the word; words consist of
5576 alphanumerics, underscore
5581 .It beginning\-of\-history: \*(ha[\*(Lt
5582 Moves to the beginning of the history.
5583 .It beginning\-of\-line: \*(haA, ANSI-Home, PC-Home
5584 Moves the cursor to the beginning of the edited input line.
5585 .It Xo capitalise\-word:
5587 .No \*(ha[C , \*(ha[c
5589 Uppercase the first ASCII character in the next
5591 words, leaving the cursor past the end of the last word.
5592 .It clear\-screen: \*(ha[\*(haL
5593 Prints a compile-time configurable sequence to clear the screen and home
5594 the cursor, redraws the entire prompt and the currently edited input line.
5595 The default sequence works for almost all standard terminals.
5596 .It comment: \*(ha[#
5597 If the current line does not begin with a comment character, one is added at
5598 the beginning of the line and the line is entered (as if return had been
5599 pressed); otherwise, the existing comment characters are removed and the cursor
5600 is placed at the beginning of the line.
5601 .It complete: \*(ha[\*(ha[
5602 Automatically completes as much as is unique of the command name or the file
5603 name containing the cursor.
5604 If the entire remaining command or file name is
5605 unique, a space is printed after its completion, unless it is a directory name
5609 If there is no command or file name with the current partial word
5610 as its prefix, a bell character is output (usually causing a beep to be
5612 .It complete\-command: \*(haX\*(ha[
5613 Automatically completes as much as is unique of the command name having the
5614 partial word up to the cursor as its prefix, as in the
5617 .It complete\-file: \*(ha[\*(haX
5618 Automatically completes as much as is unique of the file name having the
5619 partial word up to the cursor as its prefix, as in the
5621 command described above.
5622 .It complete\-list: \*(haI, \*(ha[=
5623 Complete as much as is possible of the current word
5624 and list the possible completions for it.
5625 If only one completion is possible,
5629 Note that \*(haI is usually generated by the TAB (tabulator) key.
5630 .It Xo delete\-char\-backward:
5632 .No ERASE Pq \*(haH ,
5637 characters before the cursor.
5638 .It Xo delete\-char\-forward:
5640 .No ANSI-Del , PC-Del
5644 characters after the cursor.
5645 .It Xo delete\-word\-backward:
5647 .No Pfx1+ERASE Pq \*(ha[\*(haH ,
5648 .No WERASE Pq \*(haW ,
5649 .No \*(ha[\*(ha? , \*(ha[\*(haH , \*(ha[h
5653 words before the cursor.
5654 .It Xo delete\-word\-forward:
5658 Deletes characters after the cursor up to the end of
5661 .It Xo down\-history:
5663 .No \*(haN , \*(haXB , ANSI-CurDown , PC-CurDown
5665 Scrolls the history buffer forward
5668 Each input line originally starts just after the last entry
5669 in the history buffer, so
5671 is not useful until either
5672 .Ic search\-history ,
5673 .Ic search\-history\-up
5677 .It Xo downcase\-word:
5679 .No \*(ha[L , \*(ha[l
5690 or the current line, if not specified, interactively.
5691 The actual command executed is
5692 .Ic fc \-e ${VISUAL:\-${EDITOR:\-vi}} Ar n .
5693 .It end\-of\-history: \*(ha[\*(Gt
5694 Moves to the end of the history.
5695 .It end\-of\-line: \*(haE, ANSI-End, PC-End
5696 Moves the cursor to the end of the input line.
5698 Acts as an end-of-file; this is useful because edit-mode input disables
5699 normal terminal input canonicalisation.
5700 .It Xo eot\-or\-delete:
5704 If alone on a line, same as
5707 .Ic delete\-char\-forward .
5708 .It error: (not bound)
5709 Error (ring the bell).
5710 .It evaluate\-region: \*(ha[\*(haE
5711 Evaluates the text between the mark and the cursor position
5712 .Pq the entire line if no mark is set
5713 as function substitution (if it cannot be parsed, the editing state is
5714 unchanged and the bell is rung to signal an error); $? is updated accordingly.
5715 .It exchange\-point\-and\-mark: \*(haX\*(haX
5716 Places the cursor where the mark is and sets the mark to where the cursor was.
5717 .It expand\-file: \*(ha[*
5720 to the current word and replaces the word with the result of performing file
5721 globbing on the word.
5722 If no files match the pattern, the bell is rung.
5723 .It Xo forward\-char:
5725 .No \*(haF , \*(haXC , ANSI-CurRight , PC-CurRight
5727 Moves the cursor forward
5730 .It Xo forward\-word:
5732 .No \*(ha[f , ANSI-Ctrl-CurRight , ANSI-Alt-CurRight
5734 Moves the cursor forward to the end of the
5737 .It Xo goto\-history:
5741 Goes to history number
5746 Deletes the entire input line.
5747 If Ctrl-U should only delete the line up to the cursor, use:
5749 .D1 $ bind \-m \*(haU='\*(ha[0\*(haK'
5750 .It kill\-region: \*(haW
5751 Deletes the input between the cursor and the mark.
5752 .It Xo kill\-to\-eol:
5756 Deletes the input from the cursor to the end of the line if
5758 is not specified; otherwise deletes characters between the cursor and column
5761 Prints a sorted, columnated list of command names or file names (if any) that
5762 can complete the partial word containing the cursor.
5763 Directory names have
5766 .It list\-command: \*(haX?
5767 Prints a sorted, columnated list of command names (if any) that can complete
5768 the partial word containing the cursor.
5769 .It list\-file: \*(haX\*(haY
5770 Prints a sorted, columnated list of file names (if any) that can complete the
5771 partial word containing the cursor.
5772 File type indicators are appended as described under
5775 .It newline: \*(haJ , \*(haM
5776 Causes the current input line to be processed by the shell.
5777 The current cursor position may be anywhere on the line.
5778 .It newline\-and\-next: \*(haO
5779 Causes the current input line to be processed by the shell, and the next line
5780 from history becomes the current line.
5781 This is only useful after an
5785 .Ic search\-history\-up .
5790 .It prefix\-1: \*(ha[
5791 Introduces a 2-character command sequence.
5792 .It prefix\-2: \*(haX , \*(ha[[ , \*(ha[O
5793 Introduces a multi-character command sequence.
5794 .It Xo prev\-hist\-word:
5796 .No \*(ha[. , \*(ha[_
5798 The last word or, if given, the
5800 word (zero-based) of the previous (on repeated execution, second-last,
5801 third-last, etc.) command is inserted at the cursor.
5802 Use of this editing command trashes the mark.
5803 .It quote: \*(ha\*(ha , \*(haV
5804 The following character is taken literally rather than as an editing command.
5806 Reprints the last line of the prompt string and the current input line
5808 .It Xo search\-character\-backward:
5812 Search backward in the current line for the
5814 occurrence of the next character typed.
5815 .It Xo search\-character\-forward:
5819 Search forward in the current line for the
5821 occurrence of the next character typed.
5822 .It search\-history: \*(haR
5823 Enter incremental search mode.
5824 The internal history list is searched
5825 backwards for commands matching the input.
5828 in the search string anchors the search.
5829 The escape key will leave search mode.
5830 Other commands, including sequences of escape as
5836 key will be executed after leaving search mode.
5839 command will restore the input line before search started.
5842 commands continue searching backward to the next previous occurrence of the
5844 The history buffer retains only a finite number of lines; the oldest
5845 are discarded as necessary.
5846 .It search\-history\-up: ANSI-PgUp, PC-PgUp
5847 Search backwards through the history buffer for commands whose beginning match
5848 the portion of the input line before the cursor.
5849 When used on an empty line, this has the same effect as
5851 .It search\-history\-down: ANSI-PgDn, PC-PgDn
5852 Search forwards through the history buffer for commands whose beginning match
5853 the portion of the input line before the cursor.
5854 When used on an empty line, this has the same effect as
5856 This is only useful after an
5860 .Ic search\-history\-up .
5861 .It set\-mark\-command: \*(ha[ Ns Aq space
5862 Set the mark at the cursor position.
5863 .It transpose\-chars: \*(haT
5864 If at the end of line or, if the
5866 option is set, this exchanges the two previous characters; otherwise, it
5867 exchanges the previous and current characters and moves the cursor one
5868 character to the right.
5871 .No \*(haP , \*(haXA , ANSI-CurUp , PC-CurUp
5873 Scrolls the history buffer backward
5876 .It Xo upcase\-word:
5878 .No \*(ha[U , \*(ha[u
5883 .It version: \*(ha[\*(haV
5884 Display the version of
5886 The current edit buffer is restored as soon as a key is pressed.
5887 The restoring keypress is processed, unless it is a space.
5889 Inserts the most recently killed text string at the current cursor position.
5890 .It yank\-pop: \*(ha[y
5893 replaces the inserted text string with the next previously killed text string.
5896 The tab completion escapes characters the same way as the following code:
5898 print \-nr \-\- "${x@/[\e"\-\e$\e&\-*:\-?[\e\e\e\`{\-\e}${IFS\-$\*(aq \et\en\*(aq}]/\e\e$KSH_MATCH}"
5902 The vi command-line editing mode is orphaned, yet still functional.
5903 It is 8-bit clean but specifically does not support UTF-8 or MBCS.
5905 The vi command-line editor in
5907 has basically the same commands as the
5909 editor with the following exceptions:
5912 You start out in insert mode.
5914 There are file name and command completion commands:
5915 =, \e, *, \*(haX, \*(haE, \*(haF and, optionally,
5922 command is different (in
5924 it is the last argument command; in
5926 it goes to the start of the current line).
5932 commands move in the opposite direction to the
5936 Commands which don't make sense in a single line editor are not available
5937 (e.g. screen movement commands and
5946 there are two modes:
5951 In insert mode, most characters are simply put in the buffer at the
5952 current cursor position as they are typed; however, some characters are
5954 In particular, the following characters are taken from current
5959 and have their usual meaning (normal values are in parentheses): kill (\*(haU),
5960 erase (\*(ha?), werase (\*(haW), eof (\*(haD), intr (\*(haC) and quit (\*(ha\e).
5962 the above, the following characters are also treated specially in insert mode:
5963 .Bl -tag -width XJXXXXM
5965 Command and file name enumeration (see below).
5967 Command and file name completion (see below).
5968 If used twice in a row, the
5969 list of possible completions is displayed; if used a third time, the completion
5972 Erases previous character.
5973 .It \*(haJ \*(Ba \*(haM
5975 The current line is read, parsed and executed by the shell.
5978 The next character typed is not treated specially (can be used
5979 to insert the characters being described here).
5981 Command and file name expansion (see below).
5983 Puts the editor in command mode (see below).
5985 Optional file name and command completion (see
5987 above), enabled with
5988 .Ic set Fl o Ic vi\-tabcomplete .
5991 In command mode, each character is interpreted as a command.
5993 don't correspond to commands, are illegal combinations of commands, or are
5994 commands that can't be carried out, all cause beeps.
5995 In the following command descriptions, an
5997 indicates the command may be prefixed by a number (e.g.\&
5999 moves right 10 characters); if no number prefix is used,
6001 is assumed to be 1 unless otherwise specified.
6003 .Dq current position
6004 refers to the position between the cursor and the character preceding the
6008 is a sequence of letters, digits and underscore characters or a sequence of
6009 non-letter, non-digit, non-underscore and non-whitespace characters (e.g.\&
6011 contains two words) and a
6013 is a sequence of non-whitespace characters.
6019 The following commands are not in, or are different from, the normal vi file
6025 Insert a space followed by the
6027 big-word from the last command in the history at the current position and enter
6030 is not specified, the last word is inserted.
6032 Insert the comment character
6034 at the start of the current line and return the line to the shell (equivalent
6044 is not specified, it goes to the most recent remembered line.
6054 is not specified, the current line is edited.
6055 The actual command executed is
6056 .Ic fc \-e ${VISUAL:\-${EDITOR:\-vi}} Ar n .
6058 Command or file name expansion is applied to the current big-word (with an
6061 if the word contains no file globbing characters) \*(en the big-word is replaced
6062 with the resulting words.
6063 If the current big-word is the first on the line
6064 or follows one of the characters
6071 and does not contain a slash
6073 then command expansion is done; otherwise file name expansion is done.
6074 Command expansion will match the big-word against all aliases, functions and
6075 built-in commands as well as any executable files found by searching the
6079 File name expansion matches the big-word against the files in the
6081 After expansion, the cursor is placed just past the last
6082 word and the editor is in insert mode.
6085 .Oo Ar n Oc Ns \*(haF ,
6086 .Oo Ar n Oc Ns Aq tab ,
6088 .Oo Ar n Oc Ns Aq esc
6090 Command/file name completion.
6091 Replace the current big-word with the
6092 longest unique match obtained after performing command and file name expansion.
6094 is only recognised if the
6096 option is set, while
6098 is only recognised if the
6106 possible completion is selected (as reported by the command/file name
6107 enumeration command).
6109 Command/file name enumeration.
6110 List all the commands or files that match the current big-word.
6112 Display the version of
6114 The current edit buffer is restored as soon as a key is pressed.
6115 The restoring keypress is ignored.
6118 Execute the commands found in the alias
6122 Intra-line movement commands:
6125 .Oo Ar n Oc Ns h and
6126 .Oo Ar n Oc Ns \*(haH
6132 .Oo Ar n Oc Ns l and
6133 .Oo Ar n Oc Ns Aq space
6141 Move to the first non-whitespace character.
6143 .Oo Ar n Oc Ns \*(Ba
6148 Move to the last character.
6164 Move forward to the end of the word,
6170 Move forward to the end of the big-word,
6187 The editor looks forward for the nearest parenthesis, bracket or
6188 brace and then moves the cursor to the matching parenthesis, bracket or brace.
6190 .Oo Ar n Oc Ns f Ns Ar c
6194 occurrence of the character
6197 .Oo Ar n Oc Ns F Ns Ar c
6199 Move backward to the
6201 occurrence of the character
6204 .Oo Ar n Oc Ns t Ns Ar c
6206 Move forward to just before the
6208 occurrence of the character
6211 .Oo Ar n Oc Ns T Ns Ar c
6213 Move backward to just before the
6215 occurrence of the character
6232 command, but moves in the opposite direction.
6235 Inter-line movement commands:
6241 .Oo Ar n Oc Ns \*(haN
6245 next line in the history.
6250 .Oo Ar n Oc Ns \*(haP
6254 previous line in the history.
6262 is not specified, the number of the first remembered line is used.
6270 is not specified, it goes to the most recent remembered line.
6272 .Oo Ar n Oc Ns / Ns Ar string
6274 Search backward through the history for the
6282 the remainder of the string must appear at the start of the history line for
6285 .Oo Ar n Oc Ns \&? Ns Ar string
6289 except it searches forward through the history.
6295 occurrence of the last search string;
6296 the direction of the search is the same as the last search.
6302 occurrence of the last search string;
6303 the direction of the search is the opposite of the last search.
6304 .It Ar ANSI-CurUp , PC-PgUp
6305 Take the characters from the beginning of the line to the current
6306 cursor position as search string and do a backwards history search
6307 for lines beginning with this string; keep the cursor position.
6308 This works only in insert mode and keeps it enabled.
6318 times; goes into insert mode just after the current position.
6320 only replicated if command mode is re-entered i.e.\&
6328 except it appends at the end of the line.
6334 times; goes into insert mode at the current position.
6335 The insertion is only
6336 replicated if command mode is re-entered i.e.\&
6344 except the insertion is done just before the first non-blank character.
6350 characters (i.e. delete the characters and go into insert mode).
6352 Substitute whole line.
6353 All characters from the first non-blank character to the
6354 end of the line are deleted and insert mode is entered.
6356 .Oo Ar n Oc Ns c Ns Ar move-cmd
6358 Change from the current position to the position resulting from
6360 (i.e. delete the indicated region and go into insert mode); if
6364 the line starting from the first non-blank character is changed.
6366 Change from the current position to the end of the line (i.e. delete to the
6367 end of the line and go into insert mode).
6381 Delete to the end of the line.
6383 .Oo Ar n Oc Ns d Ns Ar move-cmd
6385 Delete from the current position to the position resulting from
6386 .Ar n move-cmd Ns s ;
6388 is a movement command (see above) or
6390 in which case the current line is deleted.
6392 .Oo Ar n Oc Ns r Ns Ar c
6396 characters with the character
6402 Enter insert mode but overwrite existing characters instead of
6403 inserting before existing characters.
6404 The replacement is repeated
6408 .Oo Ar n Oc Ns \*(TI
6410 Change the case of the next
6414 .Oo Ar n Oc Ns y Ns Ar move-cmd
6416 Yank from the current position to the position resulting from
6418 into the yank buffer; if
6422 the whole line is yanked.
6424 Yank from the current position to the end of the line.
6428 Paste the contents of the yank buffer just after the current position,
6436 except the buffer is pasted at the current position.
6439 Miscellaneous vi commands
6441 .It \*(haJ and \*(haM
6442 The current line is read, parsed and executed by the shell.
6443 .It \*(haL and \*(haR
6444 Redraw the current line.
6448 Redo the last edit command
6452 Undo the last edit command.
6454 Undo all changes that have been made to the current line.
6455 .It PC Home, End, Del and cursor keys
6456 They move as expected, both in insert and command mode.
6457 .It Ar intr No and Ar quit
6458 The interrupt and quit terminal characters cause the current line to be
6459 deleted and a new prompt to be printed.
6462 .Bl -tag -width XetcXsuid_profile -compact
6463 .It Pa \*(TI/.mkshrc
6464 User mkshrc profile (non-privileged interactive shells); see
6466 The location can be changed at compile time (for embedded systems);
6467 AOSP Android builds use
6468 .Pa /system/etc/mkshrc .
6469 .It Pa \*(TI/.profile
6470 User profile (non-privileged login shells); see
6472 near the top of this manual.
6474 System profile (login shells); see
6478 .It Pa /etc/suid_profile
6479 Suid profile (privileged shells); see
6485 contains the system and suid profile.
6517 .Pa https://www.mirbsd.org/ksh\-chan.htm
6520 .%B "The KornShell Command and Programming Language"
6522 .%I "Prentice Hall PTR"
6523 .%P "xvi\ +\ 356 pages"
6524 .%O "ISBN 978\-0\-13\-516972\-8 (0\-13\-516972\-0)"
6527 .%A Morris I. Bolsky
6529 .%B "The New KornShell Command and Programming Language (2nd Edition)"
6531 .%I "Prentice Hall PTR"
6532 .%P "xvi\ +\ 400 pages"
6533 .%O "ISBN 978\-0\-13\-182700\-4 (0\-13\-182700\-6)"
6536 .%A Stephen G. Kochan
6538 .%B "\\*(tNUNIX\\*(sP Shell Programming"
6542 .%P "xiii\ +\ 437 pages"
6543 .%O "ISBN 978\-0\-672\-32490\-1 (0\-672\-32490\-3)"
6547 .%T "\\*(tNIEEE\\*(sP Standard for Information Technology \*(en Portable Operating System Interface (POSIX)"
6548 .%V "Part 2: Shell and Utilities"
6551 .%P "xvii\ +\ 1195 pages"
6552 .%O "ISBN 978\-1\-55937\-255\-8 (1\-55937\-255\-9)"
6556 .%B "Learning the Korn Shell"
6560 .%O "ISBN 978\-1\-56592\-054\-5 (1\-56592\-054\-6)"
6565 .%B "Learning the Korn Shell, Second Edition"
6569 .%O "ISBN 978\-0\-596\-00195\-7 (0\-596\-00195\-9)"
6573 .%B "KornShell Programming Tutorial"
6575 .%I "Addison-Wesley Professional"
6576 .%P "xxi\ +\ 324 pages"
6577 .%O "ISBN 978\-0\-201\-56324\-5 (0\-201\-56324\-X)"
6581 .Nm "The MirBSD Korn Shell"
6583 .An mirabilos Aq Mt m@mirbsd.org
6584 as part of The MirOS Project.
6585 This shell is based on the public domain 7th edition Bourne shell clone by
6586 .An Charles Forsyth ,
6587 who kindly agreed to, in countries where the Public Domain status of the work
6588 may not be valid, grant a copyright licence to the general public to deal in
6589 the work without restriction and permission to sublicence derivatives under
6590 the terms of any (OSI approved) Open Source licence,
6591 and parts of the BRL shell by
6595 .An Arnold Robbins ,
6598 The first release of
6602 and it was subsequently maintained by
6603 .An John R. MacMillan ,
6604 .An Simon J. Gerraty
6606 .An Michael Rendell .
6607 The effort of several projects, such as Debian and OpenBSD, and other
6608 contributors including our users, to improve the shell is appreciated.
6609 See the documentation, web site and CVS for details.
6611 The BSD daemon is Copyright \(co Marshall Kirk McKusick.
6612 The complete legalese is at:
6613 .Pa https://www.mirbsd.org/TaC\-mksh.txt
6615 .\" This boils down to: feel free to use mksh.ico as application icon
6616 .\" or shortcut for mksh or mksh/Win32 or OS/2; distro patches are ok
6617 .\" (but we request they amend $KSH_VERSION when modifying mksh).
6618 .\" Authors are Marshall Kirk McKusick (UCB), Rick Collette (ekkoBSD),
6619 .\" mirabilos, Benny Siegert (MirBSD), Michael Langguth (mksh/Win32),
6620 .\" KO Myung-Hun (mksh for OS/2).
6622 .\" As far as MirBSD is concerned, the files themselves are free
6623 .\" to modification and distribution under BSD/MirOS Licence, the
6624 .\" restriction on use stems only from trademark law's requirement
6625 .\" to protect it or lose it, which McKusick almost did.
6629 has a different scope model from
6632 which leads to subtle differences in semantics for identical builtins.
6633 This can cause issues with a
6635 to suddenly point to a local variable by accident; fixing this is hard.
6637 The parts of a pipeline, like below, are executed in subshells.
6638 Thus, variable assignments inside them are not visible in the
6639 surrounding execution environment.
6640 Use co-processes instead.
6641 .Bd -literal -offset indent
6642 foo \*(Ba bar \*(Ba read baz # will not change $baz
6643 foo \*(Ba bar \*(Ba& read \-p baz # will, however, do so
6647 provides a consistent 32-bit integer arithmetic implementation, both
6648 signed and unsigned, with sign of the result of a remainder operation
6649 and wraparound defined, even (defying POSIX) on 36-bit and 64-bit systems.
6652 provides a consistent, clear interface normally.
6653 This may deviate from POSIX in historic or opinionated places.
6654 .Ic set Fl o Ic posix
6658 will cause the shell to behave more conformant.
6668 only supports the Unicode BMP (Basic Multilingual Plane) and maps
6669 raw octets into the U+EF80..U+EFFF wide character range; compare
6670 .Sx Arithmetic expressions .
6676 option dependent on the current
6678 locale for mksh to allow using the UTF-8 mode, within the constraints
6679 outlined above, in code portable across various shell implementations:
6680 .Bd -literal -offset indent
6681 case ${KSH_VERSION:\-} in
6682 *MIRBSD\ KSH*\*(Ba*LEGACY\ KSH*)
6683 case ${LC_ALL:\-${LC_CTYPE:\-${LANG:\-}}} in
6684 *[Uu][Tt][Ff]8*\*(Ba*[Uu][Tt][Ff]\-8*) set \-U ;;
6689 In near future, (Unicode) locale tracking will be implemented though.
6691 Suspending (using \*(haZ) pipelines like the one below will only suspend
6692 the currently running part of the pipeline; in this example,
6694 is immediately printed on suspension (but not later after an
6696 .Bd -literal -offset indent
6697 $ /bin/sleep 666 && echo fubar
6700 The truncation process involved when changing
6702 does not free old history entries (leaks memory) and leaks
6703 old entries into the new history if their line numbers are
6704 not overwritten by same-number entries from the persistent
6705 history file; truncating the on-disc file to
6707 lines has always been broken and prone to history file corruption
6708 when multiple shells are accessing the file; the rollover process
6709 for the in-memory portion of the history is slow, should use
6712 This document attempts to describe
6715 .\" with vendor patches from insert-your-name-here,
6716 compiled without any options impacting functionality, such as
6720 which, on some systems only, enables
6721 .Ic set Fl o Ic posix
6724 automatically (whose behaviour differs across targets),
6725 for an operating environment supporting all of its advanced needs.
6727 Please report bugs in
6732 .Aq Mt miros\-mksh@mirbsd.org
6737 .Pa irc.freenode.net
6738 .Pq Port 6697 SSL, 6667 unencrypted ,
6740 .Pa https://launchpad.net/mksh