From: Jason St. John Date: Tue, 25 Mar 2014 03:14:28 +0000 (-0400) Subject: src/systemd: fix grammar and spelling errors in comments X-Git-Tag: v212~4 X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ianmdlvl/git?p=elogind.git;a=commitdiff_plain;h=10b17992ee59ac1d03d6fc210a976bc2b59f6d75 src/systemd: fix grammar and spelling errors in comments --- diff --git a/src/systemd/_sd-common.h b/src/systemd/_sd-common.h index cc3be9380..896a027eb 100644 --- a/src/systemd/_sd-common.h +++ b/src/systemd/_sd-common.h @@ -22,10 +22,10 @@ along with systemd; If not, see . ***/ -/* 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 c0bd03bcc..6ed0527ae 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 f14efeb28..4fdbf3ab4 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 c539dd800..a4ca23117 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 984527f24..71a83ec52 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 ed8300c9b..bb30f9a45 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 a02be7df4..132e5d2e0 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 1d6554988..9ff377f4e 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