mirrored from git://git.code.sf.net/p/zsh/code
-
Notifications
You must be signed in to change notification settings - Fork 432
/
builtins.yo
2895 lines (2639 loc) · 131 KB
/
builtins.yo
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
texinode(Shell Builtin Commands)(Zsh Line Editor)(Options)(Top)
chapter(Shell Builtin Commands)
ifzman(\
sect(Shell Builtin Commands)
)\
def(prefix)(1)(\
item(tt(ARG1) var(simple command))(
See ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
ifnzman(noderef(Precommand Modifiers)).
)\
)\
def(alias)(2)(\
findex(ARG1)
item(tt(ARG1))(
Same as tt(ARG2).
)\
)\
def(module)(2)(\
item(tt(ARG1))(
See ifzman(the section `The ARG2 Module' in zmanref(zshmodules))\
ifnzman(noderef(The ARG2 Module)).
)\
)\
def(zlecmd)(1)(\
item(tt(ARG1))(
See ifzman(the section `Zle Builtins' in zmanref(zshzle))\
ifnzman(noderef(Zle Builtins)).
)\
)\
cindex(builtin commands)
cindex(commands, builtin)
Some shell builtin commands take options as described in individual
entries; these are often referred to in the list below as `tt(flags)' to
avoid confusion with shell options, which may also have an effect on the
behaviour of builtin commands. In this introductory section,
`tt(option)' always has the meaning of an option to a command that should
be familiar to most command line users.
Typically, options are single letters preceded by a hyphen (tt(-)).
Options that take an argument accept it either immediately following the
option letter or after white space, for example `tt(print -C3 {1..9})' or
`tt(print -C 3 {1..9})' are equivalent. Arguments to options are not the
same as arguments to the command; the documentation indicates which is
which. Options that do not take an argument may be combined in a single
word, for example `tt(print -rca -- *)' and `tt(print -r -c -a -- *)' are
equivalent.
Some shell builtin commands also take options that begin with `tt(+)'
instead of `tt(-)'. The list below makes clear which commands these
are.
Options (together with their individual arguments, if any) must appear
in a group before any non-option arguments; once the first non-option
argument has been found, option processing is terminated.
All builtin commands other than `tt(echo)' and precommand modifiers,
even those that have no options, can be given the argument `tt(-)tt(-)'
to terminate option processing. This indicates that the following words
are non-option arguments, but is otherwise ignored. This is useful in
cases where arguments to the command may begin with `tt(-)'. For
historical reasons, most builtin commands (including `tt(echo)') also
recognize a single `tt(-)' in a separate word for this purpose; note
that this is less standard and use of `tt(-)tt(-)' is recommended.
startitem()
prefix(-)
findex(.)
item(tt(.) var(file) [ var(arg) ... ])(
Read commands from var(file) and execute them in the current shell
environment.
If var(file) does not contain a slash, or if tt(PATH_DIRS) is set,
the shell looks in the components of tt($path) to find the directory
containing var(file). Files in the current directory are not read
unless `tt(.)' appears somewhere in tt($path). If a file named
`var(file)tt(.zwc)' is found, is newer than var(file), and is the
compiled form (created with the tt(zcompile) builtin) of var(file),
then commands are read from that file instead of var(file).
If any arguments var(arg) are given,
they become the positional parameters; the old positional
parameters are restored when the var(file) is done executing.
However, if no arguments are given,
the positional parameters remain those of the calling context,
and no restoring is done.
If var(file) was not found the return status is 127; if var(file) was found
but contained a syntax error the return status is 126; else the return
status is the exit status of the last command executed.
)
findex(NOTRANS(:))
cindex(expanding parameters)
cindex(parameters, expanding)
cindex(doing nothing)
item(tt(:) [ var(arg) ... ])(
This command does nothing, although normal argument expansions is performed
which may have effects on shell parameters. A zero exit status is returned.
)
findex(alias)
cindex(aliases, defining)
cindex(aliases, listing)
item(tt(alias) [ {tt(PLUS())|tt(-)}tt(gmrsL) ] [ var(name)[tt(=)var(value)] ... ])(
For each var(name) with a corresponding var(value), define an alias
with that value. A trailing space in var(value) causes the next word
to be checked for alias expansion. If the tt(-g) flag is present,
define a global alias; global aliases are expanded even if they do not
occur in command position.
If the tt(-s) flag is present, define a suffix alias: if the command
word on a command line is in the form `var(text)tt(.)var(name)', where
var(text) is any non-empty string, it is replaced by the text
`var(value) var(text)tt(.)var(name)'. Note that var(name) is treated as
a literal string, not a pattern. A trailing space in var(value) is not
special in this case. For example,
example(alias -s ps='gv --')
will cause the command `tt(*.ps)' to be expanded to `tt(gv -- *.ps)'. As
alias expansion is carried out earlier than globbing, the `tt(*.ps)' will
then be expanded. Suffix aliases constitute a different name space from
other aliases (so in the above example it is still possible
to create an alias for the command tt(ps)) and the two sets are never
listed together.
For each var(name) with no var(value),
print the value of var(name), if any. With no arguments, print all
currently defined aliases other than suffix aliases. If the tt(-m) flag
is given the arguments are taken as patterns (they should be quoted to
preserve them from being interpreted as glob patterns), and the aliases
matching these patterns are printed. When printing aliases and one of
the tt(-g), tt(-r) or tt(-s) flags is present, restrict the printing to
global, regular or suffix aliases, respectively; a regular alias is one
which is neither a global nor a suffix alias. Using `tt(PLUS())'
instead of `tt(-)', or ending the option list with a single
`tt(PLUS())', prevents the values of the aliases from being printed.
If the tt(-L) flag is present, then print each
alias in a manner suitable for putting in a startup script. The exit
status is nonzero if a var(name) (with no var(value)) is given for
which no alias has been defined.
For more on aliases, include common problems, see
ifzman(the section ALIASING in zmanref(zshmisc))\
ifnzman(noderef(Aliasing)).
)
findex(autoload)
cindex(functions, autoloading)
cindex(autoloading functions)
item(tt(autoload) [ {tt(PLUS())|tt(-)}tt(RTUXdkmrtWz) ] [ tt(-w) ] [ var(name) ... ])(
vindex(fpath, searching)
See the section `Autoloading Functions' in ifzman(zmanref(zshmisc))\
ifnzman(noderef(Functions)) for full details. The tt(fpath) parameter
will be searched to find the function definition when the function is
first referenced.
If var(name) consists of an absolute path, the function is defined to
load from the file given (searching as usual for dump files in the given
location). The name of the function is the basename (non-directory
part) of the file. It is normally an error if the function is not found
in the given location; however, if the option tt(-d) is given, searching
for the function defaults to tt($fpath). If a function is loaded by
absolute path, any functions loaded from it that are marked for
tt(autoload) without an absolute path have the load path of the parent
function temporarily prepended to tt($fpath).
If the option tt(-r) or tt(-R) is given, the function is searched for
immediately and the location is recorded internally for use when the
function is executed; a relative path is expanded using the value of
tt($PWD). This protects against a change to tt($fpath) after the call
to tt(autoload). With tt(-r), if the function is not found, it is
silently left unresolved until execution; with tt(-R), an error message
is printed and command processing aborted immediately the search fails,
i.e. at the tt(autoload) command rather than at function execution..
The flag tt(-X) may be used only inside a shell function. It causes the
calling function to be marked for autoloading and then immediately
loaded and executed, with the current array of positional parameters as
arguments. This replaces the previous definition of the function. If
no function definition is found, an error is printed and the function
remains undefined and marked for autoloading. If an argument is given,
it is used as a directory (i.e. it does not include the name of the
function) in which the function is to be found; this may be combined
with the tt(-d) option to allow the function search to default to tt($fpath)
if it is not in the given location.
The flag tt(+X) attempts to load each var(name) as an autoloaded function,
but does em(not) execute it. The exit status is zero (success) if the
function was not previously defined em(and) a definition for it was found.
This does em(not) replace any existing definition of the function. The
exit status is nonzero (failure) if the function was already defined or
when no definition was found. In the latter case the function remains
undefined and marked for autoloading. If ksh-style autoloading is
enabled, the function created will contain the contents of the file
plus a call to the function itself appended to it, thus giving normal
ksh autoloading behaviour on the first call to the function.
If the tt(-m) flag is also given each var(name) is treated as a
pattern and all functions already marked for autoload that match the
pattern are loaded.
With the tt(-t) flag, turn on execution tracing; with tt(-T), turn on
execution tracing only for the current function, turning it off on entry
to any called functions that do not also have tracing enabled.
With the tt(-U) flag, alias expansion is suppressed when the function is
loaded.
With the tt(-w) flag, the var(name)s are taken as names of files compiled
with the tt(zcompile) builtin, and all functions defined in them are
marked for autoloading.
The flags tt(-z) and tt(-k) mark the function to be autoloaded using the
zsh or ksh style, as if the option tt(KSH_AUTOLOAD) were unset or were
set, respectively. The flags override the setting of the option at the
time the function is loaded.
Note that the tt(autoload) command makes no attempt to ensure the
shell options set during the loading or execution of the file have
any particular value. For this, the tt(emulate) command can be used:
example(emulate zsh -c 'autoload -Uz var(func)')
arranges that when var(func) is loaded the shell is in native tt(zsh)
emulation, and this emulation is also applied when var(func) is run.
Some of the functions of tt(autoload) are also provided by tt(functions
-u) or tt(functions -U), but tt(autoload) is a more comprehensive
interface.
)
findex(bg)
cindex(jobs, backgrounding)
xitem(tt(bg) [ var(job) ... ])
item(var(job) ... tt(&))(
Put each specified var(job) in the background,
or the current job if none is specified.
)
zlecmd(bindkey)
findex(break)
cindex(exiting loops)
cindex(loops, exiting)
item(tt(break) [ var(n) ])(
Exit from an enclosing tt(for), tt(while),
tt(until), tt(select) or tt(repeat) loop. If an arithmetic expression var(n)
is specified, then break var(n) levels instead of just one.
)
findex(builtin)
item(tt(builtin) var(name) [ var(args) ... ])(
Executes the builtin var(name), with the given var(args).
)
alias(bye)(exit)
module(cap)(zsh/cap)
findex(cd)
cindex(directories, changing)
xitem(tt(cd) [ tt(-qsLP) ] [ var(arg) ])
xitem(tt(cd) [ tt(-qsLP) ] var(old) var(new))
item(tt(cd) [ tt(-qsLP) ] {tt(PLUS())|tt(-)}var(n))(
Change the current directory. In the first form, change the
current directory to var(arg), or to the value of tt($HOME) if
var(arg) is not specified. If var(arg) is `tt(-)', change to the
previous directory.
Otherwise, if var(arg) begins with a slash, attempt to change to the
directory given by var(arg).
If var(arg) does not begin with a slash, the behaviour depends on whether
the current directory `tt(.)' occurs in the list of directories contained
in the shell parameter tt(cdpath). If it does not, first attempt to change
to the directory var(arg) under the current directory, and if that fails
but tt(cdpath) is set and contains at least one element attempt to change
to the directory var(arg) under each component of tt(cdpath) in turn until
successful. If `tt(.)' occurs in tt(cdpath), then tt(cdpath) is searched
strictly in order so that `tt(.)' is only tried at the appropriate point.
The order of testing tt(cdpath) is modified if the option tt(POSIX_CD)
is set, as described in the documentation for the option.
If no directory is found, the option tt(CDABLE_VARS) is set, and a
parameter named var(arg) exists whose value begins with a slash, treat its
value as the directory. In that case, the parameter is added to the named
directory hash table.
The second form of tt(cd) substitutes the string var(new)
for the string var(old) in the name of the current directory,
and tries to change to this new directory.
The third form of tt(cd) extracts an entry from the directory
stack, and changes to that directory. An argument of the form
`tt(PLUS())var(n)' identifies a stack entry by counting from the left
of the list shown by the tt(dirs) command, starting with zero.
An argument of the form `tt(-)var(n)' counts from the right.
If the tt(PUSHD_MINUS) option is set, the meanings of `tt(PLUS())'
and `tt(-)' in this context are swapped.
If the tt(POSIX_CD) option is set, this form of tt(cd) is not recognised
and will be interpreted as the first form.
If the tt(-q) (quiet) option is specified, the hook function tt(chpwd)
and the functions in the array tt(chpwd_functions) are not called.
This is useful for calls to tt(cd) that do not change the environment
seen by an interactive user.
If the tt(-s) option is specified, tt(cd) refuses to change the current
directory if the given pathname contains symlinks. If the tt(-P) option
is given or the tt(CHASE_LINKS) option is set, symbolic links are resolved
to their true values. If the tt(-L) option is given symbolic links are
retained in the directory (and not resolved) regardless of the state of
the tt(CHASE_LINKS) option.
)
alias(chdir)(cd)
module(clone)(zsh/clone)
findex(command)
item(tt(command) [ tt(-pvV) ] var(simple command))(
The simple command argument is taken as an external command instead of
a function or builtin and is executed. If the tt(POSIX_BUILTINS) option
is set, builtins will also be executed but certain special properties
of them are suppressed. The tt(-p) flag causes a default path to be
searched instead of that in tt($path). With the tt(-v) flag, tt(command)
is similar to tt(whence) and with tt(-V), it is equivalent to tt(whence
-v).
See also ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
ifnzman(noderef(Precommand Modifiers)).
)
module(comparguments)(zsh/computil)
module(compcall)(zsh/compctl)
module(compctl)(zsh/compctl)
module(compdescribe)(zsh/computil)
module(compfiles)(zsh/computil)
module(compgroups)(zsh/computil)
module(compquote)(zsh/computil)
module(comptags)(zsh/computil)
module(comptry)(zsh/computil)
module(compvalues)(zsh/computil)
findex(continue)
cindex(loops, continuing)
cindex(continuing loops)
item(tt(continue) [ var(n) ])(
Resume the next iteration of the enclosing
tt(for), tt(while), tt(until), tt(select) or
tt(repeat) loop. If an arithmetic expression var(n) is specified, break out of
var(n)-1 loops and resume at the var(n)th enclosing loop.
)
alias(declare)(typeset)
findex(dirs)
cindex(directory stack, printing)
xitem(tt(dirs) [ tt(-c) ] [ var(arg) ... ])
item(tt(dirs) [ tt(-lpv) ])(
With no arguments, print the contents of the directory stack.
Directories are added to this stack with the tt(pushd) command,
and removed with the tt(cd) or tt(popd) commands.
If arguments are specified, load them onto the directory stack,
replacing anything that was there, and push the current directory
onto the stack.
startitem()
item(tt(-c))(
clear the directory stack.
)
item(tt(-l))(
print directory names in full instead of using of using tt(~) expressions (\
ifzman(see em(Dynamic) and em(Static named directories) in zmanref(zshexpn))\
ifnzman(noderef(Filename Expansion))).
)
item(tt(-p))(
print directory entries one per line.
)
item(tt(-v))(
number the directories in the stack when printing.
)
enditem()
)
findex(disable)
cindex(disabling commands)
cindex(commands, disabling)
item(tt(disable) [ tt(-afmprs) ] var(name) ...)(
Temporarily disable the var(name)d hash table elements or patterns. The default
is to disable builtin commands. This allows you to use an external
command with the same name as a builtin command. The tt(-a) option
causes tt(disable) to act on regular or global aliases. The tt(-s)
option causes tt(disable) to act on suffix aliases. The tt(-f) option causes
tt(disable) to act on shell functions. The tt(-r) options causes
tt(disable) to act on reserved words. Without arguments all disabled
hash table elements from the corresponding hash table are printed.
With the tt(-m) flag the arguments are taken as patterns (which should be
quoted to prevent them from undergoing filename expansion), and all hash
table elements from the corresponding hash table matching these patterns
are disabled. Disabled objects can be enabled with the tt(enable)
command.
With the option tt(-p), var(name) ... refer to elements of the
shell's pattern syntax as described in noderef(Filename Generation).
Certain elements can be disabled separately, as given below.
Note that patterns
not allowed by the current settings for the options tt(EXTENDED_GLOB),
tt(KSH_GLOB) and tt(SH_GLOB) are never enabled, regardless of the
setting here. For example, if tt(EXTENDED_GLOB) is not active,
the pattern tt(^) is ineffective even if `tt(disable -p "^")' has
not been issued. The list below indicates any option settings
that restrict the use of the pattern. It should be noted that
setting tt(SH_GLOB) has a wider effect than merely disabling patterns
as certain expressions, in particular those involving parentheses,
are parsed differently.
The following patterns may be disabled; all
the strings need quoting on the command line to prevent them from
being interpreted immediately as patterns and the patterns are
shown below in single quotes as a reminder.
startitem()
item(tt('?'))(
The pattern character tt(?) wherever it occurs, including when preceding
a parenthesis with tt(KSH_GLOB).
)
item(tt('*'))(
The pattern character tt(*) wherever it occurs, including recursive
globbing and when preceding a parenthesis with tt(KSH_GLOB).
)
item(tt('LSQUARE()'))(
Character classes.
)
item(tt('<') (tt(NO_SH_GLOB)))(
Numeric ranges.
)
item(tt('|') (tt(NO_SH_GLOB)))(
Alternation in grouped patterns, case statements, or KSH_GLOB
parenthesised expressions.
)
item(tt('LPAR()') (tt(NO_SH_GLOB)))(
Grouping using single parentheses. Disabling this does not disable the
use of parentheses for tt(KSH_GLOB) where they are introduced by a
special character, nor for glob qualifiers (use `tt(setopt
NO_BARE_GLOB_QUAL)' to disable glob qualifiers that use parentheses
only).
)
item(tt('~') (tt(EXTENDED_GLOB)))(
Exclusion in the form var(A)tt(~)var(B).
)
item(tt('^') (tt(EXTENDED_GLOB)))(
Exclusion in the form var(A)tt(^)var(B).
)
item(tt('#') (tt(EXTENDED_GLOB)))(
The pattern character tt(#) wherever it occurs, both for
repetition of a previous pattern and for indicating globbing flags.
)
item(tt('?LPAR()') (tt(KSH_GLOB)))(
The grouping form tt(?LPAR())var(...)tt(RPAR()). Note this is also
disabled if tt('?') is disabled.
)
item(tt('*LPAR()') (tt(KSH_GLOB)))(
The grouping form tt(*LPAR())var(...)tt(RPAR()). Note this is also
disabled if tt('*') is disabled.
)
item(tt('PLUS()LPAR()') (tt(KSH_GLOB)))(
The grouping form tt(PLUS()LPAR())var(...)tt(RPAR()).
)
item(tt('!LPAR()') (tt(KSH_GLOB)))(
The grouping form tt(!LPAR())var(...)tt(RPAR()).
)
item(tt('@LPAR()') (tt(KSH_GLOB)))(
The grouping form tt(@LPAR())var(...)tt(RPAR()).
)
enditem()
)
findex(disown)
cindex(jobs, disowning)
xitem(tt(disown) [ var(job) ... ])
xitem(var(job) ... tt(&|))
item(var(job) ... tt(&!))(
Remove the specified var(job)s from the job table; the shell will
no longer report their status, and will not complain if you
try to exit an interactive shell with them running or stopped.
If no var(job) is specified, disown the current job.
If the var(job)s are currently stopped and the tt(AUTO_CONTINUE) option
is not set, a warning is printed containing information about how to
make them running after they have been disowned. If one of the latter
two forms is used, the var(job)s will automatically be made running,
independent of the setting of the tt(AUTO_CONTINUE) option.
)
findex(echo)
item(tt(echo) [ tt(-neE) ] [ var(arg) ... ])(
Write each var(arg) on the standard output, with a space separating
each one.
If the tt(-n) flag is not present, print a newline at the end.
tt(echo) recognizes the following escape sequences:
startsitem()
sitem(tt(\a))(bell character)
sitem(tt(\b))(backspace)
sitem(tt(\c))(suppress subsequent characters and final newline)
sitem(tt(\e))(escape)
sitem(tt(\f))(form feed)
sitem(tt(\n))(linefeed (newline))
sitem(tt(\r))(carriage return)
sitem(tt(\t))(horizontal tab)
sitem(tt(\v))(vertical tab)
sitem(tt(\\))(backslash)
sitem(tt(\0)var(NNN))(character code in octal)
sitem(tt(\x)var(NN))(character code in hexadecimal)
sitem(tt(\u)var(NNNN))(unicode character code in hexadecimal)
sitem(tt(\U)var(NNNNNNNN))(unicode character code in hexadecimal)
endsitem()
pindex(BSD_ECHO, use of)
The tt(-E) flag, or the tt(BSD_ECHO) option, can be used to disable
these escape sequences. In the latter case, tt(-e) flag can be used to
enable them.
Note that for standards compliance a double dash does not terminate
option processing; instead, it is printed directly. However, a
single dash does terminate option processing, so the first dash,
possibly following options, is not printed, but everything following it
is printed as an argument. The single dash behaviour is different
from other shells. For a more portable way of printing text, see
tt(printf), and for a more controllable way of printing text within zsh,
see tt(print).
)
module(echotc)(zsh/termcap)
module(echoti)(zsh/terminfo)
findex(emulate)
cindex(compatibility, sh)
cindex(compatibility, ksh)
cindex(compatibility, csh)
cindex(sh, compatibility)
cindex(ksh, compatibility)
cindex(csh, compatibility)
item(tt(emulate) [ tt(-lLR) ] [ {tt(zsh)|tt(sh)|tt(ksh)|tt(csh)} [ var(flags) ... ] ])(
Without any argument print current emulation mode.
With single argument set up zsh options to emulate the specified shell
as much as possible.
bf(csh) will never be fully emulated.
If the argument is not one of the shells listed above, tt(zsh)
will be used as a default; more precisely, the tests performed on the
argument are the same as those used to determine the emulation at startup
based on the shell name, see
ifzman(\
the section COMPATIBILITY in zmanref(zsh)
)\
ifnzman(\
noderef(Compatibility)
)\
. In addition to setting shell options, the command also restores
the pristine state of pattern enables, as if all patterns had been
enabled using tt(enable -p).
If the tt(emulate) command occurs inside a function that has been
marked for execution tracing with tt(functions -t) then the tt(xtrace)
option will be turned on regardless of emulation mode or other options.
Note that code executed inside the function by the tt(.), tt(source), or
tt(eval) commands is not considered to be running directly from the
function, hence does not provoke this behaviour.
If the tt(-R) switch is given, all settable options
are reset to their default value corresponding to the specified emulation
mode, except for certain options describing the interactive
environment; otherwise, only those options likely to cause portability
problems in scripts and functions are altered. If the tt(-L) switch is given,
the options tt(LOCAL_OPTIONS), tt(LOCAL_PATTERNS) and tt(LOCAL_TRAPS)
will be set as
well, causing the effects of the tt(emulate) command and any tt(setopt),
tt(disable -p) or tt(enable -p), and tt(trap) commands to be local to
the immediately surrounding shell
function, if any; normally these options are turned off in all emulation
modes except tt(ksh). The tt(-L) switch is mutually exclusive with the
use of tt(-c) in var(flags).
If there is a single argument and the tt(-l) switch is given, the
options that would be set or unset (the latter indicated with the prefix
`tt(no)') are listed. tt(-l) can be combined with tt(-L) or tt(-R) and
the list will be modified in the appropriate way. Note the list does
not depend on the current setting of options, i.e. it includes all
options that may in principle change, not just those that would actually
change.
The var(flags) may be any of the invocation-time flags described in
ifnzman(noderef(Invocation))\
ifzman(the section INVOCATION in zmanref(zsh)),
except that `tt(-o EMACS)' and `tt(-o VI)' may not be used. Flags such
as `tt(+r)'/`tt(+o RESTRICTED)' may be prohibited in some circumstances.
If tt(-c) var(arg) appears in var(flags), var(arg) is evaluated while the
requested emulation is temporarily in effect. In this case the emulation
mode and all options are restored to their previous values before
tt(emulate) returns. The tt(-R) switch may precede the name of the shell
to emulate; note this has a meaning distinct from including tt(-R) in
var(flags).
Use of tt(-c) enables `sticky' emulation mode for functions defined
within the evaluated expression: the emulation mode is associated
thereafter with the function so that whenever the function is executed
the emulation (respecting the tt(-R) switch, if present) and all
options are set (and pattern disables cleared)
before entry to the function, and the state is restored after exit.
If the function is called when the sticky emulation is already in
effect, either within an `tt(emulate) var(shell) tt(-c)' expression or
within another function with the same sticky emulation, entry and exit
from the function do not cause options to be altered (except due to
standard processing such as the tt(LOCAL_OPTIONS) option). This also
applies to functions marked for autoload within the sticky emulation;
the appropriate set of options will be applied at the point the
function is loaded as well as when it is run.
For example:
example(emulate sh -c 'fni+LPAR()RPAR() { setopt cshnullglob; }
fno+LPAR()RPAR() { fni; }'
fno)
The two functions tt(fni) and tt(fno) are defined with sticky tt(sh)
emulation. tt(fno) is then executed, causing options associated
with emulations to be set to their values in tt(sh). tt(fno) then
calls tt(fni); because tt(fni) is also marked for sticky tt(sh)
emulation, no option changes take place on entry to or exit from it.
Hence the option tt(cshnullglob), turned off by tt(sh) emulation, will
be turned on within tt(fni) and remain on return to tt(fno). On exit
from tt(fno), the emulation mode and all options will be restored to the
state they were in before entry to the temporary emulation.
The documentation above is typically sufficient for the intended
purpose of executing code designed for other shells in a suitable
environment. More detailed rules follow.
startsitem()
sitem(1.)(The sticky emulation environment provided by `tt(emulate)
var(shell) tt(-c)' is identical to that provided by entry to
a function marked for sticky emulation as a consequence of being
defined in such an environment. Hence, for example, the sticky
emulation is inherited by subfunctions defined within functions
with sticky emulation.)
sitem(2.)(No change of options takes place on entry to or exit from
functions that are not marked for sticky emulation, other than those
that would normally take place, even if those functions are called
within sticky emulation.)
sitem(3.)(No special handling is provided for functions marked for
tt(autoload) nor for functions present in wordcode created by
the tt(zcompile) command.)
sitem(4.)(The presence or absence of the tt(-R) switch to tt(emulate)
corresponds to different sticky emulation modes, so for example
`tt(emulate sh -c)', `tt(emulate -R sh -c)' and `tt(emulate csh -c)'
are treated as three distinct sticky emulations.)
sitem(5.)(Difference in shell options supplied in addition to the
basic emulation also mean the sticky emulations are different, so for
example `tt(emulate zsh -c)' and `tt(emulate zsh -o cbases -c)' are
treated as distinct sticky emulations.)
endsitem()
)
findex(enable)
cindex(enabling commands)
cindex(commands, enabling)
item(tt(enable) [ tt(-afmprs) ] var(name) ...)(
Enable the var(name)d hash table elements, presumably disabled
earlier with tt(disable). The default is to enable builtin commands.
The tt(-a) option causes tt(enable) to act on regular or global aliases.
The tt(-s) option causes tt(enable) to act on suffix aliases.
The tt(-f) option causes tt(enable) to act on shell functions. The tt(-r)
option causes tt(enable) to act on reserved words. Without arguments
all enabled hash table elements from the corresponding hash table are
printed. With the tt(-m) flag the arguments are taken as patterns
(should be quoted) and all hash table elements from the corresponding
hash table matching these patterns are enabled. Enabled objects can be
disabled with the tt(disable) builtin command.
tt(enable -p) reenables patterns disabled with tt(disable -p). Note
that it does not override globbing options; for example, `tt(enable -p
"~")' does not cause the pattern character tt(~) to be active unless
the tt(EXTENDED_GLOB) option is also set. To enable all possible
patterns (so that they may be individually disabled with tt(disable -p)),
use `tt(setopt EXTENDED_GLOB KSH_GLOB NO_SH_GLOB)'.
)
findex(eval)
cindex(evaluating arguments as commands)
item(tt(eval) [ var(arg) ... ])(
Read the arguments as input to the shell and execute the resulting
command+LPAR()s+RPAR() in the current shell process. The return status is
the same as if the commands had been executed directly by the shell;
if there are no var(args) or they contain no commands (i.e. are
an empty string or whitespace) the return status is zero.
)
item(tt(exec) [ tt(-cl) ] [ tt(-a) var(argv0) ] [ var(command) [ var(arg) ... ] ])(
Replace the current shell with var(command) rather than forking.
If var(command) is a shell builtin command or a shell function,
the shell executes it, and exits when the command is complete.
With tt(-c) clear the environment; with tt(-l) prepend tt(-) to the
tt(argv[0]) string of the command executed (to simulate a login shell);
with tt(-a) var(argv0) set the tt(argv[0]) string of the command
executed.
See ifzman(the section `Precommand Modifiers' in zmanref(zshmisc))\
ifnzman(noderef(Precommand Modifiers)).
If the option tt(POSIX_BUILTINS) is set, var(command) is never
interpreted as a shell builtin command or shell function. This
means further precommand modifiers such as tt(builtin) and
tt(noglob) are also not interpreted within the shell. Hence
var(command) is always found by searching the command path.
cindex(redirection, current shell's I/O)
If var(command) is omitted but any redirections are specified,
then the redirections will take effect in the current shell.
)
findex(exit)
item(tt(exit) [ var(n) ])(
Exit the shell with the exit status specified by an arithmetic
expression var(n); if none
is specified, use the exit status from the last command executed.
pindex(IGNORE_EOF, use of)
An EOF condition will also cause the shell to exit, unless
the tt(IGNORE_EOF) option is set.
See notes at the end of
ifzman(the section JOBS in zmanref(zshmisc))\
ifnzman(noderef(Jobs & Signals)) for some possibly unexpected interactions
of the tt(exit) command with jobs.
)
findex(export)
item(tt(export) [ var(name)[tt(=)var(value)] ... ])(
The specified var(name)s are marked for automatic export
to the environment of subsequently executed commands.
Equivalent to tt(typeset -gx).
If a parameter specified does not
already exist, it is created in the global scope.
)
findex(false)
cindex(doing nothing, unsuccessfully)
item(tt(false) [ var(arg) ... ])(
Do nothing and return an exit status of 1.
)
findex(fc)
cindex(history, editing)
cindex(editing history)
redef(SPACES)(0)(tt(ifztexi(NOTRANS(@ @ @ @ @ @ ))ifnztexi( )))
xitem(tt(fc) [ tt(-e) var(ename) ] [ tt(-LI) ] [ tt(-m) var(match) ] [ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
xitem(tt(fc -l )[ tt(-LI) ] [ tt(-nrdfEiD) ] [ tt(-t) var(timefmt) ] [ tt(-m) var(match) ])
xitem(SPACES()[ var(old)tt(=)var(new) ... ] [ var(first) [ var(last) ] ])
xitem(tt(fc -p )[ tt(-a) ] [ var(filename) [ var(histsize) [ var(savehistsize) ] ] ])
xitem(tt(fc) tt(-P))
item(tt(fc) tt(-ARWI) [ var(filename) ])(
The tt(fc) command controls the interactive history mechanism. Note
that reading and writing of history options is only performed if the
shell is interactive. Usually this is detected automatically, but
it can be forced by setting the tt(interactive) option when starting the
shell.
The first two forms of this command select a range of events from
var(first) to var(last) from the history list. The arguments var(first)
and var(last) may be specified as a number or as a string. A negative
number is used as an offset to the current history event number. A string
specifies the most recent event beginning with the given string. All
substitutions var(old)tt(=)var(new), if any, are then performed on the
text of the events.
In addition to the number range,
startsitem()
sitem(tt(-I))(restricts to only internal events (not from tt($HISTFILE)))
sitem(tt(-L))(restricts to only local events (not from other shells, see
tt(SHARE_HISTORY) in ifzman(zmanref(zshoptions))\
ifnzman(noderef(Description of Options)) -- note that tt($HISTFILE) is
considered local when read at startup))
sitem(tt(-m))(takes the first argument as a pattern (should be quoted) and
only the history events matching this pattern are considered)
endsitem()
If var(first) is not specified, it will be set to -1 (the most recent
event), or to -16 if the tt(-l) flag is given.
If var(last) is not specified, it will be set to var(first),
or to -1 if the tt(-l) flag is given.
However, if the current event has added entries to the history with
`tt(print -s)' or `tt(fc -R)', then the default var(last) for tt(-l)
includes all new history entries since the current event began.
When the tt(-l) flag is given, the resulting events are listed on
standard output. Otherwise the editor program specified by tt(-e) var(ename)
is invoked on a file containing these history events. If tt(-e) is not given, the
value of the parameter tt(FCEDIT) is used; if that is not set the value of
the parameter tt(EDITOR) is used; if that is not set a builtin default,
usually `tt(vi)' is used. If var(ename) is `tt(-)', no editor is invoked.
When editing is complete, the edited command is executed.
The flag tt(-r) reverses the order of the events and the
flag tt(-n) suppresses event numbers when listing.
Also when listing,
startsitem()
sitem(tt(-d))(prints timestamps for each event)
sitem(tt(-f))(prints full time-date stamps in the US
`var(MM)tt(/)var(DD)tt(/)var(YY) var(hh)tt(:)var(mm)' format)
sitem(tt(-E))(prints full time-date stamps in the European
`var(dd)tt(.)var(mm)tt(.)var(yyyy) var(hh)tt(:)var(mm)' format)
sitem(tt(-i))(prints full time-date stamps in ISO8601
`var(yyyy)tt(-)var(mm)tt(-)var(dd) var(hh)tt(:)var(mm)' format)
sitem(tt(-t) var(fmt))(prints time and date stamps in the given format;
var(fmt) is formatted with the strftime function with the zsh extensions
described for the tt(%D{)var(string)tt(}) prompt format in
ifzman(the section EXPANSION OF PROMPT SEQUENCES in zmanref(zshmisc))\
ifnzman(noderef(Prompt Expansion)). The resulting formatted string must be
no more than 256 characters or will not be printed
)
sitem(tt(-D))(prints elapsed times; may be combined with one of the
options above)
endsitem()
cindex(history, stack)
cindex(stack, history)
`tt(fc -p)' pushes the current history list onto a stack and switches to a
new history list. If the tt(-a) option is also specified, this history list
will be automatically popped when the current function scope is exited, which
is a much better solution than creating a trap function to call `tt(fc -P)'
manually. If no arguments are specified, the history list is left empty,
tt($HISTFILE) is unset, and tt($HISTSIZE) & tt($SAVEHIST) are set to their
default values. If one argument is given, tt($HISTFILE) is set to that
filename, tt($HISTSIZE) & tt($SAVEHIST) are left unchanged, and the history
file is read in (if it exists) to initialize the new list. If a second
argument is specified, tt($HISTSIZE) & tt($SAVEHIST) are instead set to the
single specified numeric value. Finally, if a third argument is specified,
tt($SAVEHIST) is set to a separate value from tt($HISTSIZE). You are free to
change these environment values for the new history list however you desire
in order to manipulate the new history list.
`tt(fc -P)' pops the history list back to an older list saved by `tt(fc -p)'.
The current list is saved to its tt($HISTFILE) before it is destroyed
(assuming that tt($HISTFILE) and tt($SAVEHIST) are set appropriately, of
course). The values of tt($HISTFILE), tt($HISTSIZE), and tt($SAVEHIST) are
restored to the values they had when `tt(fc -p)' was called. Note that this
restoration can conflict with making these variables "local", so your best
bet is to avoid local declarations for these variables in functions that use
`tt(fc -p)'. The one other guaranteed-safe combination is declaring these
variables to be local at the top of your function and using the automatic
option (tt(-a)) with `tt(fc -p)'. Finally, note that it is legal to manually
pop a push marked for automatic popping if you need to do so before the
function exits.
cindex(history, file)
cindex(file, history)
`tt(fc -R)' reads the history from the given file,
`tt(fc -W)' writes the history out to the given file,
and `tt(fc -A)' appends the history out to the given file.
If no filename is specified, the tt($HISTFILE) is assumed.
If the tt(-I) option is added to tt(-R), only those events that are
not already contained within the internal history list are added.
If the tt(-I) option is added to tt(-A) or tt(-W), only those
events that are new since last incremental append/write to
the history file are appended/written.
In any case, the created file will have no more than tt($SAVEHIST)
entries.
)
findex(fg)
cindex(jobs, foregrounding)
cindex(jobs, resuming)
xitem(tt(fg) [ var(job) ... ])
item(var(job) ...)(
Bring each specified var(job) in turn to the foreground.
If no var(job) is specified, resume the current job.
)
findex(float)
item(tt(float) [ {tt(PLUS())|tt(-)}tt(Hghlprtux) ] \
[ {tt(PLUS())|tt(-)}tt(EFLRZ) [ var(n) ] ] [ var(name)[tt(=)var(value)] ... ])(
Equivalent to tt(typeset -E), except that options irrelevant to floating
point numbers are not permitted.
)
findex(functions)
xitem(tt(functions) [ {tt(PLUS())|tt(-)}tt(UkmtTuWz) ] [ tt(-x) var(num) ] [ var(name) ... ])
xitem(tt(functions -c) var(oldfn) var(newfn))
xitem(tt(functions -M) [tt(-s)] var(mathfn) [ var(min) [ var(max) [ var(shellfn) ] ] ])
xitem(tt(functions -M) [ tt(-m) var(pattern) ... ])
item(tt(functions +M) [ tt(-m) ] var(mathfn) ... )(
Equivalent to tt(typeset -f), with the exception of the tt(-c), tt(-x),
tt(-M) and tt(-W) options. For tt(functions -u) and tt(functions -U),
see tt(autoload), which provides additional options.
The tt(-x) option indicates that any functions output will have
each leading tab for indentation, added by the shell to show syntactic
structure, expanded to the given number var(num) of spaces. var(num)
can also be 0 to suppress all indentation.
The tt(-W) option turns on the option tt(WARN_NESTED_VAR) for the named
function or functions only. The option is turned off at the start of
nested functions (apart from anonoymous functions) unless the called
function also has the tt(-W) attribute.
The tt(-c) option causes var(oldfn) to be copied to var(newfn). The
copy is efficiently handled internally by reference counting. If
var(oldfn) was marked for autoload it is first loaded and if this
fails the copy fails. Either function may subsequently be redefined
without affecting the other. A typical idiom is that var(oldfn) is the
name of a library shell function which is then redefined to call
tt(newfn), thereby installing a modified version of the function.
Use of the tt(-M) option may not be combined with any of the options
handled by tt(typeset -f).
tt(functions -M) var(mathfn) defines var(mathfn) as the name of
a mathematical function recognised in all forms of arithmetical expressions;
see
ifzman(the section `Arithmetic Evaluation' in zmanref(zshmisc))\
ifnzman(noderef(Arithmetic Evaluation))\
. By default var(mathfn) may take
any number of comma-separated arguments. If var(min) is given,
it must have exactly var(min) args; if var(min) and var(max) are
both given, it must have at least var(min) and at most var(max)
args. var(max) may be -1 to indicate that there is no upper limit.
By default the function is implemented by a shell function of the same
name; if var(shellfn) is specified it gives the name of the corresponding
shell function while var(mathfn) remains the name used in arithmetical
expressions. The name of the function in tt($0) is var(mathfn) (not
var(shellfn) as would usually be the case), provided the option
tt(FUNCTION_ARGZERO) is in effect. The positional parameters in the shell
function correspond to the arguments of the mathematical function call.
The result of the last arithmetical expression evaluated
inside the shell function (even if it is a form that normally only returns
a status) gives the result of the mathematical function.
If the additional option tt(-s) is given to tt(functions -M), the
argument to the function is a single string: anything between the
opening and matching closing parenthesis is passed to the function as a
single argument, even if it includes commas or white space. The minimum
and maximum argument specifiers must therefore be 1 if given. An empty
argument list is passed as a zero-length string.
tt(functions -M) with no arguments lists all such user-defined functions in
the same form as a definition. With the additional option tt(-m) and
a list of arguments, all functions whose var(mathfn) matches one of
the pattern arguments are listed.
tt(function +M) removes the list of mathematical functions; with the
additional option tt(-m) the arguments are treated as patterns and
all functions whose var(mathfn) matches the pattern are removed. Note
that the shell function implementing the behaviour is not removed
(regardless of whether its name coincides with var(mathfn)).
For example, the following prints the cube of 3:
example(zmath_cube+LPAR()RPAR() { (( $1 * $1 * $1 )) }
functions -M cube 1 1 zmath_cube
print $(( cube+LPAR()3+RPAR() )))
The following string function takes a single argument, including
the commas, so prints 11:
example(stringfn+LPAR()RPAR() { (( $#1 )) }
functions -Ms stringfn
print $(( stringfn+LPAR()foo,bar,rod+RPAR() )))
)
module(getcap)(zsh/cap)
findex(getln)
cindex(line, reading)
cindex(reading a line)
item(tt(getln) [ tt(-AclneE) ] var(name) ...)(
Read the top value from the buffer stack and put it in
the shell parameter var(name). Equivalent to
tt(read -zr).
)
findex(getopts)
cindex(options, processing)
item(tt(getopts) var(optstring) var(name) [ var(arg) ... ])(
Checks the var(arg)s for legal options. If the var(arg)s are omitted,
use the positional parameters. A valid option argument
begins with a `tt(PLUS())' or a `tt(-)'. An argument not beginning with
a `tt(PLUS())' or a `tt(-)', or the argument `tt(-)tt(-)', ends the options.
Note that a single `tt(-)' is not considered a valid option argument.
var(optstring) contains the letters that tt(getopts)
recognizes. If a letter is followed by a `tt(:)', that option
requires an argument. The options can be
separated from the argument by blanks.
Each time it is invoked, tt(getopts) places the option letter it finds
in the shell parameter var(name), prepended with a `tt(PLUS())' when
var(arg) begins with a `tt(PLUS())'. The index of the next var(arg)
is stored in tt(OPTIND). The option argument, if any,
is stored in tt(OPTARG).
vindex(OPTIND, use of)
vindex(OPTARG, use of)
The first option to be examined may be changed by explicitly assigning
to tt(OPTIND). tt(OPTIND) has an initial value of tt(1), and is
normally set to tt(1) upon entry to a shell function and restored
upon exit (this is disabled by the tt(POSIX_BUILTINS) option). tt(OPTARG)
is not reset and retains its value from the most recent call to
tt(getopts). If either of tt(OPTIND) or tt(OPTARG) is explicitly
unset, it remains unset, and the index or option argument is not
stored. The option itself is still stored in var(name) in this case.
A leading `tt(:)' in var(optstring) causes tt(getopts) to store the
letter of any invalid option in tt(OPTARG), and to set var(name) to
`tt(?)' for an unknown option and to `tt(:)' when a required argument is
missing. Otherwise, tt(getopts) sets var(name) to `tt(?)' and prints
an error message when an option is invalid. The exit status is
nonzero when there are no more options.
)
findex(hash)
item(tt(hash) [ tt(-Ldfmrv) ] [ var(name)[tt(=)var(value)] ] ...)(
tt(hash) can be used to directly modify the contents of the command
hash table, and the named directory hash table. Normally one would
modify these tables by modifying one's tt(PATH)
(for the command hash table) or by creating appropriate shell parameters
(for the named directory hash table).
The choice of hash table to work on is determined by the tt(-d) option;
without the option the command hash table is used, and with the option the
named directory hash table is used.