upstream/opnsense-src
1
0
Fork 0
mirror of https://github.com/opnsense/src.git synced 2026-06-11 09:41:03 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

builtin.1: streamlined rewrite + document keybinds

Browse source 
+ clean title: one line with keywords, builtin's mlinked
+ additional search terms: FreeBSD, index
+ synopsis: builtins are documented in your shell's manual
+ clear/scoped introduction: increase straightforwardness
+ table alignment fixed, now renders nicely on MANWIDTH=59
+ keybindings: fundamentals now documented, more please?
+ improved structure and flow, and a spdx tag
+ remove info(1) from SEE ALSO

MFC after:	3 days
Discussed with:	imp,jlduran
Reviewed by:	imp
Closes:		https://github.com/freebsd/freebsd-src/pull/1481
This commit is contained in:
Alexander Ziaee 2024-10-17 18:43:14 -04:00
parent 8adb3acb63
commit 42df4faf70
No known key found for this signature in database
GPG key ID: 0A8F850BCDEF4511
2 changed files with 93 additions and 177 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
share/man/man1/Makefile
View file

@ -55,6 +55,7 @@ MLINKS= builtin.1 alias.1 \
builtin.1 if.1 \
builtin.1 jobid.1 \
builtin.1 jobs.1 \
builtin.1 keybinds.1 \
builtin.1 limit.1 \
builtin.1 log.1 \
builtin.1 logout.1 \

269
share/man/man1/builtin.1
View file

@ -1,4 +1,6 @@
.\"
.\" SPDX-License-Identifier: BSD-2-Clause
.\"
.\" Copyright (c) 1999 Sheldon Hearn
.\"
.\" All rights reserved.
@ -24,175 +26,33 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd December 21, 2010
.Dd March 29, 2025
.Dt BUILTIN 1
.Os
.Sh NAME
.Nm builtin ,
.Nm \&! ,
.Nm % ,
.Nm \&. ,
.Nm \&: ,
.Nm @ ,
.Nm \&[ ,
.Nm { ,
.Nm } ,
.Nm alias ,
.Nm alloc ,
.Nm bg ,
.Nm bind ,
.Nm bindkey ,
.Nm break ,
.Nm breaksw ,
.Nm builtins ,
.Nm case ,
.Nm cd ,
.Nm chdir ,
.Nm command ,
.Nm complete ,
.Nm continue ,
.Nm default ,
.Nm dirs ,
.Nm do ,
.Nm done ,
.Nm echo ,
.Nm echotc ,
.Nm elif ,
.Nm else ,
.Nm end ,
.Nm endif ,
.Nm endsw ,
.Nm esac ,
.Nm eval ,
.Nm exec ,
.Nm exit ,
.Nm export ,
.Nm false ,
.Nm fc ,
.Nm fg ,
.Nm filetest ,
.Nm fi ,
.Nm for ,
.Nm foreach ,
.Nm getopts ,
.Nm glob ,
.Nm goto ,
.Nm hash ,
.Nm hashstat ,
.Nm history ,
.Nm hup ,
.Nm if ,
.Nm jobid ,
.Nm jobs ,
.Nm kill ,
.Nm limit ,
.Nm local ,
.Nm log ,
.Nm login ,
.Nm logout ,
.Nm ls-F ,
.Nm nice ,
.Nm nohup ,
.Nm notify ,
.Nm onintr ,
.Nm popd ,
.Nm printenv ,
.Nm printf ,
.Nm pushd ,
.Nm pwd ,
.Nm read ,
.Nm readonly ,
.Nm rehash ,
.Nm repeat ,
.Nm return ,
.Nm sched ,
.Nm set ,
.Nm setenv ,
.Nm settc ,
.Nm setty ,
.Nm setvar ,
.Nm shift ,
.Nm source ,
.Nm stop ,
.Nm suspend ,
.Nm switch ,
.Nm telltc ,
.Nm test ,
.Nm then ,
.Nm time ,
.Nm times ,
.Nm trap ,
.Nm true ,
.Nm type ,
.Nm ulimit ,
.Nm umask ,
.Nm unalias ,
.Nm uncomplete ,
.Nm unhash ,
.Nm unlimit ,
.Nm unset ,
.Nm unsetenv ,
.Nm until ,
.Nm wait ,
.Nm where ,
.Nm which ,
.Nm while
.Nd shell built-in commands
.Nm keybinds
.Nd index of FreeBSD shell built-in commands
.Sh SYNOPSIS
See the built-in command description in the appropriate shell manual page.
See the manual for your shell for operation details.
.Sh DESCRIPTION
Shell builtin commands are commands that can be executed within the
running shell's process.
Note that, in the case of
.Xr csh 1
builtin commands, the command is executed in a subshell if it occurs as
any component of a pipeline except the last.
.Pp
If a command specified to the shell contains a slash
.Ql / ,
the shell will not execute a builtin command, even if the last component
of the specified command matches the name of a builtin command.
Thus, while specifying
.Dq Li echo
causes a builtin command to be executed under shells that support the
.Nm echo
builtin command,
specifying
.Dq Li /bin/echo
or
.Dq Li ./echo
does not.
.Pp
While some builtin commands may exist in more than one shell, their
operation may be different under each shell which supports them.
Below is a table which lists shell builtin commands, the standard shells
that support them and whether they exist as standalone utilities.
.Pp
Only builtin commands for the
This page provides an index of
.Nm
commands, keywords, and keyboard bindings provided by
.Xr csh 1
and
.Xr sh 1
shells are listed here.
Consult a shell's manual page for
details on the operation its builtin commands.
Beware that the
.Xr sh 1
manual page, at least, calls some of these commands
.Dq built-in commands
and some of them
.Dq reserved words .
Users of other shells may need to consult an
.Xr info 1
page or other sources of documentation.
.Pp
Commands marked
.Dq Li No**
under
.Em External
do exist externally,
but are implemented as scripts using a builtin command of the same name.
.Bl -column ".Ic uncomplete" ".Em External" ".Xr csh 1" ".Xr sh 1" -offset indent
.It Em Command Ta Em External Ta Xr csh 1 Ta Xr sh 1
.Xr sh 1 ,
the command line interpreters which comprise the
.Bx
user environment.
.Ss Commands
Below is a table which lists
.Nm
commands and keywords,
whether they exist as standalone utilities,
and the standard shells that provide them.
.Bl -column "uncomplete" "Standalone" "csh(1)" "sh(1)" -offset indent
.It Em Command Ta Em Standalone Ta Xr csh 1 Ta Xr sh 1
.It Ic \&! Ta \&No Ta \&No Ta Yes
.It Ic % Ta \&No Ta Yes Ta \&No
.It Ic \&. Ta \&No Ta \&No Ta Yes
@ -201,9 +61,9 @@ but are implemented as scripts using a builtin command of the same name.
.It Ic \&[ Ta Yes Ta \&No Ta Yes
.It Ic { Ta \&No Ta \&No Ta Yes
.It Ic } Ta \&No Ta \&No Ta Yes
.It Ic alias Ta No** Ta Yes Ta Yes
.It Ic alias Ta No* Ta Yes Ta Yes
.It Ic alloc Ta \&No Ta Yes Ta \&No
.It Ic bg Ta No** Ta Yes Ta Yes
.It Ic bg Ta No* Ta Yes Ta Yes
.It Ic bind Ta \&No Ta \&No Ta Yes
.It Ic bindkey Ta \&No Ta Yes Ta \&No
.It Ic break Ta \&No Ta Yes Ta Yes
@ -211,9 +71,9 @@ but are implemented as scripts using a builtin command of the same name.
.It Ic builtin Ta \&No Ta \&No Ta Yes
.It Ic builtins Ta \&No Ta Yes Ta \&No
.It Ic case Ta \&No Ta Yes Ta Yes
.It Ic cd Ta No** Ta Yes Ta Yes
.It Ic cd Ta No* Ta Yes Ta Yes
.It Ic chdir Ta \&No Ta Yes Ta Yes
.It Ic command Ta No** Ta \&No Ta Yes
.It Ic command Ta No* Ta \&No Ta Yes
.It Ic complete Ta \&No Ta Yes Ta \&No
.It Ic continue Ta \&No Ta Yes Ta Yes
.It Ic default Ta \&No Ta Yes Ta \&No
@ -233,22 +93,22 @@ but are implemented as scripts using a builtin command of the same name.
.It Ic exit Ta \&No Ta Yes Ta Yes
.It Ic export Ta \&No Ta \&No Ta Yes
.It Ic false Ta Yes Ta \&No Ta Yes
.It Ic fc Ta No** Ta \&No Ta Yes
.It Ic fg Ta No** Ta Yes Ta Yes
.It Ic fc Ta No* Ta \&No Ta Yes
.It Ic fg Ta No* Ta Yes Ta Yes
.It Ic filetest Ta \&No Ta Yes Ta \&No
.It Ic fi Ta \&No Ta \&No Ta Yes
.It Ic for Ta \&No Ta \&No Ta Yes
.It Ic foreach Ta \&No Ta Yes Ta \&No
.It Ic getopts Ta No** Ta \&No Ta Yes
.It Ic getopts Ta No* Ta \&No Ta Yes
.It Ic glob Ta \&No Ta Yes Ta \&No
.It Ic goto Ta \&No Ta Yes Ta \&No
.It Ic hash Ta No** Ta \&No Ta Yes
.It Ic hash Ta No* Ta \&No Ta Yes
.It Ic hashstat Ta \&No Ta Yes Ta \&No
.It Ic history Ta \&No Ta Yes Ta \&No
.It Ic hup Ta \&No Ta Yes Ta \&No
.It Ic if Ta \&No Ta Yes Ta Yes
.It Ic jobid Ta \&No Ta \&No Ta Yes
.It Ic jobs Ta No** Ta Yes Ta Yes
.It Ic jobs Ta No* Ta Yes Ta Yes
.It Ic kill Ta Yes Ta Yes Ta Yes
.It Ic limit Ta \&No Ta Yes Ta \&No
.It Ic local Ta \&No Ta \&No Ta Yes
@ -265,7 +125,7 @@ but are implemented as scripts using a builtin command of the same name.
.It Ic printf Ta Yes Ta \&No Ta Yes
.It Ic pushd Ta \&No Ta Yes Ta \&No
.It Ic pwd Ta Yes Ta \&No Ta Yes
.It Ic read Ta No** Ta \&No Ta Yes
.It Ic read Ta No* Ta \&No Ta Yes
.It Ic readonly Ta \&No Ta \&No Ta Yes
.It Ic rehash Ta \&No Ta Yes Ta \&No
.It Ic repeat Ta \&No Ta Yes Ta \&No
@ -288,26 +148,68 @@ but are implemented as scripts using a builtin command of the same name.
.It Ic times Ta \&No Ta \&No Ta Yes
.It Ic trap Ta \&No Ta \&No Ta Yes
.It Ic true Ta Yes Ta \&No Ta Yes
.It Ic type Ta No** Ta \&No Ta Yes
.It Ic ulimit Ta No** Ta \&No Ta Yes
.It Ic umask Ta No** Ta Yes Ta Yes
.It Ic unalias Ta No** Ta Yes Ta Yes
.It Ic type Ta No* Ta \&No Ta Yes
.It Ic ulimit Ta No* Ta \&No Ta Yes
.It Ic umask Ta No* Ta Yes Ta Yes
.It Ic unalias Ta No* Ta Yes Ta Yes
.It Ic uncomplete Ta \&No Ta Yes Ta \&No
.It Ic unhash Ta \&No Ta Yes Ta \&No
.It Ic unlimit Ta \&No Ta Yes Ta \&No
.It Ic unset Ta \&No Ta Yes Ta Yes
.It Ic unsetenv Ta \&No Ta Yes Ta \&No
.It Ic until Ta \&No Ta \&No Ta Yes
.It Ic wait Ta No** Ta Yes Ta Yes
.It Ic wait Ta No* Ta Yes Ta Yes
.It Ic where Ta \&No Ta Yes Ta \&No
.It Ic which Ta Yes Ta Yes Ta \&No
.It Ic while Ta \&No Ta Yes Ta Yes
.El
.Pp
\&No*: Commands marked
.Ql No*
exist externally, but are implemented as scripts using a
.Nm
command of the same name.
.Ss Keybinds
The command line environment also provides the following
default keyboard bindings:
.Bl -column "Process Info (SIGINFO)" "^M | ^J" "^M | ^J" -offset indent
.It Em Signal Ta Xr csh 1 Ta Xr sh 1
.It Ic Backspace Ta ^H Ta ^H
.It Ic Carriage Return Ta ^M | ^J Ta ^M | ^J
.It Ic Tab Ta ^I Ta ^I
.It Ic Beginning of Line Ta ^A Ta ^A
.It Ic End of Line Ta ^E Ta ^E
.It Ic Cursor Forward Ta ^F Ta ^F
.It Ic Cursor Backward Ta ^B Ta ^B
.It Ic Clear Screen Ta ^L Ta ^L
.It Ic Cut Line Ta ^U Ta ^U
.It Ic Cut Word Backwards Ta ^W Ta ^W
.It Ic Cut Rest of Line Ta ^K Ta ^K
.It Ic Paste Last Cut Ta ^Y Ta ^Y
.It Ic Typo Ta ^T Ta ^T
.It End of File Po Ic EOF Pc Ta ^D Ta ^D
.It Interupt Po Ic SIGINT Pc Ta ^C Ta ^C
.It Process info Po Ic SIGINFO Pc Ta ^T Ta ^T
.It Ic Search History Ta \&No Ta ^R
.It Ic Exit Search History Ta \&No Ta ^G
.It Ic Previous Command Ta ^P Ta ^P
.It Ic Next Command Ta ^N Ta ^N
.It Ic Print Next Character Ta ^V Ta ^V
.It Ic Pause Job Ta ^S Ta ^S
.It Ic Resume Job Ta ^Q Ta ^Q
.It Suspend Job Ic (SIGTSTP) Ta ^Z Ta ^Z
.It Ic Scrollback Mode Ta ScrLk* Ta ScrLk*
.El
.Pp
\&*: Bindings marked
.Ql *
are provided by
.Xr vt 4 ,
the console driver.
.Sh SEE ALSO
.Xr csh 1 ,
.Xr echo 1 ,
.Xr false 1 ,
.Xr info 1 ,
.Xr kill 1 ,
.Xr login 1 ,
.Xr nice 1 ,
@ -326,5 +228,18 @@ The
manual page first appeared in
.Fx 3.4 .
.Sh AUTHORS
.An -nosplit
This manual page was written by
.An Alexander Ziaee Aq Mt ziaee@FreeBSD.org
from an earlier version by
.An Sheldon Hearn Aq Mt sheldonh@FreeBSD.org .
.Sh CAVEATS
While
.Nm
commands may exist in more than one shell or standalone,
each may be implemented differently.
.Pp
Standalone utilities and their manuals must be called by their path
from a shell with a
.Nm
command of the same name.