From e4c3ef87cc63e4d2c907b85ca096ee93299a8da3 Mon Sep 17 00:00:00 2001 From: Michal Bloch Date: Tue, 23 Aug 2016 16:05:48 +0200 Subject: [PATCH] Documentation. Change-Id: Ifd945ead493a5999b837756a3fe62de599262ded Signed-off-by: Michal Bloch --- src/libdlog/log.c | 93 ++++++++++++- src/libdlog/log_android.c | 13 ++ src/libdlog/log_kmsg.c | 13 ++ src/libdlog/log_pipe.c | 25 ++++ src/logctrl/logctrl.c | 6 + src/logger/logger_pipe.c | 274 ++++++++++++++++++++++++++++++++++++-- src/loginit/loginit.c | 12 ++ src/logutil/logutil_kmsg_logger.c | 85 ++++++++++-- src/logutil/logutil_pipe.c | 48 +++++++ src/shared/dlog_ioctl.c | 41 ++++++ src/shared/log_file.c | 11 ++ src/shared/logcommon.c | 28 +++- src/shared/logconfig.c | 114 +++++++++++++++- src/shared/logprint.c | 150 +++++++++++++++------ src/shared/queued_entry.c | 63 +++++++++ 15 files changed, 904 insertions(+), 72 deletions(-) diff --git a/src/libdlog/log.c b/src/libdlog/log.c index a44cf30..be3dc2b 100755 --- a/src/libdlog/log.c +++ b/src/libdlog/log.c @@ -27,15 +27,15 @@ #include #endif -/* +/** * @brief Points to a function which writes a log message * @details The function pointed to depends on the backend used - * @param log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive - * @param prio Priority of the message. - * @param tag The message tag, identifies the sender. - * @param msg The contents of the message. - * @retval Returns the number of bytes written on success and a negative error value on error. - * @seealso __dlog_init_backend + * @param[in] log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive + * @param[in] prio Priority of the message. + * @param[in] tag The message tag, identifies the sender. + * @param[in] msg The contents of the message. + * @return Returns the number of bytes written on success and a negative error value on error. + * @see __dlog_init_backend */ int (*write_to_log)(log_id_t log_id, log_priority prio, const char *tag, const char *msg); pthread_mutex_t log_init_lock = PTHREAD_MUTEX_INITIALIZER; @@ -44,11 +44,27 @@ extern void __dlog_init_backend(); static int limiter; static int plog; +/** + * @brief Null handler + * @description Ignores a log + * @param[in] log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive + * @param[in] prio Priority of the message. + * @param[in] tag The message tag, identifies the sender. + * @param[in] msg The contents of the message. + * @return DLOG_ERROR_NOT_PERMITTED + */ static int __write_to_log_null(log_id_t log_id, log_priority prio, const char *tag, const char *msg) { return DLOG_ERROR_NOT_PERMITTED; } +/** + * @brief Limiter rule from config + * @details Adds a limiter rule from a config entry, if one exists inside + * @param[in] key The entry key + * @param[in] value The entry value + * @return 0 on success, else 1 + */ static int __config_iteration(const char* key, const char* value) { const int prefix_len = strlen("limiter|"); @@ -76,6 +92,10 @@ static int __config_iteration(const char* key, const char* value) return 0; } +/** + * @brief Configure the library + * @details Reads relevant config values + */ static void __configure(void) { struct log_config conf; @@ -104,6 +124,10 @@ static void __configure(void) limiter = 0; } +/** + * @brief DLog init + * @details Initializes the library + */ static void __dlog_init(void) { pthread_mutex_lock(&log_init_lock); @@ -113,6 +137,11 @@ static void __dlog_init(void) pthread_mutex_unlock(&log_init_lock); } +/** + * @brief Fatal assertion + * @details Conditionally crash the sucka who sent the log + * @param[in] prio Priority of the log + */ void __dlog_fatal_assert(int prio) { #ifdef FATAL_ON @@ -120,6 +149,16 @@ void __dlog_fatal_assert(int prio) #endif } +/** + * @brief Check log validity + * @details Checks whether the log is valid and eligible for printing + * @param[in] log_id The target buffer ID + * @param[in] tag The log's tag + * @param[in] prio The log's priority + * @return 0 on success, else an error code. + * @retval DLOG_ERROR_INVALID_PARAMETER Invalid parameter + * @retval DLOG_ERROR_NOT_PERMITTED Not permitted + */ static int dlog_should_log(log_id_t log_id, const char* tag, int prio) { int should_log; @@ -154,6 +193,16 @@ static int dlog_should_log(log_id_t log_id, const char* tag, int prio) return DLOG_ERROR_NONE; } +/** + * @brief Print log + * @details Print a log line + * @param[in] log_id The target buffer ID + * @param[in] prio Priority + * @param[in] tag tag + * @param[in] fmt Format (same as printf) + * @param[in] ap Argument list + * @return Bytes written, or negative error + */ int __dlog_vprint(log_id_t log_id, int prio, const char *tag, const char *fmt, va_list ap) { int ret; @@ -175,6 +224,15 @@ int __dlog_vprint(log_id_t log_id, int prio, const char *tag, const char *fmt, v return ret; } +/** + * @brief Print log + * @details Print a log line + * @param[in] log_id The target buffer ID + * @param[in] prio Priority + * @param[in] tag tag + * @param[in] fmt Format (same as printf) + * @return Bytes written, or negative error + */ int __dlog_print(log_id_t log_id, int prio, const char *tag, const char *fmt, ...) { int ret; @@ -200,6 +258,15 @@ int __dlog_print(log_id_t log_id, int prio, const char *tag, const char *fmt, .. return ret; } +/** + * @brief Print log + * @details Print a log line + * @param[in] prio Priority + * @param[in] tag tag + * @param[in] fmt Format (same as printf) + * @param[in] ap Argument list + * @return Bytes written, or negative error + */ int dlog_vprint(log_priority prio, const char *tag, const char *fmt, va_list ap) { char buf[LOG_MAX_SIZE]; @@ -212,6 +279,14 @@ int dlog_vprint(log_priority prio, const char *tag, const char *fmt, va_list ap) return write_to_log(LOG_ID_APPS, prio, tag, buf); } +/** + * @brief Print log + * @details Print a log line + * @param[in] prio Priority + * @param[in] tag tag + * @param[in] fmt Format (same as printf) + * @return Bytes written, or negative error + */ int dlog_print(log_priority prio, const char *tag, const char *fmt, ...) { va_list ap; @@ -227,6 +302,10 @@ int dlog_print(log_priority prio, const char *tag, const char *fmt, ...) return write_to_log(LOG_ID_APPS, prio, tag, buf); } +/** + * @brief Finalize DLog + * @details Finalizes and deallocates the library + */ void __attribute__((destructor)) __dlog_fini(void) { __log_limiter_destroy(); diff --git a/src/libdlog/log_android.c b/src/libdlog/log_android.c index 39d14f5..6791962 100644 --- a/src/libdlog/log_android.c +++ b/src/libdlog/log_android.c @@ -9,6 +9,15 @@ extern int (*write_to_log)(log_id_t, log_priority, const char *tag, const char * static int log_fds[(int)LOG_ID_MAX] = { -1, -1, -1, -1, -1 }; +/** + * @brief Write to log + * @description Writes a log + * @param[in] log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive + * @param[in] prio Priority of the message. + * @param[in] tag The message tag, identifies the sender. + * @param[in] msg The contents of the message. + * @return Number of bytes written, or negative errno + */ static int __write_to_log_android(log_id_t log_id, log_priority prio, const char *tag, const char *msg) { ssize_t ret; @@ -43,6 +52,10 @@ static int __write_to_log_android(log_id_t log_id, log_priority prio, const char return ret; } +/** + * @brief Initialize the backend + * @description Prepares the backend for proper and fruitful work + */ void __dlog_init_backend() { struct log_config conf; diff --git a/src/libdlog/log_kmsg.c b/src/libdlog/log_kmsg.c index 6568c7e..bbf4f9c 100644 --- a/src/libdlog/log_kmsg.c +++ b/src/libdlog/log_kmsg.c @@ -9,6 +9,15 @@ extern int (*write_to_log)(log_id_t, log_priority, const char *tag, const char * static int log_fds[(int)LOG_ID_MAX] = { -1, -1, -1, -1, -1 }; +/** + * @brief Write to log + * @description Writes a log + * @param[in] log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive + * @param[in] prio Priority of the message. + * @param[in] tag The message tag, identifies the sender. + * @param[in] msg The contents of the message. + * @return Number of bytes written, or negative errno + */ static int __write_to_log_kmsg(log_id_t log_id, log_priority prio, const char *tag, const char *msg) { ssize_t ret; @@ -51,6 +60,10 @@ static int __write_to_log_kmsg(log_id_t log_id, log_priority prio, const char *t return ret; } +/** + * @brief Initialize the backend + * @description Prepares the backend for proper and fruitful work + */ void __dlog_init_backend() { struct log_config conf; diff --git a/src/libdlog/log_pipe.c b/src/libdlog/log_pipe.c index 859f510..5420867 100644 --- a/src/libdlog/log_pipe.c +++ b/src/libdlog/log_pipe.c @@ -35,6 +35,12 @@ extern pthread_mutex_t log_init_lock; static int pipe_fd[LOG_ID_MAX]; static char log_pipe_path[LOG_ID_MAX][PATH_MAX]; +/** + * @brief Connect to a pipe + * @details Connects to a socket whence it retrieves a pipe fd + * @param[in] path Path to the logger daemon write socket from which to retrieve the pipe + * @return Pipe file descriptor, or negative errno on failure + */ static int connect_pipe(const char * path) { int r; @@ -63,6 +69,12 @@ static int connect_pipe(const char * path) return fd; } +/** + * @brief Reconnect pipe + * @details Gets another pipe for a buffer + * @param[in] log_id The buffer whose pipe to replace + * @return Boolean whether pipe successfully reconnected + */ static int __reconnect_pipe(log_id_t log_id) { pthread_mutex_lock(&log_init_lock); @@ -74,6 +86,15 @@ static int __reconnect_pipe(log_id_t log_id) return (pipe_fd[log_id] >= 0); } +/** + * @brief Write to log + * @description Writes a log + * @param[in] log_id ID of the buffer to log to. Belongs to (LOG_ID_INVALID, LOG_ID_MAX) non-inclusive + * @param[in] prio Priority of the message. + * @param[in] tag The message tag, identifies the sender. + * @param[in] msg The contents of the message. + * @return Number of bytes written, or negative errno + */ static int __write_to_log_pipe(log_id_t log_id, log_priority prio, const char *tag, const char *msg) { ssize_t ret; @@ -126,6 +147,10 @@ static int __write_to_log_pipe(log_id_t log_id, log_priority prio, const char *t return ret; } +/** + * @brief Initialize the backend + * @description Prepares the backend for proper and fruitful work + */ void __dlog_init_backend() { const char * conf_val; diff --git a/src/logctrl/logctrl.c b/src/logctrl/logctrl.c index b59fa3a..eb79118 100644 --- a/src/logctrl/logctrl.c +++ b/src/logctrl/logctrl.c @@ -15,6 +15,12 @@ struct options { int should_clear; }; +/** + * @brief Validate options + * @details Checks whether options are valid + * @param[in] o Options to validate + * @return Validity of options: 1 if valid, 0 if invalid + */ int validate(struct options o) { int valid = 1; diff --git a/src/logger/logger_pipe.c b/src/logger/logger_pipe.c index d63898a..dea3922 100644 --- a/src/logger/logger_pipe.c +++ b/src/logger/logger_pipe.c @@ -181,6 +181,12 @@ struct file_buffer { static struct file_buffer g_file_buffer; +/** + * @brief Parse permissions + * @details Parse a string representation of permissions to the internal integral one + * @param[in] str The string representation + * @return The integer representation + */ static int parse_permissions(const char * str) { int ret, parsed; @@ -215,6 +221,14 @@ static int parse_permissions(const char * str) return ret; } +/** + * @brief Change file owners + * @detail Changes user and group ownership of a file + * @param[in] file Filename of the file to change + * @param[in] user The new user (NULL to keep intact) + * @param[in] group The new group (NULL to keep intact) + * @return 1 on success, else 0 + */ static int change_owners(const char * file, const char * user, const char * group) { char buffer[2048]; @@ -232,6 +246,11 @@ static int change_owners(const char * file, const char * user, const char * grou return !chown(file, uid, gid); // ideally would be fchown, but that is broken } +/** + * @brief Reset privileges + * @details Resets privileges to log,log + * @return 1 on success, else 0 + */ static int reset_self_privileges() { uid_t uid = -1; @@ -254,6 +273,13 @@ static int reset_self_privileges() return 1; } +/** + * @brief Create a socket + * @details Creates a socket with given permissions under the given path + * @param[in] path The path to the socket + * @param[in] permissions File permissions (the internal representation) + * @return The socket FD, or negative errno + */ static int listen_fd_create(const char* path, int permissions) { struct sockaddr_un server_addr; @@ -285,16 +311,37 @@ failure: return -errno; } +/** + * @brief Add FD to epoll + * @details Adds given FD to given epoll + * @param[in] epollfd epoll file descriptor to add the other FD to + * @param[in] fd The file descriptor to add to the epoll + * @return 0 on success, nonzero on failure + */ static int add_fd_loop(int epollfd, int fd, struct epoll_event* event) { return epoll_ctl(epollfd, EPOLL_CTL_ADD, fd, event); } +/** + * @brief Remove FD from epoll + * @details Remove given FD from given epoll + * @param[in] epollfd The file descriptor of epoll + * @param[in] fd The FD to remove from epoll + * @return 0 on success, else nonzero + */ static int remove_fd_loop(int epollfd, int fd) { return epoll_ctl(epollfd, EPOLL_CTL_DEL, fd, NULL); } +/** + * @brief Create writer + * @details Allocate a writer structure + * @param[in] fd The FD of the socket the writer initially belongs to + * @param[in] rights Whether the writer is connected to a control socket or not + * @return The newly-allocated writer + */ static struct writer* writer_create(int fd, int rights) { struct writer* w = calloc(1, sizeof(struct writer)); @@ -310,6 +357,11 @@ static struct writer* writer_create(int fd, int rights) return w; } +/** + * @brief Free writer + * @details Deallocate a writer + * @param[in] w The writer to deallocate + */ static void writer_free(struct writer* w) { switch (w->state) { @@ -325,6 +377,13 @@ static void writer_free(struct writer* w) free(w); } +/** + * @brief Create buffer + * @details Allocate a buffer structure + * @param[in] buf_id The ID of the buffer + * @param[in] size The size of the buffer + * @return The newly-allocated buffer + */ static struct log_buffer* buffer_create(int buf_id, int size) { struct log_buffer* lb = calloc(1, sizeof(struct log_buffer) + size); @@ -338,6 +397,11 @@ static struct log_buffer* buffer_create(int buf_id, int size) return lb; } +/** + * @brief Free buffer + * @details Deallocate a buffer + * @param[in] buffer The buffer to deallocate + */ static void buffer_free(struct log_buffer** buffer) { close((*buffer)->listen_fd); @@ -345,6 +409,14 @@ static void buffer_free(struct log_buffer** buffer) *buffer = NULL; } +/** + * @brief Copy from buffer + * @details Copy raw data from buffer to arbitrary location + * @param[in] dst Destination + * @param[in] from How many bytes from the beginning of the buffer the data start + * @param[in] count How much data to copy + * @param[in] b The buffer whence to copy + */ static void copy_from_buffer(void* dst, int from, int count, struct log_buffer* b) { int size = b->size; @@ -355,6 +427,14 @@ static void copy_from_buffer(void* dst, int from, int count, struct log_buffer* memcpy((char*)dst + s1, b->buffer , s2); } +/** + * @brief Copy to buffer + * @details Copy raw data to buffer from arbitrary location + * @param[in] src Source + * @param[in] from How many bytes from the beginning of the buffer the data start + * @param[in] count How much data to copy + * @param[in] b The buffer whither to copy + */ static void copy_to_buffer(const void* src, int from, int count, struct log_buffer* b) { int size = b->size; @@ -365,6 +445,12 @@ static void copy_to_buffer(const void* src, int from, int count, struct log_buff memcpy(b->buffer, (char*)src + s1, s2); } +/** + * @brief Check buffer free space + * @details Check the amount of free space in given buffer + * @param[in] b The buffer to work with + * @return Bytes of free space + */ static int buffer_free_space(struct log_buffer* b) { int head = b->head; @@ -380,6 +466,14 @@ static int buffer_free_space(struct log_buffer* b) return free_space; } +/** + * @brief Append to buffer + * @details Appends an entry to the buffer + * @param[in] s The logger server + * @param[in] entry The entry to append + * @param[in] b The buffer whither to append + * @param[in] reader_head The head of the reader queue of the buffer + */ static void buffer_append(struct logger* s, const struct logger_entry* entry, struct log_buffer* b, struct reader* reader_head) { while (buffer_free_space(b) <= entry->len) { // note that we use <= instead of < to make sure there's always some extra empty space. This guarantees that head != tail, which serves to disambiguate readers living there @@ -402,6 +496,11 @@ static void buffer_append(struct logger* s, const struct logger_entry* entry, st ++b->lines; } +/** + * @brief Add binary file header + * @details Adds the header to a binary file + * @param[in] fd The file FD + */ static void add_misc_file_info(int fd) { const int32_t version = PIPE_FILE_FORMAT_VERSION; @@ -417,6 +516,13 @@ static void add_misc_file_info(int fd) return; } +/** + * @brief Write blob to file + * @details Writes a blob of multiple entries to a file together + * @param[in] reader The reader whose file to write to + * @param[in] buffer The buffer whence data came + * @return Bytes written (-1 on failure) + */ static int write_blob_to_file(struct reader* reader, struct file_buffer* buffer) { int w = 0; @@ -432,6 +538,13 @@ static int write_blob_to_file(struct reader* reader, struct file_buffer* buffer) return 0; } +/** + * @brief Print out logs + * @details Make sure the reader is up to date on printed logs + * @param[in] reader The reader to read the data + * @param[in] buffer The buffer whence to read data + * @return 0 if data remains for the next iteration, 1 if the buffer is to be removed, else -1 + */ static int print_out_logs(struct reader* reader, struct log_buffer* buffer) { int r, ret = 0; @@ -547,6 +660,14 @@ cleanup: return ret; } +/** + * @brief Send a pipe over socket + * @details Sends a pipe over socket + * @param[in] socket The FD of the socket + * @param[in] wr_pipe The pipe to send over the socket + * @param[in] type The type of the pipe (DLOG_FLAG_READ or DLOG_FLAG_WRITE) + * @return 0 on success, else negative error + */ static int send_pipe(int socket, int wr_pipe, int type) { int r; @@ -578,6 +699,12 @@ static int send_pipe(int socket, int wr_pipe, int type) return 0; } +/** + * @brief Writer close FD + * @description Close a writer's connections + * @param[in] server The logger server + * @param[in] wr The writer whose connections to close + */ static void writer_close_fd(struct logger* server, struct writer* wr) { switch (wr->state) { @@ -594,6 +721,11 @@ static void writer_close_fd(struct logger* server, struct writer* wr) } } +/** + * @brief Free a reader + * @details Deallocates a reader + * @param[in] reader The reader to free + */ static void reader_free(struct reader* reader) { if (reader->file.path) @@ -604,6 +736,13 @@ static void reader_free(struct reader* reader) free(reader); } +/** + * @brief Service reader file + * @details Handles readers reading directly from file + * @param[in] server The logger server + * @param[in] reader The reader to service + * @return 0 on success, else an errno value + */ static int service_reader_file(struct logger * server, struct reader* reader) { static char buffer[LOG_MAX_SIZE]; @@ -650,6 +789,13 @@ static int service_reader_file(struct logger * server, struct reader* reader) return ret; } +/** + * @brief Service reader + * @details Passes the reader to a more specific servicing handler + * @param[in] server The logger server + * @param[in] reader The reader being serviced + * @return Positive integer if the reader is to be removed, else a nonpositive one + */ static int service_reader(struct logger* server, struct reader* reader) { switch (reader->type) { @@ -668,6 +814,14 @@ static int service_reader(struct logger* server, struct reader* reader) } } +/** + * @brief Parse a command line + * @details Creates a reader from a parsed command line + * @param[in] cmdl The command line string + * @param[in] server The logger server + * @param[in] wr The writer who sent the line (-1 if internal) + * @return 0 on success, else errno + */ static int parse_command_line(const char* cmdl, struct logger* server, struct writer* wr) { char cmdline[512]; @@ -837,6 +991,13 @@ cleanup: return retval; } +/** + * @brief Change FD flag + * @details Set or clear a file descriptor's flag + * @param[in] fd The FD whose flags to change + * @param[in] flag The flag to change + * @param[in] set Whether to set or to clear + */ static void fd_change_flag(int fd, int flag, int set) { int flags = fcntl(fd, F_GETFL); @@ -849,14 +1010,14 @@ static void fd_change_flag(int fd, int flag, int set) fcntl(fd, F_SETFL, flags); } -/* - The following handlers use the following return value convention: - * = 0 - success, but the reader connection needs to be closed (for example as a part of transition to another state). - * = 1 - success, connection needs to be kept. - * > 1 - failure of this particular request (value is +errno). Reader connection to be kept. - * < 0 - failure of connection (value is -errno). Reader needs to be closed. -*/ - +/** + * @brief Service util request + * @description Handle a request from util + * @param[in] server The logger server + * @param[in] wr The writer who sent the request + * @param[in] msg The message containing the request + * @return 1 on success, else errno + */ static int service_writer_handle_req_util(struct logger* server, struct writer* wr, struct dlog_control_msg* msg) { int r; @@ -879,6 +1040,14 @@ static int service_writer_handle_req_util(struct logger* server, struct writer* return 1; } +/** + * @brief Service clear request + * @description Handle a clear-buffer request + * @param[in] server The logger server + * @param[in] wr The writer who sent the request + * @param[in] msg The message containing the request + * @return 1 on success, else errno + */ static int service_writer_handle_req_clear(struct logger* server, struct writer* wr, struct dlog_control_msg* msg) { struct reader* reader; @@ -905,6 +1074,14 @@ static int service_writer_handle_req_clear(struct logger* server, struct writer* return 1; } +/** + * @brief Service a pipe acquisition request + * @description Handle a pipe request + * @param[in] server The logger server + * @param[in] wr The writer who sent the request + * @param[in] msg The message containing the request + * @return 0 on success, else -errno + */ static int service_writer_handle_req_pipe(struct logger* server, struct writer* wr, struct dlog_control_msg* msg) { int r; @@ -929,6 +1106,14 @@ static int service_writer_handle_req_pipe(struct logger* server, struct writer* return 0; } +/** + * @brief Service a socket request + * @description Handle a socket request + * @param[in] server The logger server + * @param[in] wr The writer who sent the request + * @param[in] event The event containing the request + * @return 0 on success, else -errno + */ static int service_writer_socket(struct logger* server, struct writer* wr, struct epoll_event* event) { int r = 0; @@ -985,6 +1170,14 @@ static int service_writer_socket(struct logger* server, struct writer* wr, struc return (r >= 0 || (r < 0 && errno == EAGAIN)) ? 0 : r; } +/** + * @brief Service pipe log data + * @description Handle log messages incoming through a pipe + * @param[in] server The logger server + * @param[in] wr The writer who sent the logs + * @param[in] event The event associated with the data + * @return 0 on success, else -errno + */ static int service_writer_pipe(struct logger* server, struct writer* wr, struct epoll_event* event) { struct logger_entry* entry; @@ -1015,6 +1208,14 @@ static int service_writer_pipe(struct logger* server, struct writer* wr, struct return 0; } +/** + * @brief Service a writer + * @description Relegates the event to specific handlers + * @param[in] server The logger server + * @param[in] wr The writer who sent the request + * @param[in] event The relevant event + * @return 0 on success, else errno + */ static int service_writer(struct logger* server, struct writer* wr, struct epoll_event* event) { @@ -1028,6 +1229,12 @@ static int service_writer(struct logger* server, struct writer* wr, struct epoll return 0; } +/** + * @brief Service all readers + * @details Update all readers with latest data + * @param[in] server The logger server + * @param[in] force_push Whether to force logs to be pushed to the readers + */ static void service_all_readers(struct logger* server, int force_push) { int i = 0; @@ -1060,6 +1267,12 @@ static void service_all_readers(struct logger* server, int force_push) } } +/** + * @brief Create the logger server + * @details Allocate the logger server and its auxiliary structures (buffers etc.) + * @param[in] conf The configuration + * @return The allocated logger server structure + */ static struct logger* logger_create(struct log_config *conf) { struct logger* l = calloc(1, sizeof(struct logger)); @@ -1196,6 +1409,11 @@ err1: return NULL; } +/** + * @brief Free logger + * @details Deallocate the logger and its auxiliary structures + * @param[in] l The logger server + */ static void logger_free(struct logger* l) { int j; @@ -1230,17 +1448,24 @@ static void logger_free(struct logger* l) free(l); } -static int dispatch_event(struct logger* server, struct fd_entity* entity, struct epoll_event* event) +/** + * @brief Dispatch event + * @details Receives and handles an event + * @param[in] server The logger server + * @param[in] entity The entity who received the event + * @param[in] event The received event + */ +static void dispatch_event(struct logger* server, struct fd_entity* entity, struct epoll_event* event) { - int r = 1; switch (entity->type) { - case ENTITY_WRITER: - r = service_writer(server, (struct writer*)entity, event); + case ENTITY_WRITER: { + int r = service_writer(server, (struct writer*)entity, event); if (r) { LIST_REMOVE(server->writers, ((struct writer*)entity), writer); writer_free((struct writer*)entity); } break; + } case ENTITY_CONTROL: { struct control* ctrl = (struct control*) event->data.ptr; int sock_pipe = accept4(ctrl->fd, NULL, NULL, SOCK_NONBLOCK); @@ -1257,9 +1482,14 @@ static int dispatch_event(struct logger* server, struct fd_entity* entity, struc break; } } - return 0; } +/** + * @brief Do logging + * @details The main logging loop + * @param[in] server The logger server + * @return errno + */ static int do_logger(struct logger* server) { int nfds, i; @@ -1289,6 +1519,12 @@ err: return errno; } +/** + * @brief Parse configs + * @details Create and configurate the logger server + * @param[out] server The created server + * @return 0 on success, else errno + */ static int parse_configs(struct logger** server) { struct log_config conf; @@ -1316,6 +1552,10 @@ static int parse_configs(struct logger** server) return 0; } +/** + * @brief Print help + * @details Prints basic usage tips + */ static void help() { printf("Usage: %s [options]\n" @@ -1326,6 +1566,14 @@ static void help() ); } +/** + * @brief Parse args + * @details Parses execution parameters of the program + * @param[in] argc Argument count + * @param[in] argv Argument values + * @param[in] server The logger server + * @return 0 on success, else errno + */ static int parse_args(int argc, char ** argv, struct logger * server) { int temp, option; diff --git a/src/loginit/loginit.c b/src/loginit/loginit.c index cd339dd..37594d3 100755 --- a/src/loginit/loginit.c +++ b/src/loginit/loginit.c @@ -38,6 +38,13 @@ int g_minors[LOG_ID_MAX] = {-1, -1, -1, -1, -1}; int g_sizes[LOG_ID_MAX] = {-1, -1, -1, -1, -1}; +/** + * @brief Create KMSG edvices + * @details Spawns the KMSG devices for logging to be possible + * @param[in] fd The /dev/kmsg file descriptor + * @param[in] conf The configuration + * @return 0 on success, nonzero on failure + */ static int create_kmsg_devs(int fd, struct log_config *conf) { int i; @@ -73,6 +80,11 @@ static int create_kmsg_devs(int fd, struct log_config *conf) return 0; } +/** + * @brief Remove KMSG devices + * @details Removes KMSG devices + * @param[in] fd The /dev/kmsg file descriptor + */ static void remove_kmsg_devs(int fd) { int i; diff --git a/src/logutil/logutil_kmsg_logger.c b/src/logutil/logutil_kmsg_logger.c index 5b1a4c2..3fda020 100755 --- a/src/logutil/logutil_kmsg_logger.c +++ b/src/logutil/logutil_kmsg_logger.c @@ -74,6 +74,12 @@ struct log_device_t { static struct log_config conf; +/** + * @brief Process an entry + * @details Processes and prints an entry + * @param[in] dev The device whose log is being printed + * @param[in] buf The entry buffer to print + */ static void processBuffer(struct log_device_t* dev, struct logger_entry *buf) { int bytes_written = 0; @@ -124,6 +130,12 @@ error: return; } +/** + * @brief Choose first device + * @details Choose the device whose logs are the earliest + * @param[in] dev The device chain + * @param[out] firstdev The first device (or NULL if device list empty) + */ static void chooseFirst(struct log_device_t* dev, struct log_device_t** firstdev) { for (*firstdev = NULL; dev != NULL; dev = dev->next) { @@ -134,6 +146,11 @@ static void chooseFirst(struct log_device_t* dev, struct log_device_t** firstdev } } +/** + * @brief Maybe print start + * @details Print a delimiter when starting to log from a different device + * @param[in] dev The device to print from + */ static void maybePrintStart(struct log_device_t* dev) { if (!dev->printed) { @@ -149,6 +166,11 @@ static void maybePrintStart(struct log_device_t* dev) } } +/** + * @brief Skip next entry + * @details Skips next entry from a device queue + * @param[in] dev The device to skip from + */ static void skipNextEntry(struct log_device_t* dev) { maybePrintStart(dev); @@ -156,6 +178,11 @@ static void skipNextEntry(struct log_device_t* dev) free_queued_entry(entry); } +/** + * @brief Print next entry + * @details Prints next entry from a device queue + * @param[in] dev The device to print from + */ static void printNextEntry(struct log_device_t* dev) { maybePrintStart(dev); @@ -163,7 +190,11 @@ static void printNextEntry(struct log_device_t* dev) skipNextEntry(dev); } - +/** + * @brief Read log lines + * @details The main log line reading loop + * @param[in] devices The device chain + */ static void read_log_lines(struct log_device_t* devices) { struct log_device_t* dev; @@ -266,6 +297,10 @@ next: } } +/** + * @brief Setup output + * @details Sets output up + */ static void setup_output() { @@ -283,6 +318,12 @@ static void setup_output() } } +/** + * @brief Set log format + * @details Set log format from a string + * @param[in] formatString A string representation of the format + * @return 0 on success, else -1 + */ static int set_log_format(const char * formatString) { static log_print_format format; @@ -299,9 +340,10 @@ static int set_log_format(const char * formatString) return 0; } -/* - * free one log_device_t and it doesn't take care of chain so it - * may break the chain list +/** + * @brief Free log device + * @details free one log_device_t and it doesn't take care of chain so it may break the chain list + * @param[in] dev The device to free */ static void log_devices_free(struct log_device_t *dev) { @@ -319,8 +361,10 @@ static void log_devices_free(struct log_device_t *dev) } -/* - * free all the nodes after the "dev" and includes itself +/** + * @brief Free device chain + * @details free all the nodes after the "dev" and includes itself + * @param[in] dev The device chain to free */ static void log_devices_chain_free(struct log_device_t *dev) { @@ -338,9 +382,11 @@ static void log_devices_chain_free(struct log_device_t *dev) } -/* - * create a new log_device_t instance but don't care about - * the device node accessable or not +/** + * @brief New log device + * @details Create a new log_device_t instance but don't care about the device node accessable or not + * @param[in] path The path to the device + * @return The allocated device */ static struct log_device_t *log_devices_new(const char *path) { @@ -365,8 +411,12 @@ static struct log_device_t *log_devices_new(const char *path) } -/* - * add a new device to the tail of chain +/** + * @brief Add device to tail + * @details Adds a new device to the tail of chain + * @param[in] devices The device chain + * @param[in] new The device to add to the chain + * @return 0 on success, else -1 */ static int log_devices_add_to_tail(struct log_device_t *devices, struct log_device_t *new) { @@ -384,6 +434,10 @@ static int log_devices_add_to_tail(struct log_device_t *devices, struct log_devi return 0; } +/** + * @brief Set dlog time history + * @details Saves util execution time + */ void set_dlog_time_history(void) { char buf[START_TIME_BUF_SIZE] = {0,}; @@ -405,6 +459,11 @@ void set_dlog_time_history(void) close(fd); } +/** + * @brief Signal handler + * @details Handles signals + * @param[in] sig Signal + */ void dlogutil_signal_handler (int sig) { int dlogutil_pid = getpid(); @@ -414,6 +473,10 @@ void dlogutil_signal_handler (int sig) exit(-1); } +/** + * @brief Get dlog time history + * @details Reads util execution times + */ void get_dlog_time_history() { char buf[START_TIME_BUF_SIZE] = {0,}; diff --git a/src/logutil/logutil_pipe.c b/src/logutil/logutil_pipe.c index 47ca5ae..b208118 100644 --- a/src/logutil/logutil_pipe.c +++ b/src/logutil/logutil_pipe.c @@ -64,6 +64,11 @@ static struct sorting_vector { int last_processed; } logs; +/** + * @brief Push log + * @details Push a log to the sorting container + * @param[in] p Pushee + */ static void push_log(struct logger_entry * p) { int i; @@ -95,6 +100,12 @@ static void push_log(struct logger_entry * p) logs.size = (logs.size + 1) % SORT_BUFFER_SIZE; } +/** + * @brief Connect to socket + * @details Connects to the socket at the given path + * @param[in] path The path to the socket + * @return The FD of the socket connection + */ static int connect_sock(const char * path) { int r; @@ -116,6 +127,11 @@ static int connect_sock(const char * path) return fd; } +/** + * @brief Clear request + * @details Send a CLEAR request to the logger daemon + * @return 0 on success, 1 on failure + */ static int do_clear() { const int size = sizeof(struct dlog_control_msg); @@ -131,6 +147,12 @@ static int do_clear() return 0; } +/** + * @brief Get buffer size + * @details Print the size of the working buffer + * @param[in] conf The configuration + * @return 0 on success, 1 on failure + */ static int do_getsize(struct log_config * conf) { char conf_key[MAX_CONF_KEY_LEN]; @@ -147,6 +169,13 @@ static int do_getsize(struct log_config * conf) return 0; } +/** + * @brief Send a logger request + * @details Send a logging request to the daemon + * @param[in] argc Argument count + * @param[in] argv Argument values + * @preturn 1 on success, 0 on failure + */ static int send_logger_request(int argc, char ** argv) { char logger_request[MAX_LOGGER_REQUEST_LEN]; @@ -173,6 +202,13 @@ static int send_logger_request(int argc, char ** argv) return 1; } +/** + * @brief Process log + * @details Processes a raw log and, if it's old enough, prints it + * @param[in] e The entry to process + * @param[in] now Current time + * @return 1 if the log was old enough, else 0 + */ static int process_log(struct logger_entry *e, const struct timespec *now) { int s = now->tv_sec - e->sec; @@ -192,6 +228,12 @@ static int process_log(struct logger_entry *e, const struct timespec *now) return 0; } +/** + * @brief Handle input + * @details The main loop reading log data + * @param[in] data_fd The FD to read data from + * @param[in] dump How many logs to dump (-1 for infinite, 0 for continuous mode) + */ static void handle_pipe(int pipe_fd, int dump) { char buff[RECEIVE_BUFFER_SIZE]; @@ -284,6 +326,12 @@ static void handle_pipe(int pipe_fd, int dump) } } +/** + * @brief Handle file + * @details Checks validity of a binary file + * @param[in] filename The file name + * @return 0 on invalid file, else 1 + */ int handle_file(char const * filename) { fd_set readfds; diff --git a/src/shared/dlog_ioctl.c b/src/shared/dlog_ioctl.c index 82adb44..13b11d8 100644 --- a/src/shared/dlog_ioctl.c +++ b/src/shared/dlog_ioctl.c @@ -27,6 +27,12 @@ #if DLOG_BACKEND_KMSG +/** + * @brief Clear the buffer + * @details Sends a clear ioctl to given fd + * @param[in] fd File descriptor of the buffer + * @remarks KMSG version + */ void clear_log(int fd) { int ret = ioctl(fd, KMSG_CMD_CLEAR); @@ -36,6 +42,13 @@ void clear_log(int fd) } } +/** + * @brief Get buffer size + * @details Sends a getsize ioctl to given fd and stores the result + * @param[in] fd File descriptor of the buffer + * @param[out] size Pointer to a variable in which to store the size + * @remarks KMSG version + */ void get_log_size(int fd, uint32_t *size) { int ret = ioctl(fd, KMSG_CMD_GET_BUF_SIZE, size); @@ -45,6 +58,13 @@ void get_log_size(int fd, uint32_t *size) } } +/** + * @brief Get max read size + * @details Sends an ioctl to given fd and stores the result + * @param[in] fd File descriptor of the buffer + * @param[out] size Pointer to a variable in which to store the returned value + * @remarks KMSG version + */ void get_log_read_size_max(int fd, uint32_t *size) { int ret = ioctl(fd, KMSG_CMD_GET_READ_SIZE_MAX, size); @@ -56,6 +76,12 @@ void get_log_read_size_max(int fd, uint32_t *size) #else +/** + * @brief Clear the buffer + * @details Sends a clear ioctl to given fd + * @param[in] fd File descriptor of the buffer + * @remarks ANDROID LOGGER version + */ void clear_log(int fd) { int ret = ioctl(fd, LOGGER_FLUSH_LOG); @@ -65,6 +91,13 @@ void clear_log(int fd) } } +/** + * @brief Get buffer size + * @details Sends a getsize ioctl to given fd and stores the result + * @param[in] fd File descriptor of the buffer + * @param[out] size Pointer to a variable in which to store the size + * @remarks ANDROID_LOGGER version + */ void get_log_size(int fd, uint32_t *size) { *size = ioctl(fd, LOGGER_GET_LOG_BUF_SIZE); @@ -74,6 +107,14 @@ void get_log_size(int fd, uint32_t *size) } } + +/** + * @brief Get max read size + * @details This function retrieves the maximum log entry size + * @param[in] fd File descriptor of the buffer + * @param[out] size Pointer to a variable in which to store the returned value + * @remarks ANDROID LOGGER version + */ void get_log_read_size_max(int fd, uint32_t *size) { *size = LOGGER_ENTRY_MAX_LEN; diff --git a/src/shared/log_file.c b/src/shared/log_file.c index a9d8d38..283bcb0 100644 --- a/src/shared/log_file.c +++ b/src/shared/log_file.c @@ -29,6 +29,12 @@ #include #include +/** + * @brief Open a log file + * @details Open a log file into the passed structure. + * @param[in] logfile The file structure to contain the opened file descriptor + * @remarks Creates the file if it does not exist, else appends to it. + */ void open_logfile(struct log_file *file) { file->fd = open(file->path, @@ -42,6 +48,11 @@ void open_logfile(struct log_file *file) } } +/** + * @brief Rotate log files + * @details Opens a new file and moves existing files further back + * @param[in] logfile The file structure to contain the currently opened file + */ void rotate_logs(struct log_file *file) { int i, ret; diff --git a/src/shared/logcommon.c b/src/shared/logcommon.c index d98dd6b..1d0d338 100644 --- a/src/shared/logcommon.c +++ b/src/shared/logcommon.c @@ -39,6 +39,14 @@ static struct { { .id = LOG_ID_KMSG, .name = "kmsg" }, }; +/** + * @brief Get buffer ID by name + * @details Returns the ID of the buffer with the given name + * @param[in] name The name of the buffer whose ID we seek + * @return If such buffer exists, its ID. + * Else, LOG_ID_INVALID. + * @see log_name_by_id + */ log_id_t log_id_by_name(const char *name) { log_id_t i; @@ -50,6 +58,14 @@ log_id_t log_id_by_name(const char *name) return LOG_ID_INVALID; } +/** + * @brief Get buffer name by ID + * @details Returns the name of the buffer with the given ID + * @param[in] id The ID of the buffer whose name we seek + * @return If such buffer exists, its name. + * Else, empty string. + * @see log_id_by_name + */ char * log_name_by_id(log_id_t id) { log_id_t i; @@ -61,7 +77,11 @@ char * log_name_by_id(log_id_t id) return ""; } -/* Sends a message to syslog in case dlog has a critical failure and cannot make its own log */ +/** + * @brief Log crtical failure + * @details Writes the given message to syslog with a critical failure note + * @param[in] message The message to write to syslog + */ void syslog_critical_failure(const char * message) { openlog(NULL, LOG_PERROR | LOG_CONS | LOG_PID | LOG_NDELAY, 0); @@ -69,6 +89,12 @@ void syslog_critical_failure(const char * message) closelog(); } +/** + * @brief Receive a file descriptor from a socket + * @details Receives a message from given socket fd and retrieves another fd from inside + * @param[in] sock_fd The socket's file descriptor + * @return The file descriptor received from the socket, -1 if none. + */ int recv_file_descriptor(int socket) { struct msghdr message; diff --git a/src/shared/logconfig.c b/src/shared/logconfig.c index 9652ad1..ce48611 100644 --- a/src/shared/logconfig.c +++ b/src/shared/logconfig.c @@ -7,6 +7,13 @@ #define TZ_SYS_ETC "/opt/etc" #endif +/** + * @brief Get config path by type + * @details Returns the path to the given type of configfer with the given name + * @param[in] type The type of the config: CONFIG_TYPE_COMMON or CONFIG_TYPE_KMSG + * @return Path to given config type, or NULL if invalid type given. + * @see log_config_read_file + */ const char * get_config_filename(config_type type) { switch (type) { @@ -19,12 +26,23 @@ const char * get_config_filename(config_type type) } } +/** + * @brief A singular config entry list element. + */ struct log_conf_entry { char key[MAX_CONF_KEY_LEN]; char value[MAX_CONF_VAL_LEN]; struct log_conf_entry *next; }; +/** + * @brief Get a config value + * @details Returns a value with the given key from the given config + * @param[in] config The config to work with + * @param[in] key The key of the value entry to get + * @return The value of the entry if such exists, else NULL + * @see log_config_set, log_config_push, log_config_remove + */ const char * log_config_get(struct log_config* c, const char* key) { struct log_conf_entry * e; @@ -42,6 +60,16 @@ const char * log_config_get(struct log_config* c, const char* key) return NULL; } +/** + * @brief Set a config value + * @details Sets the entry with the given key in the given config to the given value + * @param[in] config The config to work with + * @param[in] key The key of the value entry to set + * @param[in] value The value to set + * @remarks The entry must already exist + * @return 0 if the entry does not exist, else 1 + * @see log_config_get, log_config_push, log_config_remove + */ int log_config_set(struct log_config* c, const char* key, const char* value) { struct log_conf_entry * e; @@ -60,6 +88,15 @@ int log_config_set(struct log_config* c, const char* key, const char* value) return 0; } +/** + * @brief Read the config + * @details Read the entire configuration. + * @param[in] config The config to fill + * @remarks The path defaults can be overridden with the DLOG_CONFIG_PATH env var + * @return 1 if anything was read, 0 if everything failed + * @see log_config_free + * @see log_config_write + */ int log_config_read(struct log_config* config) { int ret = 0; @@ -81,6 +118,16 @@ int log_config_read(struct log_config* config) return ret; } +/** + * @brief Read one file to config + * @details Appends one file's contents to a config. + * @remarks Comments are ignored and there is no ordering guarantee + * @param[in] config The config to append to + * @param[in] filename The filename of the config file + * @return 1 on success, 0 on failure + * @see log_config_read + * @see get_config_filename + */ int log_config_read_file(struct log_config* config, const char* filename) { FILE * file; @@ -118,6 +165,13 @@ int log_config_read_file(struct log_config* config, const char* filename) return 1; } +/** + * @brief Free a config + * @details Releases the resources owned by given config + * @remarks Does not deallocate the superstructure itself + * @param[in] config The config whose contents to erase + * @see log_config_read + */ void log_config_free(struct log_config* config) { struct log_conf_entry * current = config->begin, * prev; @@ -129,6 +183,13 @@ void log_config_free(struct log_config* config) } } +/** + * @brief Save the config to a file + * @details Saves the given config under the given filename + * @param[in] config The config whose contents to save + * @see log_config_read + * @return 0 on failure, else 1 + */ int log_config_write(struct log_config* config, char const * filename) { FILE * file; @@ -160,6 +221,12 @@ int log_config_write(struct log_config* config, char const * filename) return 1; } +/** + * @brief Print the config + * @details Print all entries of the config to standard output + * @param[in] config The config whose contents to print + * @see log_config_print_key + */ void log_config_print_out(struct log_config* config) { struct log_conf_entry* e = config->begin; @@ -169,6 +236,15 @@ void log_config_print_out(struct log_config* config) } } +/** + * @brief Print a config entry + * @details Print a specific entry from the config to standard output + * @remarks Prints nothing if no such entry present + * @param[in] config The config to work with + * @param[in] key The key of the entry to print + * @return 1 if entry exists and was printed, else 0 + * @see log_config_print_out + */ int log_config_print_key(struct log_config* config, const char* key) { struct log_conf_entry* e = config->begin; @@ -182,6 +258,15 @@ int log_config_print_key(struct log_config* config, const char* key) return 0; } +/** + * @brief Append a config entry + * @details Create an entry composed of the given key and value and add it to the given config + * @remarks Does not check for duplicates + * @param[in] config The config to work with + * @param[in] key The key of the entry to create + * @param[in] value The value of the new entry + * @see log_config_set, log_config_get, log_config_remove + */ void log_config_push(struct log_config* config, const char* key, const char* value) { struct log_conf_entry* e = calloc(1, sizeof(struct log_conf_entry)); @@ -197,6 +282,15 @@ void log_config_push(struct log_config* config, const char* key, const char* val config->last = e; } +/** + * @brief Remove an entry + * @details Remove the entry under the given key from the given config + * @param[in] config The config to work with + * @param[in] key The key of the entry to create + * @param[in] value The value of the new entry + * @return 1 if the entry existed and was removed, else 0 + * @see log_config_set, log_config_get, log_config_push + */ int log_config_remove(struct log_config* config, const char* key) { struct log_conf_entry* prev; @@ -222,12 +316,28 @@ int log_config_remove(struct log_config* config, const char* key) return 0; } -int log_config_foreach(struct log_config* config, int (*func)(const char* key, const char* value)) +/** + * @brief Config iteration callback + * @param[in] key Key of an entry + * @param[in] value Value of the entry + * @return False if processing done, else true + * @see log_config_foreach + */ +typedef int (*configIter) (const char *key, const char* value); + +/** + * @brief Remove an entry + * @details Remove the entry under the given key from the given config + * @param[in] config The config to work with + * @param[in] iter The iteration function called over each entry + * @return -1 if there are no entries, 0 if any entry returns 0, else the value returned by iter when called on the last entry + */ +int log_config_foreach(struct log_config* config, configIter iter) { int r = -1; struct log_conf_entry* e = config->begin; while (e) { - if (!(r = func(e->key, e->value))) + if (!(r = iter(e->key, e->value))) break; e = e->next; diff --git a/src/shared/logprint.c b/src/shared/logprint.c index a8304dd..8d82dee 100755 --- a/src/shared/logprint.c +++ b/src/shared/logprint.c @@ -39,6 +39,14 @@ struct log_format_t { log_print_format format; }; +/** + * @brief Allocate filter info + * @details Allocates filter info with given parameters + * @param[in] tag The filtering tag + * @param[in] pri The filtering priority + * @return The new structure (or NULL if allocation failed). + * @see filterinfo_free + */ static FilterInfo * filterinfo_new(const char *tag, log_priority pri) { FilterInfo *p_ret; @@ -51,6 +59,12 @@ static FilterInfo * filterinfo_new(const char *tag, log_priority pri) return p_ret; } +/** + * @brief Deallocate filter info + * @details Deallocates the entire filter info structure + * @param[in] p_info The structure to deallocate + * @see filterinfo_new + */ static void filterinfo_free(FilterInfo *p_info) { if (p_info == NULL) @@ -61,9 +75,13 @@ static void filterinfo_free(FilterInfo *p_info) free(p_info); } -/* - * Note: also accepts 0-9 priorities - * returns DLOG_UNKNOWN if the character is unrecognized +/** + * @brief Char to priority + * @details Converts a character priority representation to integer + * @param[in] c The character to convert + * @remarks Accepts both letters and numbers + * @return Integral log priority + * @see filter_pri_to_char */ static log_priority filter_char_to_pri(char c) { @@ -98,7 +116,13 @@ static log_priority filter_char_to_pri(char c) return pri; } - +/** + * @brief Priority to character + * @details Converts an integer representation of priority to character + * @param[in] pri The integer to convert + * @return Character log priority + * @see filter_char_to_pri + */ static char filter_pri_to_char(log_priority pri) { switch (pri) { @@ -123,6 +147,13 @@ static char filter_pri_to_char(log_priority pri) } } +/** + * @brief Tag's priority + * @details Figures out the priority associated with given tag + * @param[in] p_format The log format to work with + * @param[in] tag The tag whose priority to search for + * @return The tag's log priority + */ static log_priority filter_pri_for_tag(log_format *p_format, const char *tag) { FilterInfo *p_curFilter; @@ -138,7 +169,12 @@ static log_priority filter_pri_for_tag(log_format *p_format, const char *tag) return p_format->global_pri; } -/** for debugging */ +/** + * @brief Dump filters + * @details Prints a format's filters + * @remarks For debugging + * param[in] p_format The format to work with + */ void dump_filters(log_format *p_format) { FilterInfo *p_fi; @@ -155,14 +191,24 @@ void dump_filters(log_format *p_format) } /** - * returns 1 if this log line should be printed based on its priority - * and tag, and 0 if it should not + * @brief Filter a line + * @details Passes a line through filters to discover whether it should be logged or not + * @param[in] p_format The format to work with + * @param[in] tag The line's tag + * @param[in] pri The line's priority + * @return True if the line should be printed, else false */ int log_should_print_line(log_format *p_format, const char *tag, log_priority pri) { return pri >= filter_pri_for_tag(p_format, tag); } +/** + * @brief Allocate log format + * @details Allocates a log format structure + * @return The new structure (or NULL if allocation failed). + * @see log_format_free + */ log_format *log_format_new(void) { log_format *p_ret; @@ -177,6 +223,13 @@ log_format *log_format_new(void) return p_ret; } +/** + * @brief Copy a log format + * @details Allocates a copy of the log format + * @param[in] p_format The log format to copy + * @return The new structure (or NULL if allocation failed) + * @see log_format_free + */ log_format *log_format_from_format(log_format *p_format) { log_format *p_ret; @@ -208,6 +261,11 @@ log_format *log_format_from_format(log_format *p_format) return p_ret; } +/** + * @brief Deallocate log format + * @details Deallocates the entire log format structure + * @param[in] p_format The structure to deallocate + */ void log_format_free(log_format *p_format) { FilterInfo *p_info, *p_info_old; @@ -223,13 +281,22 @@ void log_format_free(log_format *p_format) free(p_format); } +/** + * @brief Set print format + * @detail Sets a log format's print format + * @param[in] p_format The log format whose print format to set + * @param[in] format The print format + */ void log_set_print_format(log_format *p_format, log_print_format format) { p_format->format = format; } /** - * Returns FORMAT_OFF on invalid string + * @brief Print format from string + * @details Converts a string to print format + * @param[in] formatString The string representation to convert + * @return The integer print format (on invalid string: FORMAT_OFF) */ log_print_format log_format_from_string(const char * formatString) { @@ -259,12 +326,12 @@ log_print_format log_format_from_string(const char * formatString) } /** - * filterExpression: a single filter expression - * eg "AT:d" - * - * returns 0 on success and -1 on invalid expression - * - * Assumes single threaded execution + * @brief Add a filter rule + * @details Adds a tag/priority filtering rule + * @param[in] p_format The log format to add the filter rule to + * @param[in] filterExpression A filter expression ("tag:prio") + * @return 0 on success, else -1 + * @remarks Assumes single threaded execution */ int log_add_filter_rule(log_format *p_format, const char *filterExpression) @@ -316,14 +383,12 @@ error: } /** - * filterString: a comma/whitespace-separated set of filter expressions - * - * eg "AT:d *:i" - * - * returns 0 on success and -1 on invalid expression - * - * Assumes single threaded execution - * + * @brief Add filter string + * @details Adds multiple tag/priority filtering rule from a string + * @param[in] p_format The log format to add the filter rules to + * @param[in] filterstring A filter string containing multiple filter rules delimited by spaces, tabs or commas + * @return 0 on success, else -1 + * @remarks Assumes single threaded execution */ int log_add_filter_string(log_format *p_format, const char *filterString) @@ -360,14 +425,15 @@ static inline char * strip_end(char *str) } /** - * Splits a wire-format buffer into an LogEntry - * entry allocated by caller. Pointers will point directly into buf - * - * Returns 0 on success and -1 on invalid wire format (entry will be - * in unspecified state) + * @brief Preprocess a log buffer for printing + * @details Converts a log entry into a printable format + * @param[in] entry_raw The raw entry to convert + * @param[out] entry The entry to fill + * @return 0 on success, -1 on failure */ int log_process_log_buffer(struct logger_entry *entry_raw, log_entry *entry) { + //TODO: remove and make log_format_log_line just use raw entry directly int i, start = -1, end = -1; if (entry_raw->len < 3) { @@ -418,11 +484,15 @@ int log_process_log_buffer(struct logger_entry *entry_raw, log_entry *entry) } /** - * Formats a log message into a buffer - * - * Uses defaultBuffer if it can, otherwise malloc()'s a new buffer - * If return value != defaultBuffer, caller must call free() - * Returns NULL on malloc error + * @brief Format log line + * @details Formats a log entry for direct printing + * @param[in] p_format The log format to use + * @param[out] defaultBuffer The buffer to write into, if possible + * @param[in] defaultBufferSize The size of the default buffer + * @param[in] entry The entry to format + * @param[out] p_outLength The length of the output + * @return The resulting buffer (defaultBuffer if possible, else a malloc'd one) + * @remarks If the returned value is not defaultBuffer, it has to be free'd */ char *log_format_log_line( log_format *p_format, @@ -621,11 +691,13 @@ char *log_format_log_line( } /** - * Either print or do not print log line, based on filter - * - * Returns count bytes written + * @brief Print log line + * @details Prints the given log entry to the supplied file descriptor + * @param[in] p_format The format to use + * @param[in] fd The file descriptor to write to + * @param[in] entry The entry to print + * @return Bytes written */ - int log_print_log_line( log_format *p_format, int fd, @@ -665,8 +737,10 @@ done: return ret; } - - +/** + * @brief Filter tests + * @details Runs filter tests + */ void logprint_run_tests() { int err; diff --git a/src/shared/queued_entry.c b/src/shared/queued_entry.c index 386be7c..948e933 100644 --- a/src/shared/queued_entry.c +++ b/src/shared/queued_entry.c @@ -24,6 +24,13 @@ #include #include +/** + * @brief Parse a KMSG dictionary value + * @details Parses one of the extra values a KMSG message can have + * @param[in] buf The string to parse + * @param[out] val The value inside + * @return The first char after the parsed value in the string + */ static char* parse_dict_val(char *buf, char **val) { char *cptr; @@ -40,6 +47,13 @@ static char* parse_dict_val(char *buf, char **val) return cptr; } +/** + * @brief Parse KMSG message + * @details Parses a raw KMSG message into the internal format + * @param[in/out] buffer The buffer which contains the message and will contain the entry afterwards + * @param[in] prime Whether this is the primary /dev/kmsg or an extra numbered device /dev/kmsg## + * @return 1 on success, 0 on failure. + */ int parse_kmsg_message(char * buffer, int prime) { static char buffer_temp[LOG_MAX_SIZE]; @@ -143,6 +157,13 @@ int parse_kmsg_message(char * buffer, int prime) return 1; } +/** + * @brief Allocate an entry + * @details Allocates an entry + * @param[in] for_compatibility Doesn't do anything, for compatibility + * @return The allocated entry + * @see free_queued_entry + */ struct queued_entry_t* new_queued_entry(uint32_t for_compatibility) { struct queued_entry_t* entry = (struct queued_entry_t *)malloc(sizeof(struct queued_entry_t)); @@ -154,12 +175,25 @@ struct queued_entry_t* new_queued_entry(uint32_t for_compatibility) return entry; } +/** + * @brief Deallocate an entry + * @details Deallocates an entry + * @param[in] entry The entry to deallocate + * @see new_queued_entry + */ void free_queued_entry(struct queued_entry_t *entry) { if (entry) free(entry); } +/** + * @brief Compare entries + * @details Compares entries chronologically + * @param[in] a One entry + * @param[in] b The other entry + * @return Integer: 0 when equal, positive when a is greater, negative when b is greater. + */ int cmp(struct queued_entry_t* a, struct queued_entry_t* b) { int n = a->entry.sec - b->entry.sec; @@ -169,6 +203,11 @@ int cmp(struct queued_entry_t* a, struct queued_entry_t* b) return a->entry.nsec - b->entry.nsec; } +/** + * @brief Free queued entry list + * @details Frees a queued entry list + * @param[in] queue The queue entry list (ie. its head) to free + */ void free_queued_entry_list(struct queued_entry_t *queue) { while (queue->next) { @@ -179,6 +218,18 @@ void free_queued_entry_list(struct queued_entry_t *queue) free_queued_entry(queue); } +/** + * @brief Read queued entry + * @details Reads an entry from the device + * @param[in] fd FD of the device + * @param[out] entry The entry to read to + * @param[in] log_read_size_max Max log read size + * @return 0 on success, error code on failure + * @retval RQER_PARSE Parsing failure + * @retval RQER_EINTR Interrupted + * @retval RQER_EAGAIN Try again + * @retval RQER_PIPE KMSG device has wrapped around + */ int read_queued_entry_from_dev(int fd, struct queued_entry_t *entry, uint32_t log_read_size_max) { int ret = read(fd, entry->buf, LOGGER_ENTRY_MAX_LEN); @@ -217,6 +268,12 @@ int read_queued_entry_from_dev(int fd, struct queued_entry_t *entry, uint32_t lo return RQER_SUCCESS; } +/** + * @brief Pop queued entry + * @details Pops queued entry + * @param[in/out] queue The pointer to the list (ie. its head) + * @return The popped entry + */ struct queued_entry_t* pop_queued_entry(struct queued_entry_t** queue) { struct queued_entry_t *entry = *queue; @@ -224,6 +281,12 @@ struct queued_entry_t* pop_queued_entry(struct queued_entry_t** queue) return entry; } +/** + * @brief Enqueue an entry + * @details Adds an entry to the queue + * @param[in/out] queue The queue to enqueue the entry to + * @param[in] entry The entry to enqueue to the queue + */ void enqueue(struct queued_entry_t** queue, struct queued_entry_t* entry) { if (*queue == NULL) -- 2.7.4