From 1c8d13c8a4111fcfd4cc00c335d47506ab98bb33 Mon Sep 17 00:00:00 2001 From: "Thibault, Daniel" Date: Mon, 30 Jan 2012 15:58:08 -0500 Subject: [PATCH] Document return values Fix one return values that would return an -ENOMEM instead of a -1 on error. Signed-off-by: Daniel U. Thibault Signed-off-by: David Goulet --- src/bin/lttng/commands/calibrate.c | 2 + src/bin/lttng/commands/create.c | 13 +++-- src/lib/lttng-ctl/lttng-ctl.c | 94 ++++++++++++++++++++---------- 3 files changed, 71 insertions(+), 38 deletions(-) diff --git a/src/bin/lttng/commands/calibrate.c b/src/bin/lttng/commands/calibrate.c index a3c7b5241..a60cadfa0 100644 --- a/src/bin/lttng/commands/calibrate.c +++ b/src/bin/lttng/commands/calibrate.c @@ -182,6 +182,8 @@ error: /* * Calibrate LTTng tracer. + * + * Returns a CMD_* error. */ int cmd_calibrate(int argc, const char **argv) { diff --git a/src/bin/lttng/commands/create.c b/src/bin/lttng/commands/create.c index 34754c7ca..9dc375224 100644 --- a/src/bin/lttng/commands/create.c +++ b/src/bin/lttng/commands/create.c @@ -52,17 +52,18 @@ static void usage(FILE *ofp) { fprintf(ofp, "usage: lttng create [options] [NAME]\n"); fprintf(ofp, "\n"); + fprintf(ofp, " The default NAME is 'auto-yyyymmdd-hhmmss'\n"); fprintf(ofp, " -h, --help Show this help\n"); - fprintf(ofp, " --list-options Simple listing of options\n"); + fprintf(ofp, " --list-options Simple listing of options\n"); fprintf(ofp, " -o, --output PATH Specify output path for traces\n"); fprintf(ofp, "\n"); } /* - * create_session + * Create a tracing session. + * If no name is specified, a default name is generated. * - * Create a tracing session. If no name specified, a default name will be - * generated. + * Returns one of the CMD_* result constants. */ static int create_session() { @@ -147,9 +148,9 @@ error: } /* - * cmd_create - * * The 'create ' first level command + * + * Returns one of the CMD_* result constants. */ int cmd_create(int argc, const char **argv) { diff --git a/src/lib/lttng-ctl/lttng-ctl.c b/src/lib/lttng-ctl/lttng-ctl.c index 6cc04efc9..c62dcfa1d 100644 --- a/src/lib/lttng-ctl/lttng-ctl.c +++ b/src/lib/lttng-ctl/lttng-ctl.c @@ -83,8 +83,8 @@ static void copy_lttng_domain(struct lttng_domain *dst, struct lttng_domain *src /* * Send lttcomm_session_msg to the session daemon. * - * On success, return 0 - * On error, return error code + * On success, returns the number of bytes sent (>=0) + * On error, returns -1 */ static int send_session_msg(struct lttcomm_session_msg *lsm) { @@ -105,8 +105,8 @@ end: /* * Receive data from the sessiond socket. * - * On success, return 0 - * On error, return recv() error code + * On success, returns the number of bytes received (>=0) + * On error, returns -1 (recvmsg() error) or -ENOTCONN */ static int recv_data_sessiond(void *buf, size_t len) { @@ -124,7 +124,7 @@ end: } /* - * Check if the specified group name exist. + * Check if we are in the specified group. * * If yes return 1, else return -1. */ @@ -155,11 +155,11 @@ static int check_tracing_group(const char *grp_name) /* Alloc group list of the right size */ grp_list = malloc(grp_list_size * sizeof(gid_t)); if (!grp_list) { - ret = -1; + perror("malloc"); goto end; } grp_id = getgroups(grp_list_size, grp_list); - if (grp_id < -1) { + if (grp_id < 0) { perror("getgroups"); goto free_list; } @@ -209,8 +209,10 @@ static int try_connect_sessiond(const char *sock_path) } /* - * Set sessiond socket path by putting it in the global sessiond_sock_path - * variable. + * Set sessiond socket path by putting it in the global + * sessiond_sock_path variable. + * Returns 0 on success, + * -ENOMEM on failure (the sessiond socket path is somehow too long) */ static int set_session_daemon_path(void) { @@ -268,7 +270,7 @@ static int connect_sessiond(void) ret = set_session_daemon_path(); if (ret < 0) { - return ret; + return -1; /* set_session_daemon_path() returns -ENOMEM */ } /* Connect to the sesssion daemon */ @@ -284,7 +286,8 @@ static int connect_sessiond(void) } /* - * Clean disconnect the session daemon. + * Clean disconnect from the session daemon. + * On success, return 0. On error, return -1. */ static int disconnect_sessiond(void) { @@ -373,6 +376,7 @@ end: /* * Create lttng handle and return pointer. + * The returned pointer will be NULL in case of malloc() error. */ struct lttng_handle *lttng_create_handle(const char *session_name, struct lttng_domain *domain) @@ -408,6 +412,7 @@ void lttng_destroy_handle(struct lttng_handle *handle) /* * Register an outside consumer. + * Returns size of returned session payload data or a negative error code. */ int lttng_register_consumer(struct lttng_handle *handle, const char *socket_path) @@ -425,7 +430,8 @@ int lttng_register_consumer(struct lttng_handle *handle, } /* - * Start tracing for all trace of the session. + * Start tracing for all traces of the session. + * Returns size of returned session payload data or a negative error code. */ int lttng_start_tracing(const char *session_name) { @@ -443,7 +449,8 @@ int lttng_start_tracing(const char *session_name) } /* - * Stop tracing for all trace of the session. + * Stop tracing for all traces of the session. + * Returns size of returned session payload data or a negative error code. */ int lttng_stop_tracing(const char *session_name) { @@ -496,7 +503,10 @@ int lttng_add_context(struct lttng_handle *handle, } /* - * Enable event + * Enable event(s) for a channel. + * If no event name is specified, all events are enabled. + * If no channel name is specified, the default 'channel0' is used. + * Returns size of returned session payload data or a negative error code. */ int lttng_enable_event(struct lttng_handle *handle, struct lttng_event *ev, const char *channel_name) @@ -532,7 +542,10 @@ int lttng_enable_event(struct lttng_handle *handle, } /* - * Disable event of a channel and domain. + * Disable event(s) of a channel and domain. + * If no event name is specified, all events are disabled. + * If no channel name is specified, the default 'channel0' is used. + * Returns size of returned session payload data or a negative error code. */ int lttng_disable_event(struct lttng_handle *handle, const char *name, const char *channel_name) @@ -567,7 +580,8 @@ int lttng_disable_event(struct lttng_handle *handle, const char *name, } /* - * Enable channel per domain + * Enable channel per domain + * Returns size of returned session payload data or a negative error code. */ int lttng_enable_channel(struct lttng_handle *handle, struct lttng_channel *chan) @@ -594,7 +608,8 @@ int lttng_enable_channel(struct lttng_handle *handle, } /* - * All tracing will be stopped for registered events of the channel. + * All tracing will be stopped for registered events of the channel. + * Returns size of returned session payload data or a negative error code. */ int lttng_disable_channel(struct lttng_handle *handle, const char *name) { @@ -619,10 +634,10 @@ int lttng_disable_channel(struct lttng_handle *handle, const char *name) } /* - * List all available tracepoints of domain. - * - * Return the size (bytes) of the list and set the events array. - * On error, return negative value. + * Lists all available tracepoints of domain. + * Sets the contents of the events array. + * Returns the number of lttng_event entries in events; + * on error, returns a negative value. */ int lttng_list_tracepoints(struct lttng_handle *handle, struct lttng_event **events) @@ -646,10 +661,12 @@ int lttng_list_tracepoints(struct lttng_handle *handle, } /* - * Return a human readable string of code + * Returns a human readable string describing + * the error code (a negative value). */ const char *lttng_strerror(int code) { + /* lttcomm error codes range from -LTTCOMM_OK down to -LTTCOMM_NR */ if (code > -LTTCOMM_OK) { return "Ended with errors"; } @@ -658,7 +675,8 @@ const char *lttng_strerror(int code) } /* - * Create a brand new session using name. + * Create a brand new session using name and path. + * Returns size of returned session payload data or a negative error code. */ int lttng_create_session(const char *name, const char *path) { @@ -673,6 +691,7 @@ int lttng_create_session(const char *name, const char *path) /* * Destroy session using name. + * Returns size of returned session payload data or a negative error code. */ int lttng_destroy_session(const char *session_name) { @@ -691,9 +710,9 @@ int lttng_destroy_session(const char *session_name) /* * Ask the session daemon for all available sessions. - * - * Return number of session. - * On error, return negative value. + * Sets the contents of the sessions array. + * Returns the number of lttng_session entries in sessions; + * on error, returns a negative value. */ int lttng_list_sessions(struct lttng_session **sessions) { @@ -710,7 +729,10 @@ int lttng_list_sessions(struct lttng_session **sessions) } /* - * List domain of a session. + * Ask the session daemon for all available domains of a session. + * Sets the contents of the domains array. + * Returns the number of lttng_domain entries in domains; + * on error, returns a negative value. */ int lttng_list_domains(const char *session_name, struct lttng_domain **domains) @@ -735,7 +757,10 @@ int lttng_list_domains(const char *session_name, } /* - * List channels of a session + * Ask the session daemon for all available channels of a session. + * Sets the contents of the channels array. + * Returns the number of lttng_channel entries in channels; + * on error, returns a negative value. */ int lttng_list_channels(struct lttng_handle *handle, struct lttng_channel **channels) @@ -762,7 +787,10 @@ int lttng_list_channels(struct lttng_handle *handle, } /* - * List events of a session channel. + * Ask the session daemon for all available events of a session channel. + * Sets the contents of the events array. + * Returns the number of lttng_event entries in events; + * on error, returns a negative value. */ int lttng_list_events(struct lttng_handle *handle, const char *channel_name, struct lttng_event **events) @@ -792,8 +820,9 @@ int lttng_list_events(struct lttng_handle *handle, } /* - * Set tracing group variable with name. This function allocate memory pointed - * by tracing_group. + * Sets the tracing_group variable with name. + * This function allocates memory pointed to by tracing_group. + * On success, returns 0, on error, returns -1 (null name) or -ENOMEM. */ int lttng_set_tracing_group(const char *name) { @@ -831,6 +860,7 @@ int lttng_calibrate(struct lttng_handle *handle, /* * Set default channel attributes. + * If either or both of the arguments are null, nothing happens. */ void lttng_channel_set_default_attr(struct lttng_domain *domain, struct lttng_channel_attr *attr) @@ -875,7 +905,7 @@ void lttng_channel_set_default_attr(struct lttng_domain *domain, * Check if session daemon is alive. * * Return 1 if alive or 0 if not. - * On error return -1 + * On error returns a negative value. */ int lttng_session_daemon_alive(void) { -- 2.34.1