fish-shell/doc_src/cmds/jobs.rst

.. _cmd-jobs:

jobs - print currently running jobs
===================================

Synopsis
--------

``jobs`` [*OPTIONS*] [ *PID* | %*JOBID* ]


Description
-----------

``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.

jobs accepts the following switches:

- ``-c`` or ``--command`` prints the command name for each process in jobs.

- ``-g`` or ``--group`` only prints the group ID of each job.

- ``-l`` or ``--last`` prints only the last job to be started.

- ``-p`` or ``--pid`` prints the process ID for each process in all jobs.

- ``-q`` or ``--query`` prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).

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.

Example
-------

``jobs`` outputs a summary of the current jobs, such as two long-running tasks in this example:

.. code-block:: none

   Job Group   State   Command
   2   26012   running nc -l 55232 < /dev/random &
   1   26011   running python tests/test_11.py &
docs: Add labels to all commands This allows us to use :ref: references, which don't require hardcoding it as html [ci skip] 2019-03-31 09:05:09 +00:00			`.. _cmd-jobs:`

Switch command docs from \section to reStructuredText 2018-12-17 01:39:33 +00:00			`jobs - print currently running jobs`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`===================================`
Switch command docs from \section to reStructuredText 2018-12-17 01:39:33 +00:00
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00			`Synopsis`
			`--------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Update synopsis of a few stragglers. 2021-12-25 00:15:40 +00:00			``jobs`` [OPTIONS] [ PID \| %JOBID ]
Migrate the 'synopsis' sections to .rst format 2018-12-18 01:58:24 +00:00
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Description`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-----------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Fix broken links to index.html in cmd docs 2020-01-31 03:38:56 +00:00			``jobs`` prints a list of the currently running :ref:`jobs <syntax-job-control>` and their status.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`jobs accepts the following switches:`

Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-c`` or ``--command`` prints the command name for each process in jobs.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-g`` or ``--group`` only prints the group ID of each job.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-l`` or ``--last`` prints only the last job to be started.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Switch backticks to double backticks for rst compatibility 2018-12-19 20:02:45 +00:00			- ``-p`` or ``--pid`` prints the process ID for each process in all jobs.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Let command, jobs and type take `--query` instead of `--quiet` Now command, jobs, type, abbr, builtin, functions and set take `-q` to query for existence, but the long option is inconsistent. The first three use `--quiet`, the latter use `--query`. Add `--query` to the first three, but keep `--quiet` around. Fixes #7276. 2020-09-04 14:41:34 +00:00			- ``-q`` or ``--query`` prints no output for evaluation of jobs by exit status only. For compatibility with old fish versions this is also ``--quiet`` (but this is deprecated).
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
			`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\%.`

docs: note job expansion in bg/fg/jobs arguments Discussed in #5019. 2021-02-28 12:56:23 +00:00			Arguments of the form ``PID`` or ``%JOBID`` restrict the output to jobs with the selected process identifiers or job numbers respectively.

docs/jobs: Header is stripped in command substitution 2020-07-02 21:46:54 +00:00			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.

docs: Link builtins When we say "the XYZ command/builtin", we should typically include a link. The exceptions are - In the documentation for that command - no need to link to ulimit in the ulimit page - When we've already linked before - not every thing needs to be clickable, or clicking it will cause the browser to mark fifty words as visited. This is roughly what wikipedia does for crosslinks. [ci skip] 2020-03-21 14:31:25 +00:00			The exit status of ``jobs`` is ``0`` if there are running background jobs and ``1`` otherwise.
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
Convert \\subsection sections into rst format 2018-12-19 02:44:30 +00:00			`Example`
Fix command section separator line lengths 2019-01-03 04:10:47 +00:00			`-------`
Copy doc_src to sphinx_doc_src and add a TOC 2018-12-16 21:08:41 +00:00
docs/jobs: add example output and remove spurious header 2020-07-06 12:48:13 +00:00			``jobs`` outputs a summary of the current jobs, such as two long-running tasks in this example:

			`.. code-block:: none`

			`Job Group State Command`
			`2 26012 running nc -l 55232 < /dev/random &`
			`1 26011 running python tests/test_11.py &`