On Mon, Mar 24, 2014 at 3:50 PM, Lennart Poettering <[email protected]> wrote: > On Tue, 18.03.14 01:13, Jason St. John ([email protected]) 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 _______________________________________________ systemd-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/systemd-devel
