[systemd-devel] [PATCH] src/systemd: fix grammar and spelling errors in comments
Jason St. John
jstjohn at purdue.edu
Mon Mar 24 20:16:45 PDT 2014
On Mon, Mar 24, 2014 at 3:50 PM, Lennart Poettering
<lennart at poettering.net> wrote:
> On Tue, 18.03.14 01:13, Jason St. John (jstjohn at purdue.edu) wrote:
>
> Doesn't apply anymore, could please rebase?
>
Sure. I resubmitted the patch here:
http://lists.freedesktop.org/archives/systemd-devel/2014-March/018190.html
>> ---
>> 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
Jason
More information about the systemd-devel
mailing list