On Tue, 18.03.14 01:13, Jason St. John ([email protected]) 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 _______________________________________________ systemd-devel mailing list [email protected] http://lists.freedesktop.org/mailman/listinfo/systemd-devel
