From: Jan Engelhardt Date: Fri, 27 Jun 2014 22:48:28 +0000 (+0200) Subject: doc: grammatical corrections X-Git-Tag: v215~134 X-Git-Url: https://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=8d0e0ddda6501479eb69164687c83c1a7667b33a doc: grammatical corrections --- diff --git a/CODING_STYLE b/CODING_STYLE index 4ec5923d3..cb8d96c4c 100644 --- a/CODING_STYLE +++ b/CODING_STYLE @@ -10,14 +10,14 @@ - The destructors always unregister the object from the next bigger object, not the other way around -- To minimize strict aliasing violations we prefer unions over casting +- To minimize strict aliasing violations, we prefer unions over casting -- For robustness reasons destructors should be able to destruct +- For robustness reasons, destructors should be able to destruct half-initialized objects, too - Error codes are returned as negative Exxx. i.e. return -EINVAL. There - are some exceptions: for constructors it is OK to return NULL on - OOM. For lookup functions NULL is fine too for "not found". + are some exceptions: for constructors, it is OK to return NULL on + OOM. For lookup functions, NULL is fine too for "not found". Be strict with this. When you write a function that can fail due to more than one cause, it *really* should have "int" as return value @@ -30,7 +30,7 @@ program" code. (With one exception: it's OK to log with DEBUG level from any code, with the exception of maybe inner loops). -- Always check OOM. There's no excuse. In program code you can use +- Always check OOM. There's no excuse. In program code, you can use "log_oom()" for then printing a short message, but not in "library" code. - Do not issue NSS requests (that includes user name and host name @@ -123,19 +123,19 @@ backwards! - Think about the types you use. If a value cannot sensibly be - negative don't use "int", but use "unsigned". + negative, don't use "int", but use "unsigned". - Don't use types like "short". They *never* make sense. Use ints, longs, long longs, all in unsigned+signed fashion, and the fixed - size types uint32_t and so on, as well as size_t but nothing else. + size types uint32_t and so on, as well as size_t, but nothing else. - Public API calls (i.e. functions exported by our shared libraries) must be marked "_public_" and need to be prefixed with "sd_". No other functions should be prefixed like that. -- In public API calls you *must* validate all your input arguments for +- In public API calls, you *must* validate all your input arguments for programming error with assert_return() and return a sensible return - code. In all other calls it is recommended to check for programming + code. In all other calls, it is recommended to check for programming errors with a more brutal assert(). We are more forgiving to public users then for ourselves! Note that assert() and assert_return() really only should be used for detecting programming errors, not for @@ -153,16 +153,16 @@ on their own, "non-logging" function never log on their own and expect their callers to log. All functions in "library" code, i.e. in src/shared/ and suchlike must be "non-logging". Everytime a - "logging" function calls a "non-logging" function it should log + "logging" function calls a "non-logging" function, it should log about the resulting errors. If a "logging" function calls another "logging" function, then it should not generate log messages, so that log messages are not generated twice for the same errors. - Avoid static variables, except for caches and very few other cases. Think about thread-safety! While most of our code is never - used in threaded environments at least the library code should make + used in threaded environments, at least the library code should make sure it works correctly in them. Instead of doing a lot of locking - for that we tend to prefer using TLS to do per-thread caching (which + for that, we tend to prefer using TLS to do per-thread caching (which only works for small, fixed-size cache objects), or we disable caching for any thread that is not the main thread. Use is_main_thread() to detect whether the calling thread is the main diff --git a/NEWS b/NEWS index 318f3d492..835611c50 100644 --- a/NEWS +++ b/NEWS @@ -1,7 +1,7 @@ systemd System and Service Manager CHANGES WITH 215: - * A new system group "input" is introduced, all input + * A new system group "input" is introduced, and all input device nodes get this group assigned. This is useful for system-level software to get access to input devices. It complements what is already done for "audio" and "video". @@ -18,7 +18,7 @@ CHANGES WITH 214: was opened for writing, the close will trigger a partition table rescan in udev's "watch" facility, and if needed synthesize "change" events for the disk and all its partitions. - This is now unconditionally enabled, if it turns out to + This is now unconditionally enabled, and if it turns out to cause major problems, we might turn it on only for specific devices, or might need to disable it entirely. Device-mapper devices are excluded from this logic. @@ -30,7 +30,7 @@ CHANGES WITH 214: change has been released. * The dependency on libattr has been removed. Since a long - time the extended attribute calls have moved to glibc, and + time, the extended attribute calls have moved to glibc, and libattr is thus unnecessary. * Virtualization detection works without priviliges now. This @@ -55,17 +55,17 @@ CHANGES WITH 214: * systemd-networkd will no longer automatically attempt to manually load kernel modules necessary for certain tunnel - transports. Instead it is assumed the kernel loads them + transports. Instead, it is assumed the kernel loads them automatically when required. This only works correctly on very new kernels. On older kernels, please consider adding the kernel modules to /etc/modules-load.d/ as a work-around. * The resolv.conf file systemd-resolved generates has been - moved to /run/systemd/resolve/, if you have a symlink from - /etc/resolv.conf it might be necessary to correct it. + moved to /run/systemd/resolve/. If you have a symlink from + /etc/resolv.conf, it might be necessary to correct it. - * Two new service settings ProtectedHome= and ProtectedSystem= - have been added. When enabled they will make the user data + * Two new service settings, ProtectedHome= and ProtectedSystem=, + have been added. When enabled, they will make the user data (such as /home) inaccessible or read-only and the system (such as /usr) read-only, for specific services. This allows very light-weight per-service sandboxing to avoid @@ -77,7 +77,7 @@ CHANGES WITH 214: settings to set the owner user and group of AF_UNIX sockets and FIFOs in the file system. - * Socket units gained a new RemoveOnStop= setting. If enabled + * Socket units gained a new RemoveOnStop= setting. If enabled, all FIFOS and sockets in the file system will be removed when the specific socket unit is stopped. @@ -110,7 +110,7 @@ CHANGES WITH 214: vanished. * A new "on-abnormal" setting for Restart= has been added. If - set it will result in automatic restarts on all "abnormal" + set, it will result in automatic restarts on all "abnormal" reasons for a process to exit, which includes unclean signals, core dumps, timeouts and watchdog timeouts, but does not include clean and unclean exit codes or clean @@ -151,19 +151,19 @@ CHANGES WITH 214: files or entire directories. * systemd-tmpfiles "m" lines are now fully equivalent to "z" - lines. So far they have been non-globbing versions of the - latter, and have thus been redundant. In future it is - recommended to only use "z"; and "m" has hence been removed + lines. So far, they have been non-globbing versions of the + latter, and have thus been redundant. In future, it is + recommended to only use "z". "m" has hence been removed from the documentation, even though it stays supported. * A tmpfiles snippet to recreate the most basic structure in /var has been added. This is enough to create the /var/run → /run symlink and create a couple of structural directories. This allows systems to boot up with an empty or - volatile /var. Of course, while with this change the core OS - now is capable with dealing with a volatile /var not all + volatile /var. Of course, while with this change, the core OS + now is capable with dealing with a volatile /var, not all user services are ready for it. However, we hope that sooner - or later many service daemons will be changed upstream so + or later, many service daemons will be changed upstream so that they are able to automatically create their necessary directories in /var at boot, should they be missing. This is the first step to allow state-less systems that only require @@ -177,7 +177,7 @@ CHANGES WITH 214: * Access modes specified in tmpfiles snippets may now be prefixed with "~", which indicates that they shall be masked by whether the existing file or directly is currently - writable, readable or executable at all. Also, if specified + writable, readable or executable at all. Also, if specified, the sgid/suid/sticky bits will be masked for all non-directories. @@ -205,12 +205,12 @@ CHANGES WITH 213: * A new "systemd-timesyncd" daemon has been added for synchronizing the system clock across the network. It implements an SNTP client. In contrast to NTP - implementations such as chrony or the NTP reference server + implementations such as chrony or the NTP reference server, this only implements a client side, and does not bother with the full NTP complexity, focusing only on querying time from one remote server and synchronizing the local clock to it. Unless you intend to serve NTP to networked clients or - want to connect to local hardware clocks this simple NTP + want to connect to local hardware clocks, this simple NTP client should be more than appropriate for most installations. The daemon runs with minimal privileges, and has been hooked up with networkd to only operate when @@ -219,9 +219,9 @@ CHANGES WITH 213: acquired, and uses this to possibly correct the system clock early at bootup, in order to accommodate for systems that lack an RTC such as the Raspberry Pi and embedded devices, - and make sure that time monotonically progresses on these + and to make sure that time monotonically progresses on these systems, even if it is not always correct. To make use of - this daemon a new system user and group "systemd-timesync" + this daemon, a new system user and group "systemd-timesync" needs to be created on installation of systemd. * The queue "seqnum" interface of libudev has been disabled, as @@ -241,7 +241,7 @@ CHANGES WITH 213: * A new FailureAction= setting has been added for service units which may be used to specify an operation to trigger when a service fails. This works similarly to - StartLimitAction=, but unlike it controls what is done + StartLimitAction=, but unlike it, controls what is done immediately rather than only after several attempts to restart the service in question. @@ -307,7 +307,7 @@ CHANGES WITH 213: * hostnamed has been changed to prefer the statically configured hostname in /etc/hostname (unless set to 'localhost' or empty) over any dynamic one supplied by - dhcp. With this change the rules for picking the hostname + dhcp. With this change, the rules for picking the hostname match more closely the rules of other configuration settings where the local administrator's configuration in /etc always overrides any other settings. diff --git a/README b/README index 3cf3bf425..b5545621c 100644 --- a/README +++ b/README @@ -188,16 +188,16 @@ USERS AND GROUPS: exist. During execution this network facing service will drop privileges and assume this uid/gid for security reasons. - Similar, the NTP daemon requires the "systemd-timesync" system + Similarly, the NTP daemon requires the "systemd-timesync" system user and group to exist. - Similar, the network management daemon requires the + Similarly, the network management daemon requires the "systemd-network" system user and group to exist. - Similar, the name resolution daemon requires the + Similarly, the name resolution daemon requires the "systemd-resolve" system user and group to exist. - Similar, the kdbus dbus1 proxy daemon requires the + Similarly, the kdbus dbus1 proxy daemon requires the "systemd-bus-proxy" system user and group to exist. WARNINGS: diff --git a/man/coredump.conf.xml b/man/coredump.conf.xml index c87cf68bc..fa55eb9d2 100644 --- a/man/coredump.conf.xml +++ b/man/coredump.conf.xml @@ -72,7 +72,7 @@ Controls where to store cores. One of none, external, journal, and both. When - none the coredumps will be logged but not + none, the coredumps will be logged but not stored permanently. When external (the default), cores will be stored in /var/lib/systemd/coredump. When journal, cores will be stored in diff --git a/man/coredumpctl.xml b/man/coredumpctl.xml index 5ea865eaa..73d1b8435 100644 --- a/man/coredumpctl.xml +++ b/man/coredumpctl.xml @@ -120,7 +120,7 @@ List coredumps captured in the journal matching specified characteristics. If no - command is specified this is the + command is specified, this is the implied default. diff --git a/man/hostnamectl.xml b/man/hostnamectl.xml index a11f2215d..71973fde9 100644 --- a/man/hostnamectl.xml +++ b/man/hostnamectl.xml @@ -71,7 +71,7 @@ (e.g. "lennarts-laptop"), and the transient hostname which is a default received from network configuration. If a static hostname is set, and is valid (something other - than localhost) then the transient hostname is not used. + than localhost), then the transient hostname is not used. Note that the pretty hostname has little restrictions on the characters used, while the static diff --git a/man/os-release.xml b/man/os-release.xml index 11443638e..4e02f800b 100644 --- a/man/os-release.xml +++ b/man/os-release.xml @@ -90,7 +90,7 @@ files at the same time. /usr/lib/os-release is the recommended place to store OS release information as - part of vendor trees. Frequently + part of vendor trees. Frequently, /etc/os-release is simply a symlink to /usr/lib/os-release, to provide compatibility with applications only diff --git a/man/systemctl.xml b/man/systemctl.xml index 598d31323..a1f170e43 100644 --- a/man/systemctl.xml +++ b/man/systemctl.xml @@ -484,9 +484,9 @@ along with systemd; If not, see . Takes one of full (the default), enable-only, - disable-only. When use with the + disable-only. When used with the preset or preset-all - commands controls whether units shall be disabled and + commands, controls whether units shall be disabled and enabled according to the preset rules, or only enabled, or only disabled. diff --git a/man/systemd-debug-generator.xml b/man/systemd-debug-generator.xml index a64edeffd..ce4750e53 100644 --- a/man/systemd-debug-generator.xml +++ b/man/systemd-debug-generator.xml @@ -57,7 +57,7 @@ understands three options: If the option is - specified and followed by a unit name this unit is + specified and followed by a unit name, this unit is masked for the runtime, similar to the effect of systemctl1's mask command. This is useful to @@ -66,13 +66,13 @@ specified more than once. If the option is - specified and followed by a unit name a start job for + specified and followed by a unit name, a start job for this unit is added to the initial transaction. This is useful to start one ore more additional units at boot. May be specified more than once. If the - option is specified the debug shell service + option is specified, the debug shell service debug-shell.service is pulled into the boot transaction. It will spawn a debug shell on tty9 during early system startup. Note that the shell diff --git a/man/systemd.exec.xml b/man/systemd.exec.xml index c419424d9..cc5442d45 100644 --- a/man/systemd.exec.xml +++ b/man/systemd.exec.xml @@ -941,8 +941,8 @@ mounts the /usr directory read-only for processes invoked by this unit. If set to - full the - /etc is mounted + full, the + /etc directory is mounted read-only, too. This setting ensures that any modification of the vendor supplied operating system (and @@ -952,7 +952,7 @@ all long-running services, unless they are involved with system updates or need to modify the operating system in - other ways. Note however, that + other ways. Note however that processes retaining the CAP_SYS_ADMIN capability can undo the effect of this setting. This setting is hence @@ -974,7 +974,7 @@ /run/user are made inaccessible and empty for processes invoked by this unit. If set - to read-only the + to read-only, the two directores are made read-only instead. It is recommended to enable this setting for all long-running @@ -982,7 +982,7 @@ ones), to ensure they cannot get access to private user data, unless the services actually require access to - the user's private data. Note however, + the user's private data. Note however that processes retaining the CAP_SYS_ADMIN capability can undo the effect of this setting. This setting diff --git a/man/systemd.mount.xml b/man/systemd.mount.xml index 2fbad3728..126b75cb1 100644 --- a/man/systemd.mount.xml +++ b/man/systemd.mount.xml @@ -254,7 +254,7 @@ SloppyOptions= Takes a boolean - argument. If true parsing of the + argument. If true, parsing of the options specified in Options= is relaxed, and unknown mount options are diff --git a/man/systemd.network.xml b/man/systemd.network.xml index 8b2dd2f1d..21f6d50cc 100644 --- a/man/systemd.network.xml +++ b/man/systemd.network.xml @@ -224,7 +224,7 @@ If the specified address is 0.0.0.0 (for IPv4) or [::] - (for IPv6) a new + (for IPv6), a new address range of the requested size is automatically diff --git a/man/systemd.service.xml b/man/systemd.service.xml index 640318ba4..1d8048077 100644 --- a/man/systemd.service.xml +++ b/man/systemd.service.xml @@ -839,7 +839,7 @@ ExecStart=/bin/echo $ONE $TWO ${TWO} recovery from errors. For services that shall be able to terminate on their own choice (and avoiding - immediate restart) + immediate restart), is an alternative choice. diff --git a/man/systemd.socket.xml b/man/systemd.socket.xml index b3607a8b6..aeeb97fcc 100644 --- a/man/systemd.socket.xml +++ b/man/systemd.socket.xml @@ -376,7 +376,7 @@ SocketGroup= Takes a UNIX - user/group name. When specified + user/group name. When specified, all AF_UNIX sockets and FIFO nodes in the file system are owned by the specified user and group. If unset @@ -751,14 +751,14 @@ RemoveOnStop= Takes a boolean - argument. If enabled any file nodes + argument. If enabled, any file nodes created by this socket unit are removed when it is stopped. This applies to AF_UNIX sockets in the file - system, POSIX message queues as well - as FIFOs, as well as any symlinks to + system, POSIX message queues, FIFOs, + as well as any symlinks to them configured with - Symlinks=. Normally + Symlinks=. Normally, it should not be necessary to use this option, and is not recommended as services might continue to run after @@ -775,7 +775,7 @@ system paths. The specified paths will be created as symlinks to the AF_UNIX socket path or FIFO path of this - socket unit. If this setting is used + socket unit. If this setting is used, only one AF_UNIX socket in the file system or one FIFO may be configured for the socket unit. Use this option diff --git a/man/systemd.special.xml b/man/systemd.special.xml index 2ff64c9cb..f590b3fa1 100644 --- a/man/systemd.special.xml +++ b/man/systemd.special.xml @@ -853,7 +853,7 @@ target has been reached. Since the shutdown order is implicitly the reverse - start-up order between units + start-up order between units, this target is particularly useful to ensure that a service is shut down only diff --git a/man/systemd.unit.xml b/man/systemd.unit.xml index 61be6d224..032879a0a 100644 --- a/man/systemd.unit.xml +++ b/man/systemd.unit.xml @@ -1290,7 +1290,7 @@ DefaultInstance= - In template unit files + In template unit files, this specifies for which instance the unit shall be enabled if the template is enabled without any explicitly set diff --git a/man/tmpfiles.d.xml b/man/tmpfiles.d.xml index 5e0b53834..65716c305 100644 --- a/man/tmpfiles.d.xml +++ b/man/tmpfiles.d.xml @@ -112,7 +112,7 @@ all other conflicting entries will be logged as errors. When two lines are prefix and suffix of each other, then the prefix is always processed first, the - suffix later. Otherwise the files/directories are + suffix later. Otherwise, the files/directories are processed in the order they are listed. If the administrator wants to disable a @@ -175,7 +175,7 @@ L /tmp/foobar - - - - /dev/null exist yet. If suffixed with + and a file already exists where the - pipe is to be created it will + pipe is to be created, it will be removed and be replaced by the pipe. @@ -188,7 +188,7 @@ L /tmp/foobar - - - - /dev/null yet. If suffixed with + and a file already exists where the - symlink is to be created it + symlink is to be created, it will be removed and be replaced by the symlink. If the argument is omitted, @@ -207,7 +207,7 @@ L /tmp/foobar - - - - /dev/null suffixed with + and a file already exists where the - device node is to be created + device node is to be created, it will be removed and be replaced by the device node. @@ -221,7 +221,7 @@ L /tmp/foobar - - - - /dev/null exist yet. If suffixed with + and a file already exists where the - device node is to be created + device node is to be created, it will be removed and be replaced by the device node. @@ -232,12 +232,12 @@ L /tmp/foobar - - - - /dev/null Recursively copy a file or directory, if the destination files or - directories don't exist + directories do not exist yet. Note that this command will not descend into subdirectories if the destination directory already - exists, instead the entire + exists. Instead, the entire copy operation is skipped. If the argument is omitted, files from the source directory @@ -423,17 +423,17 @@ r! /tmp/.X[0-9]*-lock L lines. Optionally, if prefixed with - ~ the access mode is masked + ~, the access mode is masked based on the already set access bits for existing file or directories: if the existing - file has all executable bits unset then all + file has all executable bits unset, all executable bits are removed from the new - access mode, too. Similar, if all read bits - are removed from the old access mode they will + access mode, too. Similarly, if all read bits + are removed from the old access mode, they will be removed from the new access mode too, and if all write bits are removed, they will be removed from the new access mode too. In - addition the sticky/suid/gid bit is removed unless + addition, the sticky/suid/gid bit is removed unless applied to a directory. This functionality is particularly useful in conjunction with Z. @@ -516,7 +516,7 @@ r! /tmp/.X[0-9]*-lock and w may be used to specify a short string that is written to the file, suffixed by a newline. For - C specifies the source file + C, specifies the source file or directory. Ignored for all other lines. diff --git a/src/core/busname.c b/src/core/busname.c index 275241507..d2c926b47 100644 --- a/src/core/busname.c +++ b/src/core/busname.c @@ -501,7 +501,7 @@ static void busname_enter_making(BusName *n) { goto fail; if (n->policy) { - /* If there's a policy we need to resolve user/group + /* If there is a policy, we need to resolve user/group * names, which we can't do from PID1, hence let's * fork. */ busname_unwatch_control_pid(n); @@ -514,7 +514,7 @@ static void busname_enter_making(BusName *n) { busname_set_state(n, BUSNAME_MAKING); } else { - /* If there's no policy then we can do everything + /* If there is no policy, we can do everything * directly from PID 1, hence do so. */ r = bus_kernel_make_starter(n->starter_fd, n->name, n->activating, n->accept_fd, NULL, n->policy_world);