summaryrefslogtreecommitdiffstats
path: root/man-pages-posix-2017/man1p/sh.1p
blob: dd1821d7c14379f9d9cae7bc8d1bd482df12bbae (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
'\" et
.TH SH "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
sh
\(em shell, the standard command language interpreter
.SH SYNOPSIS
.LP
.nf
sh \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
    \fB[\fIcommand_file \fB[\fIargument\fR...\fB]]\fR
.P
sh -c \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
    \fIcommand_string \fB[\fIcommand_name \fB[\fIargument\fR...\fB]]\fR
.P
sh -s \fB[\fR-abCefhimnuvx\fB] [\fR-o \fIoption\fB]\fR... \fB[\fR+abCefhimnuvx\fB] [\fR+o \fIoption\fB]\fR...
    \fB[\fIargument\fR...\fB]\fR
.fi
.SH DESCRIPTION
The
.IR sh
utility is a command language interpreter that shall execute commands
read from a command line string, the standard input, or a specified
file. The application shall ensure that the commands to be executed are
expressed in the language described in
.IR "Chapter 2" ", " "Shell Command Language".
.P
Pathname expansion shall not fail due to the size of a file.
.P
Shell input and output redirections have an implementation-defined
offset maximum that is established in the open file description.
.SH OPTIONS
The
.IR sh
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines",
with an extension for support of a leading
<plus-sign>
(\c
.BR '\(pl' )
as noted below.
.P
The
.BR \-a ,
.BR \-b ,
.BR \-C ,
.BR \-e ,
.BR \-f ,
.BR \-m ,
.BR \-n ,
.BR \-o
.IR option ,
.BR \-u ,
.BR \-v ,
and
.BR \-x
options are described as part of the
.IR set
utility in
.IR "Section 2.14" ", " "Special Built-In Utilities".
The option letters derived from the
.IR set
special built-in shall also be accepted with a leading
<plus-sign>
(\c
.BR '\(pl' )
instead of a leading
<hyphen-minus>
(meaning the reverse case of the option as described in this volume of POSIX.1\(hy2017).
.P
The following additional options shall be supported:
.IP "\fB\-c\fP" 10
Read commands from the
.IR command_string
operand. Set the value of special parameter 0 (see
.IR "Section 2.5.2" ", " "Special Parameters")
from the value of the
.IR command_name
operand and the positional parameters ($1, $2, and so on) in sequence
from the remaining
.IR argument
operands. No commands shall be read from the standard input.
.IP "\fB\-i\fP" 10
Specify that the shell is
.IR interactive ;
see below. An implementation may treat specifying the
.BR \-i
option as an error if the real user ID of the calling process does not
equal the effective user ID or if the real group ID does not equal the
effective group ID.
.IP "\fB\-s\fP" 10
Read commands from the standard input.
.P
If there are no operands and the
.BR \-c
option is not specified, the
.BR \-s
option shall be assumed.
.P
If the
.BR \-i
option is present, or if there are no operands and the shell's standard
input and standard error are attached to a terminal, the shell is
considered to be
.IR interactive .
.SH OPERANDS
The following operands shall be supported:
.IP "\fR\-\fR" 10
A single
<hyphen-minus>
shall be treated as the first operand and then ignored. If both
.BR '\-' 
and
.BR \(dq--\(dq 
are given as arguments, or if other operands precede the single
<hyphen-minus>,
the results are undefined.
.IP "\fIargument\fR" 10
The positional parameters ($1, $2, and so on) shall be set to
.IR arguments ,
if any.
.IP "\fIcommand_file\fR" 10
The pathname of a file containing commands. If the pathname contains
one or more
<slash>
characters, the implementation attempts to read that file; the file need
not be executable. If the pathname does not contain a
<slash>
character:
.RS 10 
.IP " *" 4
The implementation shall attempt to read that file from the current
working directory; the file need not be executable.
.IP " *" 4
If the file is not in the current working directory, the implementation
may perform a search for an executable file using the value of
.IR PATH ,
as described in
.IR "Section 2.9.1.1" ", " "Command Search and Execution".
.P
Special parameter 0 (see
.IR "Section 2.5.2" ", " "Special Parameters")
shall be set to the value of
.IR command_file .
If
.IR sh
is called using a synopsis form that omits
.IR command_file ,
special parameter 0 shall be set to the value of the first argument
passed to
.IR sh
from its parent (for example,
.IR argv [0]
for a C program), which is normally a pathname used to execute the
.IR sh
utility.
.RE
.IP "\fIcommand_name\fR" 10
.br
A string assigned to special parameter 0 when executing the commands in
.IR command_string .
If
.IR command_name
is not specified, special parameter 0 shall be set to the value of the
first argument passed to
.IR sh
from its parent (for example,
.IR argv [0]
for a C program), which is normally a pathname used to execute the
.IR sh
utility.
.IP "\fIcommand_string\fR" 10
.br
A string that shall be interpreted by the shell as one or more
commands, as if the string were the argument to the
\fIsystem\fR()
function defined in the System Interfaces volume of POSIX.1\(hy2017. If the
.IR command_string
operand is an empty string,
.IR sh
shall exit with a zero exit status.
.SH STDIN
The standard input shall be used only if one of the following is true:
.IP " *" 4
The
.BR \-s
option is specified.
.IP " *" 4
The
.BR \-c
option is not specified and no operands are specified.
.IP " *" 4
The script executes one or more commands that require input from
standard input (such as a
.IR read
command that does not redirect its input).
.P
See the INPUT FILES section.
.P
When the shell is using standard input and it invokes a command that
also uses standard input, the shell shall ensure that the standard
input file pointer points directly after the command it has read when
the command begins execution. It shall not read ahead in such a manner
that any characters intended to be read by the invoked command are
consumed by the shell (whether interpreted by the shell or not) or that
characters that are not read by the invoked command are not seen by the
shell. When the command expecting to read standard input is started
asynchronously by an interactive shell, it is unspecified whether
characters are read by the command or interpreted by the shell.
.P
If the standard input to
.IR sh
is a FIFO or terminal device and is set to non-blocking reads, then
.IR sh
shall enable blocking reads on standard input. This shall remain in
effect when the command completes.
.SH "INPUT FILES"
The input file shall be a text file, except that line lengths shall be
unlimited. If the input file consists solely of zero or more blank lines
and comments,
.IR sh
shall exit with a zero exit status.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR sh :
.IP "\fIENV\fP" 10
This variable, when and only when an interactive shell is invoked,
shall be subjected to parameter expansion (see
.IR "Section 2.6.2" ", " "Parameter Expansion")
by the shell, and the resulting value shall be used as a pathname of a
file containing shell commands to execute in the current environment.
The file need not be executable. If the expanded value of
.IR ENV
is not an absolute pathname, the results are unspecified.
.IR ENV
shall be ignored if the real and effective user IDs or real and
effective group IDs of the process are different.
.IP "\fIFCEDIT\fP" 10
This variable, when expanded by the shell, shall determine the default
value for the
.BR \-e
.IR editor
option's
.IR editor
option-argument. If
.IR FCEDIT
is null or unset,
.IR ed
shall be used as the editor.
.IP "\fIHISTFILE\fP" 10
Determine a pathname naming a command history file. If the
.IR HISTFILE
variable is not set, the shell may attempt to access or create a file
.BR .sh_history
in the directory referred to by the
.IR HOME
environment variable. If the shell cannot obtain both read and
write access to, or create, the history file, it shall use an
unspecified mechanism that allows the history to operate properly.
(References to history ``file'' in this section shall be understood to
mean this unspecified mechanism in such cases.) An implementation may
choose to access this variable only when initializing the history file;
this initialization shall occur when
.IR fc
or
.IR sh
first attempt to retrieve entries from, or add entries to, the file, as
the result of commands issued by the user, the file named by the
.IR ENV
variable, or implementation-defined system start-up files.
Implementations may choose to disable the history list mechanism for
users with appropriate privileges who do not set
.IR HISTFILE ;
the specific circumstances under which this occurs are
implementation-defined. If more than one instance of the shell is
using the same history file, it is unspecified how updates to the
history file from those shells interact. As entries are deleted from
the history file, they shall be deleted oldest first. It is
unspecified when history file entries are physically removed from the
history file.
.IP "\fIHISTSIZE\fP" 10
Determine a decimal number representing the limit to the number of
previous commands that are accessible. If this variable is unset, an
unspecified default greater than or equal to 128 shall be used. The
maximum number of commands in the history list is unspecified, but
shall be at least 128. An implementation may choose to access this
variable only when initializing the history file, as described under
.IR HISTFILE .
Therefore, it is unspecified whether changes made to
.IR HISTSIZE
after the history file has been initialized are effective.
.IP "\fIHOME\fP" 10
Determine the pathname of the user's home directory. The contents of
.IR HOME
are used in tilde expansion as described in
.IR "Section 2.6.1" ", " "Tilde Expansion".
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
for the precedence of internationalization variables used to determine
the values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_COLLATE\fP" 10
.br
Determine the behavior of range expressions, equivalence classes, and
multi-character collating elements within pattern matching.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of
text data as characters (for example, single-byte as opposed to
multi-byte characters in arguments and input files), which characters
are defined as letters (character class
.BR alpha ),
and the behavior of character classes within pattern matching.
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale that should be used to affect the format and
contents of diagnostic messages written to standard error.
.IP "\fIMAIL\fP" 10
Determine a pathname of the user's mailbox file for purposes of
incoming mail notification. If this variable is set, the shell shall
inform the user if the file named by the variable is created or if its
modification time has changed. Informing the user shall be accomplished
by writing a string of unspecified format to standard error prior to
the writing of the next primary prompt string. Such check shall be
performed only after the completion of the interval defined by the
.IR MAILCHECK
variable after the last such check. The user shall be informed only if
.IR MAIL
is set and
.IR MAILPATH
is not set.
.IP "\fIMAILCHECK\fP" 10
.br
Establish a decimal integer value that specifies how often (in seconds)
the shell shall check for the arrival of mail in the files specified by
the
.IR MAILPATH
or
.IR MAIL
variables. The default value shall be 600 seconds. If set to zero,
the shell shall check before issuing each primary prompt.
.IP "\fIMAILPATH\fP" 10
Provide a list of pathnames and optional messages separated by
<colon>
characters. If this variable is set, the shell shall inform the user if
any of the files named by the variable are created or if any of their
modification times change. (See the preceding entry for
.IR MAIL
for descriptions of mail arrival and user informing.) Each pathname can
be followed by
.BR '%' 
and a string that shall be subjected to parameter expansion and written
to standard error when the modification time changes. If a
.BR '%' 
character in the pathname is preceded by a
<backslash>,
it shall be treated as a literal
.BR '%' 
in the pathname. The default message is unspecified.
.RS 10 
.P
The
.IR MAILPATH
environment variable takes precedence over the
.IR MAIL
variable.
.RE
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fIPATH\fP" 10
Establish a string formatted as described in the Base Definitions volume of POSIX.1\(hy2017,
.IR "Chapter 8" ", " "Environment Variables",
used to effect command interpretation; see
.IR "Section 2.9.1.1" ", " "Command Search and Execution".
.IP "\fIPWD\fP" 10
This variable shall represent an absolute pathname of the current
working directory. Assignments to this variable may be ignored.
.SH "ASYNCHRONOUS EVENTS"
The
.IR sh
utility shall take the standard action for all signals (see
.IR "Section 1.4" ", " "Utility Description Defaults")
with the following exceptions.
.P
If the shell is interactive, SIGINT signals received during command
line editing shall be handled as described in the EXTENDED DESCRIPTION,
and SIGINT signals received at other times shall be caught but no action
performed.
.br
.P
If the shell is interactive:
.IP " *" 4
SIGQUIT and SIGTERM signals shall be ignored.
.IP " *" 4
If the
.BR \-m
option is in effect, SIGTTIN, SIGTTOU, and SIGTSTP signals shall be
ignored.
.IP " *" 4
If the
.BR \-m
option is not in effect, it is unspecified whether SIGTTIN, SIGTTOU,
and SIGTSTP signals are ignored, set to the default action, or caught.
If they are caught, the shell shall, in the signal-catching function,
set the signal to the default action and raise the signal (after taking
any appropriate steps, such as restoring terminal settings).
.P
The standard actions, and the actions described above for interactive
shells, can be overridden by use of the
.IR trap
special built-in utility (see
.IR "\fItrap\fR\^"
and
.IR "Section 2.11" ", " "Signals and Error Handling").
.SH STDOUT
See the STDERR section.
.SH STDERR
Except as otherwise stated (by the descriptions of any invoked
utilities or in interactive mode), standard error shall be used
only for diagnostic messages.
.SH "OUTPUT FILES"
None.
.SH "EXTENDED DESCRIPTION"
See
.IR "Chapter 2" ", " "Shell Command Language".
The functionality described in the rest of the EXTENDED DESCRIPTION
section shall be provided on implementations that support the User
Portability Utilities option
(and the rest of this section is not further shaded for this option).
.SS "Command History List"
.P
When the
.IR sh
utility is being used interactively, it shall maintain a list of
commands previously entered from the terminal in the file named by the
.IR HISTFILE
environment variable. The type, size, and internal format of this file
are unspecified. Multiple
.IR sh
processes can share access to the file for a user, if file access
permissions allow this; see the description of the
.IR HISTFILE
environment variable.
.SS "Command Line Editing"
.P
When
.IR sh
is being used interactively from a terminal, the current command and
the command history (see
.IR "\fIfc\fR\^")
can be edited using
.IR vi -mode
command line editing. This mode uses commands, described below,
similar to a subset of those described in the
.IR vi
utility. Implementations may offer other command line editing modes
corresponding to other editing utilities.
.P
The command
.IR set
.BR \-o
.IR vi
shall enable
.IR vi -mode
editing and place
.IR sh
into
.IR vi
insert mode (see
.IR "Command Line Editing (vi-mode)").
This command also shall disable any other editing mode that the
implementation may provide. The command
.IR set
.BR +o
.IR vi
disables
.IR vi -mode
editing.
.P
Certain block-mode terminals may be unable to support shell command
line editing. If a terminal is unable to provide either edit mode, it
need not be possible to
.IR set
.BR \-o
.IR vi
when using the shell on this terminal.
.P
In the following sections, the characters
.IR erase ,
.IR interrupt ,
.IR kill ,
and
.IR end-of-file
are those set by the
.IR stty
utility.
.SS "Command Line Editing (vi-mode)"
.P
In
.IR vi
editing mode, there shall be a distinguished line, the edit line. All
the editing operations which modify a line affect the edit line. The
edit line is always the newest line in the command history buffer.
.P
With
.IR vi -mode
enabled,
.IR sh
can be switched between insert mode and command mode.
.P
When in insert mode, an entered character shall be inserted into the
command line, except as noted in
.IR "vi Line Editing Insert Mode".
Upon entering
.IR sh
and after termination of the previous command,
.IR sh
shall be in insert mode.
.P
Typing an escape character shall switch
.IR sh
into command mode (see
.IR "vi Line Editing Command Mode").
In command mode, an entered character shall either invoke a defined
operation, be used as part of a multi-character operation, or be
treated as an error. A character that is not recognized as part of an
editing command shall terminate any specific editing command and shall
alert the terminal. If
.IR sh
receives a SIGINT signal in command mode (whether generated by typing the
.IR interrupt
character or by other means), it shall terminate command line editing
on the current command line, reissue the prompt on the next line of the
terminal, and reset the command history (see
.IR "\fIfc\fR\^")
so that the most recently executed command is the previous command
(that is, the command that was being edited when it was interrupted is
not re-entered into the history).
.P
In the following sections, the phrase ``move the cursor to the
beginning of the word'' shall mean ``move the cursor to the first
character of the current word'' and the phrase ``move the cursor to the
end of the word'' shall mean ``move the cursor to the last character of
the current word''. The phrase ``beginning of the command line''
indicates the point between the end of the prompt string issued by the
shell (or the beginning of the terminal line, if there is no prompt
string) and the first character of the command text.
.SS "vi Line Editing Insert Mode"
.P
While in insert mode, any character typed shall be inserted in the
current command line, unless it is from the following set.
.IP <newline> 10
Execute the current command line. If the current command line is not
empty, this line shall be entered into the command history (see
.IR "\fIfc\fR\^").
.IP "\fIerase\fR" 10
Delete the character previous to the current cursor position and move
the current cursor position back one character. In insert mode,
characters shall be erased from both the screen and the buffer when
backspacing.
.IP "\fIinterrupt\fR" 10
If
.IR sh
receives a SIGINT signal in insert mode (whether generated by typing
the
.IR interrupt
character or by other means), it shall terminate command line editing
with the same effects as described for interrupting command mode; see
.IR "Command Line Editing (vi-mode)".
.IP "\fIkill\fR" 10
Clear all the characters from the input line.
.IP "<control>\(hyV" 10
Insert the next character input, even if the character is otherwise a
special insert mode character.
.IP "<control>\(hyW" 10
Delete the characters from the one preceding the cursor to the
preceding word boundary. The word boundary in this case is the closer
to the cursor of either the beginning of the line or a character that
is in neither the
.BR blank
nor
.BR punct
character classification of the current locale.
.IP "\fIend-of-file\fR" 10
Interpreted as the end of input in
.IR sh .
This interpretation shall occur only at the beginning of an input
line. If
.IR end-of-file
is entered other than at the beginning of the line, the results are
unspecified.
.IP <ESC> 10
Place
.IR sh
into command mode.
.SS "vi Line Editing Command Mode"
.P
In command mode for the command line editing feature, decimal digits
not beginning with 0 that precede a command letter shall be
remembered. Some commands use these decimal digits as a count number
that affects the operation.
.P
The term
.IR "motion command"
represents one of the commands:
.sp
.RS 4
.nf

<space>  0  b  F  l  W  \(ha  $  ;  E  f  T  w  |  ,  B  e  h  t
.fi
.P
.RE
.P
If the current line is not the edit line, any command that modifies the
current line shall cause the content of the current line to replace the
content of the edit line, and the current line shall become the edit
line. This replacement cannot be undone (see the
.BR u
and
.BR U
commands below). The modification requested shall then be performed to
the edit line. When the current line is the edit line, the modification
shall be done directly to the edit line.
.P
Any command that is preceded by
.IR count
shall take a count (the numeric value of any preceding decimal
digits). Unless otherwise noted, this count shall cause the specified
operation to repeat by the number of times specified by the count.
Also unless otherwise noted, a
.IR count
that is out of range is considered an error condition and shall alert
the terminal, but neither the cursor position, nor the command line,
shall change.
.P
The terms
.IR word
and
.IR bigword
are used as defined in the
.IR vi
description. The term
.IR "save buffer"
corresponds to the term
.IR "unnamed buffer"
in
.IR vi .
.P
The following commands shall be recognized in command mode:
.IP <newline> 10
Execute the current command line. If the current command line is not
empty, this line shall be entered into the command history (see
.IR "\fIfc\fR\^").
.IP "<control>\(hyL" 10
Redraw the current command line. Position the cursor at the same
location on the redrawn line.
.IP "\fB#\fP" 10
Insert the character
.BR '#' 
at the beginning of the current command line and treat the resulting
edit line as a comment. This line shall be entered into the command
history; see
.IR "\fIfc\fR\^".
.IP "\fB=\fP" 10
Display the possible shell word expansions (see
.IR "Section 2.6" ", " "Word Expansions")
of the bigword at the current command line position.
.RS 10 
.TP 10
.BR Note:
This does not modify the content of the current line, and therefore
does not cause the current line to become the edit line.
.P
.P
These expansions shall be displayed on subsequent terminal lines. If
the bigword contains none of the characters
.BR '?' ,
.BR '*' ,
or
.BR '[' ,
an
<asterisk>
(\c
.BR '*' )
shall be implicitly assumed at the end. If any directories are
matched, these expansions shall have a
.BR '/' 
character appended. After the expansion, the line shall be redrawn,
the cursor repositioned at the current cursor position, and
.IR sh
shall be placed in command mode.
.RE
.IP "\fB\e\fR" 10
Perform pathname expansion (see
.IR "Section 2.6.6" ", " "Pathname Expansion")
on the current bigword, up to the largest set of characters that can be
matched uniquely. If the bigword contains none of the characters
.BR '?' ,
.BR '*' ,
or
.BR '[' ,
an
<asterisk>
(\c
.BR '*' )
shall be implicitly assumed at the end. This maximal expansion then
shall replace the original bigword in the command line, and the cursor
shall be placed after this expansion. If the resulting bigword
completely and uniquely matches a directory, a
.BR '/' 
character shall be inserted directly after the bigword. If some other
file is completely matched, a single
<space>
shall be inserted after the bigword. After this operation,
.IR sh
shall be placed in insert mode.
.IP "\fB*\fR" 10
Perform pathname expansion on the current bigword and insert all
expansions into the command to replace the current bigword, with each
expansion separated by a single
<space>.
If at the end of the line, the current cursor position shall be moved
to the first column position following the expansions and
.IR sh
shall be placed in insert mode. Otherwise, the current cursor position
shall be the last column position of the first character after the
expansions and
.IR sh
shall be placed in insert mode. If the current bigword contains none
of the characters
.BR '?' ,
.BR '*' ,
or
.BR '[' ,
before the operation, an
<asterisk>
(\c
.BR '*' )
shall be implicitly assumed at the end.
.IP "\fB@\fIletter\fR" 10
Insert the value of the alias named
.IR _letter .
The symbol
.IR letter
represents a single alphabetic character from the portable character
set; implementations may support additional characters as an
extension. If the alias
.IR _letter
contains other editing commands, these commands shall be performed as
part of the insertion. If no alias
.IR _letter
is enabled, this command shall have no effect.
.IP "\fB[\fIcount\fB]~\fR" 10
Convert, if the current character is a lowercase letter, to the
equivalent uppercase letter and
.IR "vice versa" ,
as prescribed by the current locale. The current cursor position then
shall be advanced by one character. If the cursor was positioned on
the last character of the line, the case conversion shall occur, but
the cursor shall not advance. If the
.BR '\(ti' 
command is preceded by a
.IR count ,
that number of characters shall be converted, and the cursor shall be
advanced to the character position after the last character converted.
If the
.IR count
is larger than the number of characters after the cursor, this shall
not be considered an error; the cursor shall advance to the last
character on the line.
.IP "\fB[\fIcount\fB].\fR" 10
Repeat the most recent non-motion command, even if it was executed on
an earlier command line. If the previous command was preceded by a
.IR count ,
and no count is given on the
.BR '.' 
command, the count from the previous command shall be included as part
of the repeated command. If the
.BR '.' 
command is preceded by a
.IR count ,
this shall override any
.IR count
argument to the previous command. The
.IR count
specified in the
.BR '.' 
command shall become the count for subsequent
.BR '.' 
commands issued without a count.
.IP "\fB[\fInumber\fB]v\fR" 10
Invoke the
.IR vi
editor to edit the current command line in a temporary file. When the
editor exits, the commands in the temporary file shall be executed and
placed in the command history. If a
.IR number
is included, it specifies the command number in the command history to
be edited, rather than the current command line.
.IP "\fB[\fIcount\fB]l\fR\0\0\0(ell)" 10
.sp -0.5v
.IP "\fB[\fIcount\fB]\fR<space>" 10
.br
Move the current cursor position to the next character position. If
the cursor was positioned on the last character of the line, the
terminal shall be alerted and the cursor shall not be advanced. If the
.IR count
is larger than the number of characters after the cursor, this shall
not be considered an error; the cursor shall advance to the last
character on the line.
.IP "\fB[\fIcount\fB]h\fR" 10
Move the current cursor position to the
.IR count th
(default 1) previous character position. If the cursor was positioned
on the first character of the line, the terminal shall be alerted and
the cursor shall not be moved. If the count is larger than the number
of characters before the cursor, this shall not be considered an error;
the cursor shall move to the first character on the line.
.IP "\fB[\fIcount\fB]w\fR" 10
Move to the start of the next word. If the cursor was positioned on
the last character of the line, the terminal shall be alerted and the
cursor shall not be advanced. If the
.IR count
is larger than the number of words after the cursor, this shall not be
considered an error; the cursor shall advance to the last character on
the line.
.IP "\fB[\fIcount\fB]W\fR" 10
Move to the start of the next bigword. If the cursor was positioned on
the last character of the line, the terminal shall be alerted and the
cursor shall not be advanced. If the
.IR count
is larger than the number of bigwords after the cursor, this shall not
be considered an error; the cursor shall advance to the last character
on the line.
.IP "\fB[\fIcount\fB]e\fR" 10
Move to the end of the current word. If at the end of a word, move to
the end of the next word. If the cursor was positioned on the last
character of the line, the terminal shall be alerted and the cursor
shall not be advanced. If the
.IR count
is larger than the number of words after the cursor, this shall not be
considered an error; the cursor shall advance to the last character on
the line.
.IP "\fB[\fIcount\fB]E\fR" 10
Move to the end of the current bigword. If at the end of a bigword,
move to the end of the next bigword. If the cursor was positioned on
the last character of the line, the terminal shall be alerted and the
cursor shall not be advanced. If the
.IR count
is larger than the number of bigwords after the cursor, this shall not
be considered an error; the cursor shall advance to the last character
on the line.
.IP "\fB[\fIcount\fB]b\fR" 10
Move to the beginning of the current word. If at the beginning of a
word, move to the beginning of the previous word. If the cursor was
positioned on the first character of the line, the terminal shall be
alerted and the cursor shall not be moved. If the
.IR count
is larger than the number of words preceding the cursor, this shall not
be considered an error; the cursor shall return to the first character
on the line.
.IP "\fB[\fIcount\fB]B\fR" 10
Move to the beginning of the current bigword. If at the beginning of a
bigword, move to the beginning of the previous bigword. If the cursor
was positioned on the first character of the line, the terminal shall
be alerted and the cursor shall not be moved. If the
.IR count
is larger than the number of bigwords preceding the cursor, this shall
not be considered an error; the cursor shall return to the first
character on the line.
.IP "\fB^\fR" 10
Move the current cursor position to the first character on the input
line that is not a
<blank>.
.IP "\fB$\fR" 10
Move to the last character position on the current command line.
.IP "\fB0\fR" 10
(Zero.) Move to the first character position on the current command
line.
.IP "\fB[\fIcount\fB]\||\fR" 10
Move to the
.IR count th
character position on the current command line. If no number is
specified, move to the first position. The first character position
shall be numbered 1. If the count is larger than the number of
characters on the line, this shall not be considered an error; the
cursor shall be placed on the last character on the line.
.IP "\fB[\fIcount\fB]f\fIc\fR" 10
Move to the first occurrence of the character
.BR 'c' 
that occurs after the current cursor position. If the cursor was
positioned on the last character of the line, the terminal shall be
alerted and the cursor shall not be advanced. If the character
.BR 'c' 
does not occur in the line after the current cursor position, the
terminal shall be alerted and the cursor shall not be moved.
.IP "\fB[\fIcount\fB]F\fIc\fR" 10
Move to the first occurrence of the character
.BR 'c' 
that occurs before the current cursor position. If the cursor was
positioned on the first character of the line, the terminal shall be
alerted and the cursor shall not be moved. If the character
.BR 'c' 
does not occur in the line before the current cursor position, the
terminal shall be alerted and the cursor shall not be moved.
.IP "\fB[\fIcount\fB]t\fIc\fR" 10
Move to the character before the first occurrence of the character
.BR 'c' 
that occurs after the current cursor position. If the cursor was
positioned on the last character of the line, the terminal shall be
alerted and the cursor shall not be advanced. If the character
.BR 'c' 
does not occur in the line after the current cursor position, the
terminal shall be alerted and the cursor shall not be moved.
.IP "\fB[\fIcount\fB]T\fIc\fR" 10
Move to the character after the first occurrence of the character
.BR 'c' 
that occurs before the current cursor position. If the cursor was
positioned on the first character of the line, the terminal shall be
alerted and the cursor shall not be moved. If the character
.BR 'c' 
does not occur in the line before the current cursor position, the
terminal shall be alerted and the cursor shall not be moved.
.IP "\fB[\fIcount\fB];\fR" 10
Repeat the most recent
.BR f ,
.BR F ,
.BR t ,
or
.BR T
command. Any number argument on that previous command shall be
ignored. Errors are those described for the repeated command.
.IP "\fB[\fIcount\fB],\fR" 10
Repeat the most recent
.BR f ,
.BR F ,
.BR t ,
or
.BR T
command. Any number argument on that previous command shall be
ignored. However, reverse the direction of that command.
.IP "\fBa\fR" 10
Enter insert mode after the current cursor position. Characters that
are entered shall be inserted before the next character.
.IP "\fBA\fR" 10
Enter insert mode after the end of the current command line.
.IP "\fBi\fR" 10
Enter insert mode at the current cursor position. Characters that are
entered shall be inserted before the current character.
.IP "\fBI\fR" 10
Enter insert mode at the beginning of the current command line.
.IP "\fBR\fR" 10
Enter insert mode, replacing characters from the command line beginning
at the current cursor position.
.IP "\fB[\fIcount\fB]c\fImotion\fR" 10
.br
Delete the characters between the current cursor position and the
cursor position that would result from the specified motion
command. Then enter insert mode before the first character following
any deleted characters. If
.IR count
is specified, it shall be applied to the motion command. A
.IR count
shall be ignored for the following motion commands:
.RS 10 
.sp
.RS 4
.nf

0    \(ha    $    c
.fi
.P
.RE
.P
If the motion command is the character
.BR 'c' ,
the current command line shall be cleared and insert mode shall be
entered. If the motion command would move the current cursor position
toward the beginning of the command line, the character under the
current cursor position shall not be deleted. If the motion command
would move the current cursor position toward the end of the command
line, the character under the current cursor position shall be deleted.
If the
.IR count
is larger than the number of characters between the current cursor
position and the end of the command line toward which the motion
command would move the cursor, this shall not be considered an error;
all of the remaining characters in the aforementioned range shall be
deleted and insert mode shall be entered. If the motion command is
invalid, the terminal shall be alerted, the cursor shall not be moved,
and no text shall be deleted.
.RE
.IP "\fBC\fR" 10
Delete from the current character to the end of the line and enter
insert mode at the new end-of-line.
.IP "\fBS\fR" 10
Clear the entire edit line and enter insert mode.
.IP "\fB[\fIcount\fB]r\fIc\fR" 10
Replace the current character with the character
.BR 'c' .
With a number
.IR count ,
replace the current and the following
.IR count \-1
characters. After this command, the current cursor position shall be
on the last character that was changed. If the
.IR count
is larger than the number of characters after the cursor, this shall
not be considered an error; all of the remaining characters shall be
changed.
.IP "\fB[\fIcount\fB]_\fR" 10
Append a
<space>
after the current character position and then append the last bigword
in the previous input line after the
<space>.
Then enter insert mode after the last character just appended. With a
number
.IR count ,
append the
.IR count th
bigword in the previous line.
.IP "\fB[\fIcount\fB]x\fR" 10
Delete the character at the current cursor position and place the
deleted characters in the save buffer. If the cursor was positioned on
the last character of the line, the character shall be deleted and the
cursor position shall be moved to the previous character (the new last
character). If the
.IR count
is larger than the number of characters after the cursor, this shall
not be considered an error; all the characters from the cursor to the
end of the line shall be deleted.
.IP "\fB[\fIcount\fB]X\fR" 10
Delete the character before the current cursor position and place the
deleted characters in the save buffer. The character under the current
cursor position shall not change. If the cursor was positioned on the
first character of the line, the terminal shall be alerted, and the
.BR X
command shall have no effect. If the line contained a single
character, the
.BR X
command shall have no effect. If the line contained no characters, the
terminal shall be alerted and the cursor shall not be moved. If the
.IR count
is larger than the number of characters before the cursor, this shall
not be considered an error; all the characters from before the cursor
to the beginning of the line shall be deleted.
.IP "\fB[\fIcount\fB]d\fImotion\fR" 10
.br
Delete the characters between the current cursor position and the
character position that would result from the motion command. A number
.IR count
repeats the motion command
.IR count
times. If the motion command would move toward the beginning of the
command line, the character under the current cursor position shall not
be deleted. If the motion command is
.BR d ,
the entire current command line shall be cleared. If the
.IR count
is larger than the number of characters between the current cursor
position and the end of the command line toward which the motion
command would move the cursor, this shall not be considered an error;
all of the remaining characters in the aforementioned range shall be
deleted. The deleted characters shall be placed in the save buffer.
.IP "\fBD\fR" 10
Delete all characters from the current cursor position to the end of
the line. The deleted characters shall be placed in the save buffer.
.IP "\fB[\fIcount\fB]y\fImotion\fR" 10
.br
Yank (that is, copy) the characters from the current cursor position to
the position resulting from the motion command into the save buffer. A
number
.IR count
shall be applied to the motion command. If the motion command would
move toward the beginning of the command line, the character under the
current cursor position shall not be included in the set of yanked
characters. If the motion command is
.BR y ,
the entire current command line shall be yanked into the save buffer.
The current cursor position shall be unchanged. If the
.IR count
is larger than the number of characters between the current cursor
position and the end of the command line toward which the motion
command would move the cursor, this shall not be considered an error;
all of the remaining characters in the aforementioned range shall be
yanked.
.IP "\fBY\fR" 10
Yank the characters from the current cursor position to the end of the
line into the save buffer. The current character position shall be
unchanged.
.IP "\fB[\fIcount\fB]p\fR" 10
Put a copy of the current contents of the save buffer after the current
cursor position. The current cursor position shall be advanced to the
last character put from the save buffer. A
.IR count
shall indicate how many copies of the save buffer shall be put.
.IP "\fB[\fIcount\fB]P\fR" 10
Put a copy of the current contents of the save buffer before the
current cursor position. The current cursor position shall be moved to
the last character put from the save buffer. A
.IR count
shall indicate how many copies of the save buffer shall be put.
.IP "\fBu\fR" 10
Undo the last command that changed the edit line. This operation shall
not undo the copy of any command line to the edit line.
.IP "\fBU\fR" 10
Undo all changes made to the edit line. This operation shall not undo
the copy of any command line to the edit line.
.IP "\fB[\fIcount\fB]k\fR" 10
.sp -0.5v
.IP "\fB[\fIcount\fB]\-\fR" 10
Set the current command line to be the
.IR count th
previous command line in the shell command history. If
.IR count
is not specified, it shall default to 1. The cursor shall be positioned
on the first character of the new command. If a
.BR k
or
.BR \-
command would retreat past the maximum number of commands in effect for
this shell (affected by the
.IR HISTSIZE
environment variable), the terminal shall be alerted, and the command
shall have no effect.
.IP "\fB[\fIcount\fB]j\fR" 10
.sp -0.5v
.IP "\fB[\fIcount\fB]+\fR" 10
Set the current command line to be the
.IR count th
next command line in the shell command history. If
.IR count
is not specified, it shall default to 1. The cursor shall be positioned
on the first character of the new command. If a
.BR j
or
.BR +
command advances past the edit line, the current command line shall be
restored to the edit line and the terminal shall be alerted.
.IP "\fB[\fInumber\fB]G\fR" 10
Set the current command line to be the oldest command line stored in
the shell command history. With a number
.IR number ,
set the current command line to be the command line
.IR number
in the history. If command line
.IR number
does not exist, the terminal shall be alerted and the command line
shall not be changed.
.IP "\fB/\fIpattern\fR<newline>" 10
.br
Move backwards through the command history, searching for the specified
pattern, beginning with the previous command line. Patterns use the
pattern matching notation described in
.IR "Section 2.13" ", " "Pattern Matching Notation",
except that the
.BR '\(ha' 
character shall have special meaning when it appears as the first
character of
.IR pattern .
In this case, the
.BR '\(ha' 
is discarded and the characters after the
.BR '\(ha' 
shall be matched only at the beginning of a line. Commands in the
command history shall be treated as strings, not as filenames. If the
pattern is not found, the current command line shall be unchanged and
the terminal shall be alerted. If it is found in a previous line, the
current command line shall be set to that line and the cursor shall be
set to the first character of the new command line.
.RS 10 
.P
If
.IR pattern
is empty, the last non-empty pattern provided to
.BR /
or
.BR ?
shall be used. If there is no previous non-empty pattern, the terminal
shall be alerted and the current command line shall remain unchanged.
.RE
.IP "\fB?\fIpattern\fR<newline>" 10
.br
Move forwards through the command history, searching for the specified
pattern, beginning with the next command line. Patterns use the pattern
matching notation described in
.IR "Section 2.13" ", " "Pattern Matching Notation",
except that the
.BR '\(ha' 
character shall have special meaning when it appears as the first
character of
.IR pattern .
In this case, the
.BR '\(ha' 
is discarded and the characters after the
.BR '\(ha' 
shall be matched only at the beginning of a line. Commands in the
command history shall be treated as strings, not as filenames. If the
pattern is not found, the current command line shall be unchanged and
the terminal shall be alerted. If it is found in a following line, the
current command line shall be set to that line and the cursor shall be
set to the fist character of the new command line.
.RS 10 
.P
If
.IR pattern
is empty, the last non-empty pattern provided to
.BR /
or
.BR ?
shall be used. If there is no previous non-empty pattern, the terminal
shall be alerted and the current command line shall remain unchanged.
.RE
.IP "\fBn\fR" 10
Repeat the most recent
.BR /
or
.BR ?
command. If there is no previous
.BR /
or
.BR ? ,
the terminal shall be alerted and the current command line shall remain
unchanged.
.IP "\fBN\fR" 10
Repeat the most recent
.BR /
or
.BR ?
command, reversing the direction of the search. If there is no previous
.BR /
or
.BR ? ,
the terminal shall be alerted and the current command line shall remain
unchanged.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\0\0\0\00" 8
The script to be executed consisted solely of zero or more blank lines
or comments, or both.
.IP "1\(hy125" 8
A non-interactive shell detected an error other than
.IR command_file
not found or executable, including but not limited to syntax,
redirection, or variable assignment errors.
.IP "\0\0126" 8
A specified
.IR command_file
could not be executed due to an
.BR [ENOEXEC] 
error (see
.IR "Section 2.9.1.1" ", " "Command Search and Execution",
item 2).
.IP "\0\0127" 8
A specified
.IR command_file
could not be found by a non-interactive shell.
.P
Otherwise, the shell shall return the exit status of the last command
it invoked or attempted to invoke (see also the
.IR exit
utility in
.IR "Section 2.14" ", " "Special Built-In Utilities").
.SH "CONSEQUENCES OF ERRORS"
See
.IR "Section 2.8.1" ", " "Consequences of Shell Errors".
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
Standard input and standard error are the files that
determine whether a shell is interactive when
.BR \-i
is not specified. For example:
.sp
.RS 4
.nf

sh > file
.fi
.P
.RE
.P
and:
.sp
.RS 4
.nf

sh 2> file
.fi
.P
.RE
.P
create interactive and non-interactive shells, respectively. Although
both accept terminal input, the results of error conditions are
different, as described in
.IR "Section 2.8.1" ", " "Consequences of Shell Errors";
in the second example a redirection error encountered by a special
built-in utility aborts the shell.
.P
A conforming application must protect its first operand, if it starts
with a
<plus-sign>,
by preceding it with the
.BR \(dq--\(dq 
argument that denotes the end of the options.
.P
Applications should note that the standard
.IR PATH
to the shell cannot be assumed to be either
.BR /bin/sh
or
.BR /usr/bin/sh ,
and should be determined by interrogation of the
.IR PATH
returned by
.IR getconf
.IR PATH ,
ensuring that the returned pathname is an absolute pathname and not a
shell built-in.
.P
For example, to determine the location of the standard
.IR sh
utility:
.sp
.RS 4
.nf

command -v sh
.fi
.P
.RE
.P
On some implementations this might return:
.sp
.RS 4
.nf

/usr/xpg4/bin/sh
.fi
.P
.RE
.P
Furthermore, on systems that support executable scripts (the
.BR \(dq#!\(dq 
construct), it is recommended that applications using executable
scripts install them using
.IR getconf
.IR PATH
to determine the shell pathname and update the
.BR \(dq#!\(dq 
script appropriately as it is being installed (for example, with
.IR sed ).
For example:
.sp
.RS 4
.nf

#
# Installation time script to install correct POSIX shell pathname
#
# Get list of paths to check
#
Sifs=$IFS
Sifs_set=${IFS+y}
IFS=:
set -- $(getconf PATH)
if [ "$Sifs_set" = y ]
then
    IFS=$Sifs
else
    unset IFS
fi
#
# Check each path for \(aqsh\(aq
#
for i
do
    if [ -x "${i}"/sh ]
    then
        Pshell=${i}/sh
    fi
done
#
# This is the list of scripts to update. They should be of the
# form \(aq${name}.source\(aq and will be transformed to \(aq${name}\(aq.
# Each script should begin:
#
# #!INSTALLSHELLPATH
#
scripts="a b c"
#
# Transform each script
#
for i in ${scripts}
do
    sed -e "s|INSTALLSHELLPATH|${Pshell}|" < ${i}.source > ${i}
done
.fi
.P
.RE
.SH EXAMPLES
.IP " 1." 4
Execute a shell command from a string:
.RS 4 
.sp
.RS 4
.nf

sh -c "cat myfile"
.fi
.P
.RE
.RE
.IP " 2." 4
Execute a shell script from a file in the current directory:
.RS 4 
.sp
.RS 4
.nf

sh my_shell_cmds
.fi
.P
.RE
.RE
.SH RATIONALE
The
.IR sh
utility and the
.IR set
special built-in utility share a common set of options.
.P
The name
.IR IFS
was originally an abbreviation of ``Input Field Separators''; however,
this name is misleading as the
.IR IFS
characters are actually used as field terminators. One justification
for ignoring the contents of
.IR IFS
upon entry to the script, beyond security considerations, is to
assist possible future shell compilers. Allowing
.IR IFS
to be imported from the environment prevents many optimizations that
might otherwise be performed via dataflow analysis of the script
itself.
.P
The text in the STDIN section about non-blocking reads concerns an
instance of
.IR sh
that has been invoked, probably by a C-language program, with standard
input that has been opened using the O_NONBLOCK flag; see
\fIopen\fR()
in the System Interfaces volume of POSIX.1\(hy2017. If the shell did not reset this flag, it would
immediately terminate because no input data would be available yet and
that would be considered the same as end-of-file.
.P
The options associated with a
.IR "restricted shell"
(command name
.IR rsh
and the
.BR \-r
option) were excluded because the standard developers considered that
the implied level of security could not be achieved and they did not
want to raise false expectations.
.P
On systems that support set-user-ID scripts,
a historical trapdoor has been to link a script to the name
.BR \-i .
When it is called by a sequence such as:
.sp
.RS 4
.nf

sh -
.fi
.P
.RE
.P
or by:
.sp
.RS 4
.nf

#!\ usr/bin/sh\ -
.fi
.P
.RE
.P
the historical systems have assumed that no option letters follow.
Thus, this volume of POSIX.1\(hy2017 allows the single
<hyphen-minus>
to mark the end of the options, in addition to the use of the regular
.BR \(dq--\(dq 
argument, because it was considered that the older practice was so
pervasive. An alternative approach is taken by the KornShell, where
real and effective user/group IDs must match for an interactive shell;
this behavior is specifically allowed by this volume of POSIX.1\(hy2017.
.TP 10
.BR Note:
There are other problems with set-user-ID scripts that the two
approaches described here do not resolve.
.P
.P
The initialization process for the history file can be dependent on the
system start-up files, in that they may contain commands that
effectively preempt the user's settings of
.IR HISTFILE
and
.IR HISTSIZE .
For example, function definition commands are recorded in the history
file, unless the
.IR set
.BR \-o
.IR nolog
option is set. If the system administrator includes function
definitions in some system start-up file called before the
.IR ENV
file, the history file is initialized before the user gets a chance to
influence its characteristics. In some historical shells, the history
file is initialized just after the
.IR ENV
file has been processed. Therefore, it is implementation-defined
whether changes made to
.IR HISTFILE
after the history file has been initialized are effective.
.P
The default messages for the various
.IR MAIL -related
messages are unspecified because they vary across implementations.
Typical messages are:
.sp
.RS 4
.nf

"you have mail\en"
.fi
.P
.RE
.P
or:
.sp
.RS 4
.nf

"you have new mail\en"
.fi
.P
.RE
.P
It is important that the descriptions of command line editing refer to
the same shell as that in POSIX.1\(hy2008 so that interactive users can also be
application programmers without having to deal with programmatic
differences in their two environments. It is also essential that the
utility name
.IR sh
be specified because this explicit utility name is too firmly rooted in
historical practice of application programs for it to change.
.P
Consideration was given to mandating a diagnostic message when
attempting to set
.IR vi -mode
on terminals that do not support command line editing. However, it is
not historical practice for the shell to be cognizant of all terminal
types and thus be able to detect inappropriate terminals in all cases.
Implementations are encouraged to supply diagnostics in this case
whenever possible, rather than leaving the user in a state where
editing commands work incorrectly.
.P
In early proposals, the KornShell-derived
.IR emacs
mode of command line editing was included, even though the
.IR emacs
editor itself was not. The community of
.IR emacs
proponents was adamant that the full
.IR emacs
editor not be standardized because they were concerned that an attempt
to standardize this very powerful environment would encourage vendors
to ship strictly conforming versions lacking the extensibility required
by the community. The author of the original
.IR emacs
program also expressed his desire to omit the program. Furthermore,
there were a number of historical systems that did not include
.IR emacs ,
or included it without supporting it, but there were very few that did
not include and support
.IR vi .
The shell
.IR emacs
command line editing mode was finally omitted because it became
apparent that the KornShell version and the editor being distributed
with the GNU system had diverged in some respects. The author of
.IR emacs
requested that the POSIX
.IR emacs
mode either be deleted or have a significant number of unspecified
conditions. Although the KornShell author agreed to consider changes to
bring the shell into alignment, the standard developers decided to
defer specification at that time. At the time, it was assumed that
convergence on an acceptable definition would occur for a subsequent
draft, but that has not happened, and there appears to be no impetus to
do so. In any case, implementations are free to offer additional
command line editing modes based on the exact models of editors their
users are most comfortable with.
.P
Early proposals had the following list entry in
.IR "vi Line Editing Insert Mode":
.IP "\fR\e\fR" 6
If followed by the
.IR erase
or
.IR kill
character, that character shall be inserted into the input line.
Otherwise, the
<backslash>
itself shall be inserted into the input line.
.P
However, this is not actually a feature of
.IR sh
command line editing insert mode, but one of some historical terminal
line drivers. Some conforming implementations continue to do this when
the
.IR stty
.BR iexten
flag is set.
.P
In interactive shells, SIGTERM is ignored so that
.IR "kill 0"
does not kill the shell, and SIGINT is caught so that
.IR wait
is interruptible. If the shell does not ignore SIGTTIN, SIGTTOU, and
SIGTSTP signals when it is interactive and the
.BR \-m
option is not in effect, these signals suspend the shell if it is not
a session leader. If it is a session leader, the signals are discarded
if they would stop the process, as required by the System Interfaces volume of POSIX.1\(hy2017,
.IR "Section 2.4.3" ", " "Signal Actions"
for orphaned process groups.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "Section 2.9.1.1" ", " "Command Search and Execution",
.IR "Chapter 2" ", " "Shell Command Language",
.IR "\fIcd\fR\^",
.IR "\fIecho\fR\^",
.IR "\fIexit\fR\^",
.IR "\fIfc\fR\^",
.IR "\fIpwd\fR\^",
.IR "invalid",
.IR "\fIset\fR\^",
.IR "\fIstty\fR\^",
.IR "\fItest\fR\^",
.IR "\fItrap\fR\^",
.IR "\fIumask\fR\^",
.IR "\fIvi\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.P
The System Interfaces volume of POSIX.1\(hy2017,
.IR "\fIdup\fR\^(\|)",
.IR "\fIexec\fR\^",
.IR "\fIexit\fR\^(\|)",
.IR "\fIfork\fR\^(\|)",
.IR "\fIopen\fR\^(\|)",
.IR "\fIpipe\fR\^(\|)",
.IR "\fIsignal\fR\^(\|)",
.IR "\fIsystem\fR\^(\|)",
.IR "\fIulimit\fR\^(\|)",
.IR "\fIumask\fR\^(\|)",
.IR "\fIwait\fR\^(\|)"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .