diff --git a/man/systemctl.xml b/man/systemctl.xml index 1c55028837..802824d438 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -50,7 +50,7 @@ The following commands are understood: - Unit Commands + Unit Commands (Introspection and Modification) @@ -151,6 +151,196 @@ Sun 2017-02-26 20:57:49 EST 2h 3min left Sun 2017-02-26 11:56:36 EST 6h ago + + is-active PATTERN… + + + Check whether any of the specified units are active + (i.e. running). Returns an exit code + 0 if at least one is active, or + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. + + + + + is-failed PATTERN… + + + Check whether any of the specified units are in a + "failed" state. Returns an exit code + 0 if at least one has failed, + non-zero otherwise. Unless is + specified, this will also print the current unit state to + standard output. + + + + + status PATTERN…|PID…] + + + Show terse runtime status information about one or + more units, followed by most recent log data from the + journal. If no units are specified, show system status. If + combined with , also show the status of + all units (subject to limitations specified with + ). If a PID is passed, show information + about the unit the process belongs to. + + This function is intended to generate human-readable + output. If you are looking for computer-parsable output, + use show instead. By default, this + function only shows 10 lines of output and ellipsizes + lines to fit in the terminal window. This can be changed + with and , + see above. In addition, journalctl + --unit=NAME or + journalctl + --user-unit=NAME use + a similar filter for messages and might be more + convenient. + + + systemd implicitly loads units as necessary, so just running the status will + attempt to load a file. The command is thus not useful for determining if something was already loaded or + not. The units may possibly also be quickly unloaded after the operation is completed if there's no reason + to keep it in memory thereafter. + + + + Example output from systemctl status + + $ systemctl status bluetooth +● bluetooth.service - Bluetooth service + Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled) + Active: active (running) since Wed 2017-01-04 13:54:04 EST; 1 weeks 0 days ago + Docs: man:bluetoothd(8) + Main PID: 930 (bluetoothd) + Status: "Running" + Tasks: 1 + Memory: 648.0K + CPU: 435ms + CGroup: /system.slice/bluetooth.service + └─930 /usr/lib/bluetooth/bluetoothd + +Jan 12 10:46:45 example.com bluetoothd[8900]: Not enough free handles to register service +Jan 12 10:46:45 example.com bluetoothd[8900]: Current Time Service could not be registered +Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output error (5) + + + The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White + indicates an inactive or deactivating state. Red indicates a + failed or error state and green indicates an + active, reloading or activating state. + + + The "Loaded:" line in the output will show loaded if the unit has been loaded into + memory. Other possible values for "Loaded:" include: error if there was a problem + loading it, not-found if no unit file was found for this unit, + bad-setting if an essential unit file setting could not be parsed and + masked if the unit file has been masked. Along with showing the path to the unit file, + this line will also show the enablement state. Enabled commands start at boot. See the full table of + possible enablement states — including the definition of masked — in the documentation + for the is-enabled command. + + + The "Active:" line shows active state. The value is usually active or + inactive. Active could mean started, bound, plugged in, etc depending on the unit type. + The unit could also be in process of changing states, reporting a state of activating or + deactivating. A special failed state is entered when the service + failed in some way, such as a crash, exiting with an error code or timing out. If the failed state is + entered the cause will be logged for later reference. + + + + + + + show PATTERN…|JOB… + + + Show properties of one or more units, jobs, or the manager itself. If no argument is specified, + properties of the manager will be shown. If a unit name is specified, properties of the unit are shown, and + if a job ID is specified, properties of the job are shown. By default, empty properties are suppressed. Use + to show those too. To select specific properties to show, use + . This command is intended to be used whenever computer-parsable output is + required. Use status if you are looking for formatted human-readable output. + + Many properties shown by systemctl show map directly to configuration settings of + the system and service manager and its unit files. Note that the properties shown by the command are + generally more low-level, normalized versions of the original configuration settings and expose runtime + state in addition to configuration. For example, properties shown for service units include the service's + current main process identifier as MainPID (which is runtime state), and time settings + are always exposed as properties ending in the …USec suffix even if a matching + configuration options end in …Sec, because microseconds is the normalized time unit used + internally by the system and service manager. + + For details about many of these properties, see the documentation of the D-Bus interface + backing these properties, see + org.freedesktop.systemd15. + + + + + cat PATTERN… + + + Show backing files of one or more units. Prints the + "fragment" and "drop-ins" (source files) of units. Each + file is preceded by a comment which includes the file + name. Note that this shows the contents of the backing files + on disk, which may not match the system manager's + understanding of these units if any unit files were + updated on disk and the daemon-reload + command wasn't issued since. + + + + + help PATTERN…|PID… + + + Show manual pages for one or more units, if + available. If a PID is given, the manual pages for the unit + the process belongs to are shown. + + + + + + list-dependencies + UNIT... + + + + Shows units required and wanted by the specified + units. This recursively lists units following the + Requires=, + Requisite=, + ConsistsOf=, + Wants=, BindsTo= + dependencies. If no units are specified, + default.target is implied. + + By default, only target units are recursively + expanded. When is passed, all other + units are recursively expanded as well. + + Options , + , + may be used to change what types of dependencies + are shown. + + Note that this command only lists units currently loaded into memory by the service manager. In + particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a + specific unit, as it won't list the dependencies declared by units currently not loaded. + + + + + start PATTERN… @@ -325,148 +515,6 @@ Sun 2017-02-26 20:57:49 EST 2h 3min left Sun 2017-02-26 11:56:36 EST 6h ago processes in the unit's cgroup. - - is-active PATTERN… - - - Check whether any of the specified units are active - (i.e. running). Returns an exit code - 0 if at least one is active, or - non-zero otherwise. Unless is - specified, this will also print the current unit state to - standard output. - - - - is-failed PATTERN… - - - Check whether any of the specified units are in a - "failed" state. Returns an exit code - 0 if at least one has failed, - non-zero otherwise. Unless is - specified, this will also print the current unit state to - standard output. - - - - status PATTERN…|PID…] - - - Show terse runtime status information about one or - more units, followed by most recent log data from the - journal. If no units are specified, show system status. If - combined with , also show the status of - all units (subject to limitations specified with - ). If a PID is passed, show information - about the unit the process belongs to. - - This function is intended to generate human-readable - output. If you are looking for computer-parsable output, - use show instead. By default, this - function only shows 10 lines of output and ellipsizes - lines to fit in the terminal window. This can be changed - with and , - see above. In addition, journalctl - --unit=NAME or - journalctl - --user-unit=NAME use - a similar filter for messages and might be more - convenient. - - - systemd implicitly loads units as necessary, so just running the status will - attempt to load a file. The command is thus not useful for determining if something was already loaded or - not. The units may possibly also be quickly unloaded after the operation is completed if there's no reason - to keep it in memory thereafter. - - - - Example output from systemctl status - - $ systemctl status bluetooth -● bluetooth.service - Bluetooth service - Loaded: loaded (/usr/lib/systemd/system/bluetooth.service; enabled; vendor preset: enabled) - Active: active (running) since Wed 2017-01-04 13:54:04 EST; 1 weeks 0 days ago - Docs: man:bluetoothd(8) - Main PID: 930 (bluetoothd) - Status: "Running" - Tasks: 1 - Memory: 648.0K - CPU: 435ms - CGroup: /system.slice/bluetooth.service - └─930 /usr/lib/bluetooth/bluetoothd - -Jan 12 10:46:45 example.com bluetoothd[8900]: Not enough free handles to register service -Jan 12 10:46:45 example.com bluetoothd[8900]: Current Time Service could not be registered -Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output error (5) - - - The dot ("●") uses color on supported terminals to summarize the unit state at a glance. White - indicates an inactive or deactivating state. Red indicates a - failed or error state and green indicates an - active, reloading or activating state. - - - The "Loaded:" line in the output will show loaded if the unit has been loaded into - memory. Other possible values for "Loaded:" include: error if there was a problem - loading it, not-found if no unit file was found for this unit, - bad-setting if an essential unit file setting could not be parsed and - masked if the unit file has been masked. Along with showing the path to the unit file, - this line will also show the enablement state. Enabled commands start at boot. See the full table of - possible enablement states — including the definition of masked — in the documentation - for the is-enabled command. - - - The "Active:" line shows active state. The value is usually active or - inactive. Active could mean started, bound, plugged in, etc depending on the unit type. - The unit could also be in process of changing states, reporting a state of activating or - deactivating. A special failed state is entered when the service - failed in some way, such as a crash, exiting with an error code or timing out. If the failed state is - entered the cause will be logged for later reference. - - - - - - show PATTERN…|JOB… - - - Show properties of one or more units, jobs, or the manager itself. If no argument is specified, - properties of the manager will be shown. If a unit name is specified, properties of the unit are shown, and - if a job ID is specified, properties of the job are shown. By default, empty properties are suppressed. Use - to show those too. To select specific properties to show, use - . This command is intended to be used whenever computer-parsable output is - required. Use status if you are looking for formatted human-readable output. - - Many properties shown by systemctl show map directly to configuration settings of - the system and service manager and its unit files. Note that the properties shown by the command are - generally more low-level, normalized versions of the original configuration settings and expose runtime - state in addition to configuration. For example, properties shown for service units include the service's - current main process identifier as MainPID (which is runtime state), and time settings - are always exposed as properties ending in the …USec suffix even if a matching - configuration options end in …Sec, because microseconds is the normalized time unit used - internally by the system and service manager. - - For details about many of these properties, see the documentation of the D-Bus interface - backing these properties, see - org.freedesktop.systemd15. - - - - cat PATTERN… - - - Show backing files of one or more units. Prints the - "fragment" and "drop-ins" (source files) of units. Each - file is preceded by a comment which includes the file - name. Note that this shows the contents of the backing files - on disk, which may not match the system manager's - understanding of these units if any unit files were - updated on disk and the daemon-reload - command wasn't issued since. - - set-property UNIT PROPERTY=VALUE… @@ -502,16 +550,6 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err - - help PATTERN…|PID… - - - Show manual pages for one or more units, if - available. If a PID is given, the manual pages for the unit - the process belongs to are shown. - - - reset-failed [PATTERN…] @@ -529,37 +567,6 @@ Jan 12 10:46:45 example.com bluetoothd[8900]: gatt-time-server: Input/output err to be started again, use this command to make it startable again. - - - - list-dependencies - UNIT... - - - - Shows units required and wanted by the specified - units. This recursively lists units following the - Requires=, - Requisite=, - ConsistsOf=, - Wants=, BindsTo= - dependencies. If no units are specified, - default.target is implied. - - By default, only target units are recursively - expanded. When is passed, all other - units are recursively expanded as well. - - Options , - , - may be used to change what types of dependencies - are shown. - - Note that this command only lists units currently loaded into memory by the service manager. In - particular, this command is not suitable to get a comprehensive list at all reverse dependencies on a - specific unit, as it won't list the dependencies declared by units currently not loaded. - - diff --git a/src/systemctl/systemctl.c b/src/systemctl/systemctl.c index acf07d645f..7057049c60 100644 --- a/src/systemctl/systemctl.c +++ b/src/systemctl/systemctl.c @@ -7708,6 +7708,16 @@ static int systemctl_help(void) { " ordered by address\n" " list-timers [PATTERN...] List timer units currently in memory,\n" " ordered by next elapse\n" + " is-active PATTERN... Check whether units are active\n" + " is-failed PATTERN... Check whether units are failed\n" + " status [PATTERN...|PID...] Show runtime status of one or more units\n" + " show [PATTERN...|JOB...] Show properties of one or more\n" + " units/jobs or the manager\n" + " cat PATTERN... Show files and drop-ins of specified units\n" + " help PATTERN...|PID... Show manual for one or more units\n" + " list-dependencies [UNIT...] Recursively show units which are required\n" + " or wanted by the units or by which those\n" + " units are required or wanted\n" " start UNIT... Start (activate) one or more units\n" " stop UNIT... Stop (deactivate) one or more units\n" " reload UNIT... Reload one or more units\n" @@ -7723,19 +7733,9 @@ static int systemctl_help(void) { " configuration of unit\n" " freeze PATTERN... Freeze execution of unit processes\n" " thaw PATTERN... Resume execution of a frozen unit\n" - " is-active PATTERN... Check whether units are active\n" - " is-failed PATTERN... Check whether units are failed\n" - " status [PATTERN...|PID...] Show runtime status of one or more units\n" - " show [PATTERN...|JOB...] Show properties of one or more\n" - " units/jobs or the manager\n" - " cat PATTERN... Show files and drop-ins of specified units\n" " set-property UNIT PROPERTY=VALUE... Sets one or more properties of a unit\n" - " help PATTERN...|PID... Show manual for one or more units\n" " reset-failed [PATTERN...] Reset failed state for all, one, or more\n" - " units\n" - " list-dependencies [UNIT...] Recursively show units which are required\n" - " or wanted by the units or by which those\n" - " units are required or wanted" + " units" "\n%3$sUnit File Commands:%4$s\n" " list-unit-files [PATTERN...] List installed unit files\n" " enable [UNIT...|PATH...] Enable one or more unit files\n"