From 12e2ddf54f6bfa77f6e65151b04199ac98361c9a Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Tue, 1 Sep 2015 23:10:46 +0200 Subject: improve header file MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- src/bus.c | 9 ++-- src/bus.h | 139 ++++++++++++++++++++++++++++++++++++-------------------------- 2 files changed, 84 insertions(+), 64 deletions(-) diff --git a/src/bus.c b/src/bus.c index 4b6b8d1..c1f1c6f 100644 --- a/src/bus.c +++ b/src/bus.c @@ -540,7 +540,7 @@ absolute_time_to_delta_time(struct timespec *delta, const struct timespec *absol * @return 0 on success, -1 on error */ int -bus_create(const char *file, int flags, char **out_file) +bus_create(const char *restrict file, int flags, char **restrict out_file) { int fd = -1, saved_errno; bus_t bus; @@ -679,7 +679,7 @@ fail: * @return 0 on success, -1 on error */ int -bus_open(bus_t *bus, const char *file, int flags) +bus_open(bus_t *restrict bus, const char *restrict file, int flags) { int saved_errno; char *line = NULL; @@ -830,7 +830,6 @@ fail: release_semaphore(bus, X, SEM_UNDO); errno = saved_errno; return -1; - } @@ -858,7 +857,7 @@ fail: * @return 0 on success, -1 on error */ int -bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data) +bus_read(const bus_t *restrict bus, int (*callback)(const char *message, void *user_data), void *user_data) { int r, state = 0, saved_errno; if (release_semaphore(bus, S, SEM_UNDO) == -1) @@ -924,7 +923,7 @@ done: * it most be a predictable clock * @return 0 on success, -1 on error */ -int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void *user_data), +int bus_read_timed(const bus_t *restrict bus, int (*callback)(const char *message, void *user_data), void *user_data, const struct timespec *timeout, clockid_t clockid) { int r, state = 0, saved_errno; diff --git a/src/bus.h b/src/bus.h index 20c7411..0dd40eb 100644 --- a/src/bus.h +++ b/src/bus.h @@ -33,6 +33,14 @@ +#if defined(__GNUC__) +# define BUS_COMPILER_GCC(X) X +#else +# define BUS_COMPILER_GCC(X) /* ignore */ +#endif + + + /** * Open the bus for reading only */ @@ -122,7 +130,8 @@ typedef struct bus * @param out_file Output parameter for the pathname of the bus * @return 0 on success, -1 on error */ -int bus_create(const char *file, int flags, char **out_file); +int bus_create(const char *restrict, int, char **restrict) + BUS_COMPILER_GCC(__attribute__((warn_unused_result))); /** * Remove a bus @@ -130,7 +139,8 @@ int bus_create(const char *file, int flags, char **out_file); * @param file The pathname of the bus * @return 0 on success, -1 on error */ -int bus_unlink(const char *file); +int bus_unlink(const char *) + BUS_COMPILER_GCC(__attribute__((nonnull))); /** @@ -142,7 +152,8 @@ int bus_unlink(const char *file); * the value must not be negative * @return 0 on success, -1 on error */ -int bus_open(bus_t *bus, const char *file, int flags); +int bus_open(bus_t *restrict, const char *restrict, int) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Close a bus @@ -150,7 +161,8 @@ int bus_open(bus_t *bus, const char *file, int flags); * @param bus Bus information * @return 0 on success, -1 on error */ -int bus_close(bus_t *bus); +int bus_close(bus_t *) + BUS_COMPILER_GCC(__attribute__((nonnull))); /** @@ -164,7 +176,8 @@ int bus_close(bus_t *bus); * procedure * @return 0 on success, -1 on error */ -int bus_write(const bus_t *bus, const char *message, int flags); +int bus_write(const bus_t *, const char *, int) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Broadcast a message on a bus @@ -178,65 +191,67 @@ int bus_write(const bus_t *bus, const char *message, int flags); * it most be a predictable clock * @return 0 on success, -1 on error */ -int bus_write_timed(const bus_t *bus, const char *message, - const struct timespec *timeout, clockid_t clockid); +int bus_write_timed(const bus_t *, const char *, const struct timespec *, clockid_t) + BUS_COMPILER_GCC(__attribute__((nonnull(1, 2), warn_unused_result))); /** * Listen (in a loop, forever) for new message on a bus * - * @param bus Bus information - * @param callback Function to call when a message is received, the - * input parameters will be the read message and - * `user_data` from `bus_read`'s parameter with the - * same name. The message must have been parsed or - * copied when `callback` returns as it may be over - * overridden after that time. `callback` should - * return either of the the values: - * * 0: stop listening - * * 1: continue listening - * * -1: an error has occurred - * However, the function [`bus_read`] will invoke - * `callback` with `message` set to `NULL`one time - * directly after it has started listening on the - * bus. This is to the the program now it can safely - * continue with any action that requires that the - * programs is listening on the bus. - * @param user_data Parameter passed to `callback` - * @return 0 on success, -1 on error + * @param bus Bus information + * @param callback Function to call when a message is received, the + * (message, user_data) input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @return 0 on success, -1 on error */ -int bus_read(const bus_t *bus, int (*callback)(const char *message, void *user_data), void *user_data); +int bus_read(const bus_t *restrict, int (*)(const char *, void *), void *) + BUS_COMPILER_GCC(__attribute__((nonnull(1, 2), warn_unused_result))); /** * Listen (in a loop, forever) for new message on a bus * - * @param bus Bus information - * @param callback Function to call when a message is received, the - * input parameters will be the read message and - * `user_data` from `bus_read`'s parameter with the - * same name. The message must have been parsed or - * copied when `callback` returns as it may be over - * overridden after that time. `callback` should - * return either of the the values: - * * 0: stop listening - * * 1: continue listening - * * -1: an error has occurred - * However, the function [`bus_read`] will invoke - * `callback` with `message` set to `NULL`one time - * directly after it has started listening on the - * bus. This is to the the program now it can safely - * continue with any action that requires that the - * programs is listening on the bus. - * @param user_data Parameter passed to `callback` - * @param timeout The time the operation shall fail with errno set - * to `EAGAIN` if not completed, note that the callback - * function may or may not have been called - * @param clockid The ID of the clock the `timeout` is measured with, - * it most be a predictable clock - * @return 0 on success, -1 on error + * @param bus Bus information + * @param callback Function to call when a message is received, the + * (message, user_data) input parameters will be the read message and + * `user_data` from `bus_read`'s parameter with the + * same name. The message must have been parsed or + * copied when `callback` returns as it may be over + * overridden after that time. `callback` should + * return either of the the values: + * * 0: stop listening + * * 1: continue listening + * * -1: an error has occurred + * However, the function [`bus_read`] will invoke + * `callback` with `message` set to `NULL`one time + * directly after it has started listening on the + * bus. This is to the the program now it can safely + * continue with any action that requires that the + * programs is listening on the bus. + * @param user_data Parameter passed to `callback` + * @param timeout The time the operation shall fail with errno set + * to `EAGAIN` if not completed, note that the callback + * function may or may not have been called + * @param clockid The ID of the clock the `timeout` is measured with, + * it most be a predictable clock + * @return 0 on success, -1 on error */ -int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void *user_data), - void *user_data, const struct timespec *timeout, clockid_t clockid); +int bus_read_timed(const bus_t *restrict, int (*)(const char *, void *), + void *, const struct timespec *, clockid_t) + BUS_COMPILER_GCC(__attribute__((nonnull(1, 2), warn_unused_result))); /** @@ -250,7 +265,8 @@ int bus_read_timed(const bus_t *bus, int (*callback)(const char *message, void * * @param bus Bus information * @return 0 on success, -1 on error */ -int bus_poll_start(bus_t *bus); +int bus_poll_start(bus_t *) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Announce that the thread has stopped listening on the bus. @@ -260,7 +276,8 @@ int bus_poll_start(bus_t *bus); * @param bus Bus information * @return 0 on success, -1 on error */ -int bus_poll_stop(const bus_t *bus); +int bus_poll_stop(const bus_t *) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Wait for a message to be broadcasted on the bus. @@ -275,7 +292,8 @@ int bus_poll_stop(const bus_t *bus); * `EAGAIN` if there isn't already a message available on the bus * @return The received message, `NULL` on error */ -const char *bus_poll(bus_t *bus, int flags); +const char *bus_poll(bus_t *, int) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Wait for a message to be broadcasted on the bus. @@ -292,7 +310,8 @@ const char *bus_poll(bus_t *bus, int flags); * it most be a predictable clock * @return The received message, `NULL` on error */ -const char *bus_poll_timed(bus_t *bus, const struct timespec *timeout, clockid_t clockid); +const char *bus_poll_timed(bus_t *, const struct timespec *, clockid_t) + BUS_COMPILER_GCC(__attribute__((nonnull(1), warn_unused_result))); /** @@ -305,7 +324,8 @@ const char *bus_poll_timed(bus_t *bus, const struct timespec *timeout, clockid_t * @param group The group ID of the bus's new group * @return 0 on success, -1 on error */ -int bus_chown(const char *file, uid_t owner, gid_t group); +int bus_chown(const char *, uid_t, gid_t) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); /** * Change the permissions for a bus @@ -318,7 +338,8 @@ int bus_chown(const char *file, uid_t owner, gid_t group); * edit the bus's associated file * @return 0 on success, -1 on error */ -int bus_chmod(const char *file, mode_t mode); +int bus_chmod(const char *, mode_t) + BUS_COMPILER_GCC(__attribute__((nonnull, warn_unused_result))); -- cgit v1.2.3-70-g09d2