Mirrors/fish-shell
2
0
Fork 0
mirror of https://github.com/fish-shell/fish-shell synced 2024-12-27 21:33:09 +00:00
Code Issues Projects Releases Packages Wiki Activity

docs: note job expansion in bg/fg/jobs arguments

Browse source 
Discussed in #5019.
This commit is contained in:
David Adam 2021-02-28 20:56:23 +08:00
parent 1f3fdf2de6
commit 3e8e864c7c
3 changed files with 15 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

12
doc_src/cmds/bg.rst
View file

@ -15,18 +15,22 @@ Description
``bg`` sends :ref:`jobs <syntax-job-control>` to the background, resuming them if they are stopped.
A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If PID is specified, the jobs with the specified process group IDs are put in the background.
A background job is executed simultaneously with fish, and does not have access to the keyboard. If no job is specified, the last job to be used is put in the background. If ``PID`` is specified, the jobs containing the specified process IDs are put in the background.
When at least one of the arguments isn't a valid job specifier (i.e. PID),
For compatibility with other shells, job expansion syntax is supported for ``bg``. A PID of the format ``%1`` will be interpreted as the PID of job 1. Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
When at least one of the arguments isn't a valid job specifier,
``bg`` will print an error without backgrounding anything.
When all arguments are valid job specifiers, bg will background all matching jobs that exist.
When all arguments are valid job specifiers, ``bg`` will background all matching jobs that exist.
Example
-------
``bg 123 456 789`` will background 123, 456 and 789.
``bg 123 456 789`` will background the jobs that contain processes 123, 456 and 789.
If only 123 and 789 exist, it will still background them and print an error about 456.
``bg 123 banana`` or ``bg banana 123`` will complain that "banana" is not a valid job specifier.
``bg %1`` will background job 1.

5
doc_src/cmds/fg.rst
View file

@ -13,10 +13,13 @@ Synopsis
Description
-----------
``fg`` brings the specified :ref:`job <syntax-job-control>` to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If PID is specified, the job with the specified group ID is put in the foreground.
``fg`` brings the specified :ref:`job <syntax-job-control>` to the foreground, resuming it if it is stopped. While a foreground job is executed, fish is suspended. If no job is specified, the last job to be used is put in the foreground. If ``PID`` is specified, the job containing a process with the specified process ID is put in the foreground.
For compatibility with other shells, job expansion syntax is supported for ``fg``. A ``PID`` of the format ``%1`` will foreground job 1. Job numbers can be seen in the output of :ref:`jobs <cmd-jobs>`.
Example
-------
``fg`` will put the last job in the foreground.
``fg %3`` will put job 3 into the foreground.

4
doc_src/cmds/jobs.rst
View file

@ -8,7 +8,7 @@ Synopsis
::
jobs [OPTIONS] [PID]
jobs [OPTIONS] [ PID | %JOBID ]
Description
@ -30,6 +30,8 @@ jobs accepts the following switches:
On systems that supports this feature, jobs will print the CPU usage of each job since the last command was executed. The CPU usage is expressed as a percentage of full CPU activity. Note that on multiprocessor systems, the total activity may be more than 100\%.
Arguments of the form ``PID`` or ``%JOBID`` restrict the output to jobs with the selected process identifiers or job numbers respectively.
If the output of ``jobs`` is redirected or if it is part of a command substitution, the column header that is usually printed is omitted, making it easier to parse.
The exit status of ``jobs`` is ``0`` if there are running background jobs and ``1`` otherwise.