[systemd-devel] [PATCHv2] src/systemd: fix grammar and spelling errors in comments
Jason St. John
jstjohn at purdue.edu
Mon Mar 24 20:14:28 PDT 2014
---
This is a resubmit that now should apply cleanly on the latest master.
src/systemd/_sd-common.h | 4 +--
src/systemd/sd-event.h | 6 ++--
src/systemd/sd-id128.h | 2 +-
src/systemd/sd-login.h | 52 +++++++++++++++++------------------
src/systemd/sd-network.h | 14 +++++-----
src/systemd/sd-readahead.h | 18 ++++++------
src/systemd/sd-resolve.h | 68 +++++++++++++++++++++++-----------------------
src/systemd/sd-shutdown.h | 23 ++++++++--------
8 files changed, 92 insertions(+), 95 deletions(-)
diff --git a/src/systemd/_sd-common.h b/src/systemd/_sd-common.h
index cc3be93..896a027 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 c0bd03b..6ed0527 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 f14efeb..4fdbf3a 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 c539dd8..a4ca231 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 984527f..71a83ec 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 ed8300c..bb30f9a 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 a02be7d..132e5d2 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 1d65549..9ff377f 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
--
1.9.1
More information about the systemd-devel
mailing list