src/systemd: fix grammar and spelling errors in comments

8 files changed, 92 insertions, 95 deletions

diff --git a/src/systemd/_sd-common.h b/src/systemd/_sd-common.h
index cc3be93803..896a027eb5 100644
--- a/src/systemd/_sd-common.h
+++ b/src/systemd/_sd-common.h
@@ -22,10 +22,10 @@
   along with systemd; If not, see <http://www.gnu.org/licenses/>.
 ***/
 
-/* This is a private header, never even think of including this directly! */
+/* This is a private header; never even think of including this directly! */
 
 #if __INCLUDE_LEVEL__ <= 1
-#error "Do not include _sd-common.h directly, it is a private header."
+#error "Do not include _sd-common.h directly; it is a private header."
 #endif
 
 #ifndef _sd_printf_
diff --git a/src/systemd/sd-event.h b/src/systemd/sd-event.h
index c0bd03bccf..6ed0527aef 100644
--- a/src/systemd/sd-event.h
+++ b/src/systemd/sd-event.h
@@ -33,8 +33,8 @@
 /*
   Why is this better than pure epoll?
 
-  - Supports event source priorisation
-  - Scales better with a large number of time events, since it doesn't require one timerfd each
+  - Supports event source prioritization
+  - Scales better with a large number of time events because it does not require one timerfd each
   - Automatically tries to coalesce timer events system-wide
   - Handles signals and child PIDs
 */
@@ -58,7 +58,7 @@ enum {
 };
 
 enum {
-        /* And everything inbetween and outside is good too */
+        /* And everything in-between and outside is good too */
         SD_EVENT_PRIORITY_IMPORTANT = -100,
         SD_EVENT_PRIORITY_NORMAL = 0,
         SD_EVENT_PRIORITY_IDLE = 100
diff --git a/src/systemd/sd-id128.h b/src/systemd/sd-id128.h
index f14efeb28d..4fdbf3ab41 100644
--- a/src/systemd/sd-id128.h
+++ b/src/systemd/sd-id128.h
@@ -29,7 +29,7 @@
 
 _SD_BEGIN_DECLARATIONS;
 
-/* 128 Bit ID APIs. See sd-id128(3) for more information. */
+/* 128-bit ID APIs. See sd-id128(3) for more information. */
 
 typedef union sd_id128 sd_id128_t;
 
diff --git a/src/systemd/sd-login.h b/src/systemd/sd-login.h
index c539dd8005..a4ca231174 100644
--- a/src/systemd/sd-login.h
+++ b/src/systemd/sd-login.h
@@ -34,14 +34,14 @@
  * may return NULL.
  *
  * Free the data the library returns with libc free(). String arrays
- * are NULL terminated and you need to free the array itself in
+ * are NULL terminated, and you need to free the array itself, in
  * addition to the strings contained.
  *
- * We return error codes as negative errno, kernel-style. 0 or
- * positive on success.
+ * We return error codes as negative errno, kernel-style. On success, we
+ * return 0 or positive.
  *
- * These functions access data in /proc, /sys/fs/cgroup and /run. All
- * of these are virtual file systems, hence the accesses are
+ * These functions access data in /proc, /sys/fs/cgroup, and /run. All
+ * of these are virtual file systems; therefore, accesses are
  * relatively cheap.
  *
  * See sd-login(3) for more information.
@@ -56,9 +56,9 @@ _SD_BEGIN_DECLARATIONS;
 int sd_pid_get_session(pid_t pid, char **session);
 
 /* Get UID of the owner of the session of the PID (or in case the
- * process is a 'shared' user process the UID of that user is
+ * process is a 'shared' user process, the UID of that user is
  * returned). This will not return the UID of the process, but rather
- * the UID of the owner of the cgroup the process is in. This will
+ * the UID of the owner of the cgroup that the process is in. This will
  * return an error for system processes. */
 int sd_pid_get_owner_uid(pid_t pid, uid_t *uid);
 
@@ -71,7 +71,7 @@ int sd_pid_get_unit(pid_t pid, char **unit);
  * processes. */
 int sd_pid_get_user_unit(pid_t pid, char **unit);
 
-/* Get machine name from PID, for processes assigned to VM or
+/* Get machine name from PID, for processes assigned to a VM or
  * container. This will return an error for non-machine processes. */
 int sd_pid_get_machine_name(pid_t pid, char **machine);
 
@@ -102,21 +102,21 @@ int sd_peer_get_machine_name(int fd, char **machine);
  * connected AF_UNIX socket */
 int sd_peer_get_slice(int fd, char **slice);
 
-/* Get state from uid. Possible states: offline, lingering, online, active, closing */
+/* Get state from UID. Possible states: offline, lingering, online, active, closing */
 int sd_uid_get_state(uid_t uid, char**state);
 
-/* Return 1 if uid has session on seat. If require_active is true will
+/* Return 1 if UID has session on seat. If require_active is true, this will
  * look for active sessions only. */
 int sd_uid_is_on_seat(uid_t uid, int require_active, const char *seat);
 
-/* Return sessions of user. If require_active is true will look for
- * active sessions only. Returns number of sessions as return
- * value. If sessions is NULL will just return number of sessions. */
+/* Return sessions of user. If require_active is true, this will look for
+ * active sessions only. Returns the number of sessions.
+ * If sessions is NULL, this will just return the number of sessions. */
 int sd_uid_get_sessions(uid_t uid, int require_active, char ***sessions);
 
-/* Return seats of user is on. If require_active is true will look for
- * active seats only.  Returns number of seats. If seats is NULL will
- * just return number of seats.*/
+/* Return seats of user is on. If require_active is true, this will look for
+ * active seats only. Returns the number of seats.
+ * If seats is NULL, this will just return the number of seats.*/
 int sd_uid_get_seats(uid_t uid, int require_active, char ***seats);
 
 /* Return 1 if the session is active. */
@@ -125,12 +125,11 @@ int sd_session_is_active(const char *session);
 /* Return 1 if the session is remote. */
 int sd_session_is_remote(const char *session);
 
-/* Get state from session. Possible states: online, active, closing
- * (This function is a more generic version of
- * sd_session_is_active().) */
+/* Get state from session. Possible states: online, active, closing.
+ * This function is a more generic version of sd_session_is_active(). */
 int sd_session_get_state(const char *session, char **state);
 
-/* Determine user id of session */
+/* Determine user ID of session */
 int sd_session_get_uid(const char *session, uid_t *uid);
 
 /* Determine seat of session */
@@ -163,9 +162,8 @@ int sd_session_get_vt(const char *session, unsigned *vtnr);
 /* Return active session and user of seat */
 int sd_seat_get_active(const char *seat, char **session, uid_t *uid);
 
-/* Return sessions and users on seat. Returns number of sessions as
- * return value. If sessions is NULL returns only the number of
- * sessions. */
+/* Return sessions and users on seat. Returns number of sessions.
+ * If sessions is NULL, this returns only the number of sessions. */
 int sd_seat_get_sessions(const char *seat, char ***sessions, uid_t **uid, unsigned *n_uids);
 
 /* Return whether the seat is multi-session capable */
@@ -181,15 +179,15 @@ int sd_seat_can_graphical(const char *seat);
 int sd_machine_get_class(const char *machine, char **clazz);
 
 /* Get all seats, store in *seats. Returns the number of seats. If
- * seats is NULL only returns number of seats. */
+ * seats is NULL, this only returns the number of seats. */
 int sd_get_seats(char ***seats);
 
 /* Get all sessions, store in *sessions. Returns the number of
- * sessions. If sessions is NULL only returns number of sessions. */
+ * sessions. If sessions is NULL, this only returns the number of sessions. */
 int sd_get_sessions(char ***sessions);
 
 /* Get all logged in users, store in *users. Returns the number of
- * users. If users is NULL only returns the number of users. */
+ * users. If users is NULL, this only returns the number of users. */
 int sd_get_uids(uid_t **users);
 
 /* Get all running virtual machines/containers */
@@ -199,7 +197,7 @@ int sd_get_machine_names(char ***machines);
 typedef struct sd_login_monitor sd_login_monitor;
 
 /* Create a new monitor. Category must be NULL, "seat", "session",
- * "uid", "machine" to get monitor events for the specific category
+ * "uid", or "machine" to get monitor events for the specific category
  * (or all). */
 int sd_login_monitor_new(const char *category, sd_login_monitor** ret);
 
diff --git a/src/systemd/sd-network.h b/src/systemd/sd-network.h
index 984527f240..71a83ec526 100644
--- a/src/systemd/sd-network.h
+++ b/src/systemd/sd-network.h
@@ -37,14 +37,14 @@
  * may return NULL.
  *
  * Free the data the library returns with libc free(). String arrays
- * are NULL terminated and you need to free the array itself in
+ * are NULL terminated, and you need to free the array itself in
  * addition to the strings contained.
  *
- * We return error codes as negative errno, kernel-style. 0 or
- * positive on success.
+ * We return error codes as negative errno, kernel-style. On success, we
+ * return 0 or positive.
  *
- * These functions access data in /run. This is a virtual file systems,
- * hence the accesses is relatively cheap.
+ * These functions access data in /run. This is a virtual file system;
+ * therefore, accesses are relatively cheap.
  *
  * See sd-network(3) for more information.
  */
@@ -57,8 +57,8 @@ int sd_network_get_link_state(unsigned index, char**state);
 /* Get DHCPv4 lease from ifindex. */
 int sd_network_get_dhcp_lease(unsigned index, sd_dhcp_lease **ret);
 
-/* Get all network interfaces indices, store in *indices. Returns the
- * number of indices. If indices is NULL only returns the number of indices. */
+/* Get all network interfaces' indices, and store them in *indices. Returns
+ * the number of indices. If indices is NULL, only returns the number of indices. */
 int sd_network_get_ifindices(unsigned **indices);
 
 /* Monitor object */
diff --git a/src/systemd/sd-readahead.h b/src/systemd/sd-readahead.h
index ed8300c9b3..bb30f9a45e 100644
--- a/src/systemd/sd-readahead.h
+++ b/src/systemd/sd-readahead.h
@@ -32,17 +32,17 @@ extern "C" {
 #endif
 
 /*
-  Reference implementation of a few boot readahead related
+  Reference implementation of a few boot read-ahead-related
   interfaces. These interfaces are trivial to implement. To simplify
-  porting, we provide this reference implementation.  Applications are
+  porting, we provide this reference implementation. Applications are
   welcome to reimplement the algorithms described here if they do not
   want to include these two source files.
 
   You may compile this with -DDISABLE_SYSTEMD to disable systemd
   support. This makes all calls NOPs.
 
-  Since this is drop-in code we don't want any of our symbols to be
-  exported in any case. Hence we declare hidden visibility for all of
+  Because this is drop-in code, we don't want any of our symbols to be
+  exported in any case. Hence, we declare hidden visibility for all of
   them.
 
   You may find an up-to-date version of these source files online:
@@ -50,18 +50,18 @@ extern "C" {
   http://cgit.freedesktop.org/systemd/systemd/plain/src/systemd/sd-readahead.h
   http://cgit.freedesktop.org/systemd/systemd/plain/src/readahead/sd-readahead.c
 
-  This should compile on non-Linux systems, too, but all functions
+  This should compile on non-Linux systems too, but all functions
   will become NOPs.
 
   See sd-readahead(3) for more information.
 */
 
 /*
-  Controls ongoing disk read-ahead operations during boot-up. The argument
-  must be a string, and either "cancel", "done" or "noreplay".
+  Controls on-going disk read-ahead operations during boot-up. The argument
+  must be one of the following strings: "cancel", "done", or "noreplay".
 
-  cancel = terminate read-ahead data collection, drop collected information
-  done = terminate read-ahead data collection, keep collected information
+  cancel = terminate read-ahead data collection, and drop collected information
+  done = terminate read-ahead data collection, and keep collected information
   noreplay = terminate read-ahead replay
 */
 int sd_readahead(const char *action);
diff --git a/src/systemd/sd-resolve.h b/src/systemd/sd-resolve.h
index a02be7df4e..132e5d2e07 100644
--- a/src/systemd/sd-resolve.h
+++ b/src/systemd/sd-resolve.h
@@ -36,11 +36,11 @@ typedef struct sd_resolve sd_resolve;
 /** An opaque sd-resolve query structure */
 typedef struct sd_resolve_query sd_resolve_query;
 
-/** Allocate a new sd-resolve session */
+/** Allocate a new sd-resolve session. */
 int sd_resolve_new(sd_resolve **ret);
 
 /** Free a sd-resolve session. This destroys all attached
- * sd_resolve_query objects automatically */
+ * sd_resolve_query objects automatically. */
 sd_resolve* sd_resolve_unref(sd_resolve *resolve);
 
 /** Return the UNIX file descriptor to poll() for events on. Use this
@@ -51,96 +51,96 @@ int sd_resolve_get_fd(sd_resolve *resolve);
  * POLLOUT, ...) to check for. */
 int sd_resolve_get_events(sd_resolve *resolve);
 
-/** Return the poll() timeout to pass. Returns (uint64_t) -1 as time
- * out if no time out is needed */
+/** Return the poll() timeout to pass. Returns (uint64_t) -1 as
+ * timeout if no timeout is needed. */
 int sd_resolve_get_timeout(sd_resolve *resolve, uint64_t *timeout_usec);
 
-/** Process pending responses. After this function is called you can
+/** Process pending responses. After this function is called, you can
  * get the next completed query object(s) using
  * sd_resolve_get_next(). */
 int sd_resolve_process(sd_resolve *resolve);
 
-/** Wait for a resolve event to complete */
+/** Wait for a resolve event to complete. */
 int sd_resolve_wait(sd_resolve *resolve, uint64_t timeout_usec);
 
-/** Issue a name to address query on the specified session. The
- * arguments are compatible with the ones of libc's
+/** Issue a name-to-address query on the specified session. The
+ * arguments are compatible with those of libc's
  * getaddrinfo(3). The function returns a new query object. When the
- * query is completed you may retrieve the results using
+ * query is completed, you may retrieve the results using
  * sd_resolve_getaddrinfo_done(). */
 int sd_resolve_getaddrinfo(sd_resolve *resolve, sd_resolve_query **q, const char *node, const char *service, const struct addrinfo *hints);
 
 /** Retrieve the results of a preceding sd_resolve_getaddrinfo()
  * call. Returns a addrinfo structure and a return value compatible
- * with libc's getaddrinfo(3). The query object q is destroyed by this
+ * with libc's getaddrinfo(3). The query object, q, is destroyed by this
  * call and may not be used any further. Make sure to free the
  * returned addrinfo structure with sd_resolve_freeaddrinfo() and not
- * libc's freeaddrinfo(3)! If the query is not completed yet EAI_AGAIN
+ * libc's freeaddrinfo(3)! If the query is not completed yet, EAI_AGAIN
  * is returned. */
 int sd_resolve_getaddrinfo_done(sd_resolve_query* q, struct addrinfo **ret_ai);
 
 /** Free the addrinfo structure as returned by
- * sd_resolve_getaddrinfo_done(). Make sure to use this functions instead
- * of the libc's freeaddrinfo()! */
+ * sd_resolve_getaddrinfo_done(). Make sure to use this function instead
+ * of libc's freeaddrinfo()! */
 void sd_resolve_freeaddrinfo(struct addrinfo *ai);
 
-/** Issue an address to name query on the specified session. The
- * arguments are compatible with the ones of libc's
+/** Issue an address-to-name query on the specified session. The
+ * arguments are compatible with those of libc's
  * getnameinfo(3). The function returns a new query object. When the
- * query is completed you may retrieve the results using
+ * query is completed, you may retrieve the results using
  * sd_resolve_getnameinfo_done(). Set gethost (resp. getserv) to non-zero
  * if you want to query the hostname (resp. the service name). */
 int sd_resolve_getnameinfo(sd_resolve *resolve, sd_resolve_query **q, const struct sockaddr *sa, socklen_t salen, int flags, int gethost, int getserv);
 
 /** Retrieve the results of a preceding sd_resolve_getnameinfo()
  * call. Returns the hostname and the service name in ret_host and
- * ret_serv. The query object q is destroyed by this call and may not
- * be used any further. If the query is not completed yet EAI_AGAIN is
+ * ret_serv. The query object, q, is destroyed by this call and may not
+ * be used any further. If the query is not completed yet, EAI_AGAIN is
  * returned. */
 int sd_resolve_getnameinfo_done(sd_resolve_query* q, char **ret_host, char **ret_serv);
 
 /** Issue a resolver query on the specified session. The arguments are
- * compatible with the ones of libc's res_query(3). The function returns a new
- * query object. When the query is completed you may retrieve the results using
- * sd_resolve_res_done().  */
+ * compatible with those of libc's res_query(3). The function returns a new
+ * query object. When the query is completed, you may retrieve the results using
+ * sd_resolve_res_done(). */
 int sd_resolve_res_query(sd_resolve *resolve, sd_resolve_query **q, const char *dname, int clazz, int type);
 
-/** Issue an resolver query on the specified session. The arguments are
- * compatible with the ones of libc's res_search(3). The function returns a new
- * query object. When the query is completed you may retrieve the results using
- * sd_resolve_res_done().  */
+/** Issue a resolver query on the specified session. The arguments are
+ * compatible with those of libc's res_search(3). The function returns a new
+ * query object. When the query is completed, you may retrieve the results using
+ * sd_resolve_res_done(). */
 int sd_resolve_res_search(sd_resolve *resolve, sd_resolve_query **q, const char *dname, int clazz, int type);
 
 /** Retrieve the results of a preceding sd_resolve_res_query() or
- * resolve_res_search call.  The query object q is destroyed by this
+ * resolve_res_search call. The query object, q, is destroyed by this
  * call and may not be used any further. Returns a pointer to the
- * answer of the res_query call. If the query is not completed yet
- * -EAGAIN is returned, on failure -errno is returned, otherwise the
+ * answer of the res_query call. If the query is not completed yet,
+ * -EAGAIN is returned; on failure, -errno is returned; otherwise, the
  * length of answer is returned. */
 int sd_resolve_res_done(sd_resolve_query* q, unsigned char **answer);
 
 /** Return the next completed query object. If no query has been
  * completed yet, return NULL. Please note that you need to run
- * sd_resolve_wait() before this function will return sensible data.  */
+ * sd_resolve_wait() before this function will return sensible data. */
 int sd_resolve_get_next(sd_resolve *resolve, sd_resolve_query **q);
 
 /** Return the number of query objects (completed or not) attached to
- * this session */
+ * this session. */
 int sd_resolve_get_n_queries(sd_resolve *resolve);
 
-/** Cancel a currently running query. q is is destroyed by this call
+/** Cancel a currently running query. q is destroyed by this call
  * and may not be used any further. */
 int sd_resolve_cancel(sd_resolve_query* q);
 
-/** Returns non-zero when the query operation specified by q has been completed */
+/** Returns non-zero when the query operation specified by q has been completed. */
 int sd_resolve_is_done(sd_resolve_query*q);
 
-/** Assign some opaque userdata with a query object */
+/** Assign some opaque userdata with a query object. */
 void* sd_resolve_set_userdata(sd_resolve_query *q, void *userdata);
 
 /** Return userdata assigned to a query object. Use
  * sd_resolve_setuserdata() to set this data. If no data has been set
- * prior to this call it returns NULL. */
+ * prior to this call, it returns NULL. */
 void* sd_resolve_get_userdata(sd_resolve_query *q);
 
 _SD_END_DECLARATIONS;
diff --git a/src/systemd/sd-shutdown.h b/src/systemd/sd-shutdown.h
index 1d65549882..9ff377f4e4 100644
--- a/src/systemd/sd-shutdown.h
+++ b/src/systemd/sd-shutdown.h
@@ -71,46 +71,45 @@ struct sd_shutdown_command {
  * AF_UNIX/SOCK_DGRAM datagram with the structure above suffixed with
  * the wall message to the socket /run/systemd/shutdownd (leave an
  * empty wall message for the default shutdown message). To calculate
- * the size of the message use "offsetof(struct sd_shutdown_command,
+ * the size of the message, use "offsetof(struct sd_shutdown_command,
  * wall_message) + strlen(command.wall_message)".
  *
- * To cancel a shutdown, do the same, but send an fully zeroed out
+ * To cancel a shutdown, do the same, but send a fully zeroed-out
  * structure.
  *
  * To be notified about scheduled shutdowns, create an inotify watch
- * on /run/shutdown/. Whenever a file called "scheduled" appears a
- * shutdown is scheduled. If it is removed it is canceled. It is
- * replaced the scheduled shutdown has been changed. The file contains
- * a simple environment-like block, that contains information about
+ * on /run/shutdown/. Whenever a file called "scheduled" appears, a
+ * shutdown is scheduled. If it is removed, it is canceled. If it is
+ * replaced, the scheduled shutdown has been changed. The file contains
+ * a simple, environment-like block that contains information about
  * the scheduled shutdown:
  *
  * USEC=
  * encodes the time for the shutdown in usecs since the epoch UTC,
- * formatted as numeric string.
+ * formatted as a numeric string.
  *
  * WARN_WALL=
  * is 1 if a wall message shall be sent
  *
  * DRY_RUN=
- * is 1 if a dry run shutdown is scheduled
+ * is 1 if a dry-run shutdown is scheduled
  *
  * MODE=
  * is the shutdown mode, one of "poweroff", "reboot", "halt", "kexec"
  *
  * WALL_MESSAGE=
- * is the wall message to use, with all special characters escape in C style.
+ * is the wall message to use, with all special characters escaped in C-style.
  *
  * Note that some fields might be missing if they do not apply.
  *
  * Note that the file is first written to a temporary file and then
  * renamed, in order to provide atomic properties for readers: if the
- * file exists under the name "scheduled" it is guaranteed to be fully
+ * file exists under the name "scheduled", it is guaranteed to be fully
  * written. A reader should ignore all files in that directory by any
  * other name.
  *
  * Scheduled shutdowns are only accepted from privileged processes,
- * but the directory may be watched and the file in it read by
- * anybody.
+ * but anyone may watch the directory and the file in it.
  */
 
 #ifdef __cplusplus