From 0385654986e1d7d597a5241a58d7956d7f01dd8d Mon Sep 17 00:00:00 2001 From: Alejandro Cervera <96702705+tricantivu@users.noreply.github.com> Date: Sun, 7 Jan 2024 17:38:34 -0500 Subject: [PATCH] common/*: update pages of some POSIX special built-in utilities (#11956) * exec, export, readonly, set, shift, trap: replace command descriptions * exec, exit, export, readonly, set, shift, trap, exec, export: replace example descriptions * exec, trap: replace "More information" links * trap: remove prefix "SIG" from some command arguments Although POSIX allows implementations to specify signal names without the prefix "SIG", I will choose the most portable form. * export: replace term Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * set: replace term Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * export: replace term Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * export: replace term Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * exec: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * exit: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * export: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * readonly: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * set: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * shift: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * trap: replace Open Group link Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> * exec: explain environment of child process Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> --------- Co-authored-by: Vitor Henrique <87824454+vitorhcl@users.noreply.github.com> --- pages/common/exec.md | 6 +++--- pages/common/exit.md | 6 +++--- pages/common/export.md | 8 ++++---- pages/common/readonly.md | 7 +++---- pages/common/set.md | 12 ++++++------ pages/common/shift.md | 8 ++++---- pages/common/trap.md | 15 +++++++-------- pages/linux/exec.md | 14 +++++++------- pages/linux/export.md | 10 +++++----- pages/linux/trap.md | 13 ++++++------- 10 files changed, 48 insertions(+), 51 deletions(-) diff --git a/pages/common/exec.md b/pages/common/exec.md index a05af53f3..c8434135f 100644 --- a/pages/common/exec.md +++ b/pages/common/exec.md @@ -1,8 +1,8 @@ # exec -> Replace the current process with another process. -> More information: . +> Execute a command without creating a child process. +> More information: . -- Replace with the specified command using the current environment variables: +- Execute a specific command using the current environment variables: `exec {{command -with -flags}}` diff --git a/pages/common/exit.md b/pages/common/exit.md index 60aa9d89e..17be8388d 100644 --- a/pages/common/exit.md +++ b/pages/common/exit.md @@ -1,12 +1,12 @@ # exit > Exit the shell. -> More information: . +> More information: . -- Exit the shell with the exit code of the last command executed: +- Exit with the exit status of the most recently executed command: `exit` -- Exit the shell with the specified exit code: +- Exit with a specific exit status: `exit {{exit_code}}` diff --git a/pages/common/export.md b/pages/common/export.md index 9336f2171..33cd5ffe4 100644 --- a/pages/common/export.md +++ b/pages/common/export.md @@ -1,12 +1,12 @@ # export -> Command to mark shell variables in the current environment to be exported with any newly forked child processes. -> More information: . +> Export shell variables to child processes. +> More information: . -- Set a new environment variable: +- Set an environment variable: `export {{VARIABLE}}={{value}}` -- Append something to the PATH variable: +- Append a pathname to the environment variable `PATH`: `export PATH=$PATH:{{path/to/append}}` diff --git a/pages/common/readonly.md b/pages/common/readonly.md index f674724c5..d396ce141 100644 --- a/pages/common/readonly.md +++ b/pages/common/readonly.md @@ -1,10 +1,9 @@ # readonly -> Create or modify read-only variables within a shell script, preventing the variable from being changed by subsequent commands. -> This is useful when you want to ensure that a variable retains a constant value throughout the execution of a script. -> More information: . +> Set read-only shell variables. +> More information: . -- Create a read-only variable: +- Set a read-only variable: `readonly {{variable_name}}={{value}}` diff --git a/pages/common/set.md b/pages/common/set.md index c3afd93d7..703f4bf2a 100644 --- a/pages/common/set.md +++ b/pages/common/set.md @@ -1,24 +1,24 @@ # set -> Display, set or unset values of shell attributes and positional parameters. -> More information: . +> Toggle shell options or set the values of positional parameters. +> More information: . - Display the names and values of shell variables: `set` -- Mark variables that are modified or created for export: +- Export newly initialized variables to child processes: `set -a` -- Notify of job termination immediately: +- Write formatted messages to `stderr` when jobs finish: `set -b` -- Set various options, e.g. enable `vi` style line editing: +- Write and edit text in the command line with `vi`-like keybindings (e.g. `yy`): `set -o {{vi}}` -- Set the shell to exit as soon as the first error is encountered (mostly used in scripts): +- Exit the shell when (some) commands fail: `set -e` diff --git a/pages/common/shift.md b/pages/common/shift.md index 52cb27539..937896660 100644 --- a/pages/common/shift.md +++ b/pages/common/shift.md @@ -1,12 +1,12 @@ # shift -> Shell built-in command that shifts the arguments passed to the calling function or script by a specified number of places. -> More information: . +> Move positional parameters. +> More information: . -- Move arguments by one place dropping the first argument: +- Remove the first positional parameter: `shift` -- Move arguments by N places dropping the first N arguments: +- Remove the first `N` positional parameters: `shift {{N}}` diff --git a/pages/common/trap.md b/pages/common/trap.md index 2104c234d..2453efcf7 100644 --- a/pages/common/trap.md +++ b/pages/common/trap.md @@ -1,17 +1,16 @@ # trap -> Automatically execute commands after receiving signals by processes or the operating system. -> Can be used to perform cleanups for interruptions by the user or other actions. -> More information: . +> Execute a command upon an event. +> More information: . -- List active traps for the current shell: +- List the commands and the names of the expected events: `trap` -- Set a trap to execute commands when one or more signals are detected: +- Execute a command when a signal is received: -`trap 'echo "Caught signal {{SIGHUP}}"' {{SIGHUP}}` +`trap 'echo "Caught signal {{SIGHUP}}"' {{HUP}}` -- Remove active traps: +- Remove commands: -`trap - {{SIGHUP}} {{SIGINT}}` +`trap - {{HUP}} {{INT}}` diff --git a/pages/linux/exec.md b/pages/linux/exec.md index 00d27a22f..5080e41f6 100644 --- a/pages/linux/exec.md +++ b/pages/linux/exec.md @@ -1,20 +1,20 @@ # exec -> Replace the current process with another process. -> More information: . +> Execute a command without creating a child process. +> More information: . -- Replace with the specified command using the current environment variables: +- Execute a specific command: `exec {{command -with -flags}}` -- Replace with the specified command, clearing environment variables: +- Execute a command with a (mostly) empty environment: `exec -c {{command -with -flags}}` -- Replace with the specified command and login using the default shell: +- Execute a command as a login shell: `exec -l {{command -with -flags}}` -- Replace with the specified command and change the process name: +- Execute a command with a different name: -`exec -a {{process_name}} {{command -with -flags}}` +`exec -a {{name}} {{command -with -flags}}` diff --git a/pages/linux/export.md b/pages/linux/export.md index b55408112..c9ef7df52 100644 --- a/pages/linux/export.md +++ b/pages/linux/export.md @@ -1,20 +1,20 @@ # export -> Command to mark shell variables in the current environment to be exported with any newly forked child processes. +> Export shell variables to child processes. > More information: . -- Set a new environment variable: +- Set an environment variable: `export {{VARIABLE}}={{value}}` -- Remove an environment variable: +- Unset an environment variable: `export -n {{VARIABLE}}` -- Mark a shell function for export: +- Export a function to child processes: `export -f {{FUNCTION_NAME}}` -- Append something to the PATH variable: +- Append a pathname to the environment variable `PATH`: `export PATH=$PATH:{{path/to/append}}` diff --git a/pages/linux/trap.md b/pages/linux/trap.md index 98dc02d8b..bdc37ee45 100644 --- a/pages/linux/trap.md +++ b/pages/linux/trap.md @@ -1,21 +1,20 @@ # trap -> Automatically execute commands after receiving signals by processes or the operating system. -> Can be used to perform cleanups for interruptions by the user or other actions. -> More information: . +> Execute a command upon an event. +> More information: . -- List available signals to set traps for: +- List the available event names (e.g. `SIGWINCH`): `trap -l` -- List active traps for the current shell: +- List the commands and the names of the expected events: `trap -p` -- Set a trap to execute commands when one or more signals are detected: +- Execute a command when a signal is received: `trap 'echo "Caught signal {{SIGHUP}}"' {{SIGHUP}}` -- Remove active traps: +- Remove commands: `trap - {{SIGHUP}} {{SIGINT}}`