[systemd-devel] [PATCH] src/systemd: fix grammar and spelling errors in comments
Lennart Poettering
lennart at poettering.net
Mon Mar 24 12:50:35 PDT 2014
On Tue, 18.03.14 01:13, Jason St. John (jstjohn at purdue.edu) wrote:
Doesn't apply anymore, could please rebase?
> ---
> 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 45c3608..67dc249 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 87ebafb..a31dc69 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 **class);
>
> /* 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 3c1d482..dae55c6 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 class, 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 class, 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
Lennart
--
Lennart Poettering, Red Hat
More information about the systemd-devel
mailing list