Fix one return values that would return an -ENOMEM instead of a -1 on
error.
Signed-off-by: Daniel U. Thibault <daniel.thibault@drdc-rddc.gc.ca>
Signed-off-by: David Goulet <dgoulet@efficios.com>
/*
* Calibrate LTTng tracer.
/*
* Calibrate LTTng tracer.
+ *
+ * Returns a CMD_* error.
*/
int cmd_calibrate(int argc, const char **argv)
{
*/
int cmd_calibrate(int argc, const char **argv)
{
{
fprintf(ofp, "usage: lttng create [options] [NAME]\n");
fprintf(ofp, "\n");
{
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, " -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");
}
/*
fprintf(ofp, " -o, --output PATH Specify output path for traces\n");
fprintf(ofp, "\n");
}
/*
+ * 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()
{
*/
static int create_session()
{
* The 'create <options>' first level command
* The 'create <options>' first level command
+ *
+ * Returns one of the CMD_* result constants.
*/
int cmd_create(int argc, const char **argv)
{
*/
int cmd_create(int argc, const char **argv)
{
/*
* Send lttcomm_session_msg to the session daemon.
*
/*
* 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)
{
*/
static int send_session_msg(struct lttcomm_session_msg *lsm)
{
/*
* Receive data from the sessiond socket.
*
/*
* 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)
{
*/
static int recv_data_sessiond(void *buf, size_t len)
{
- * Check if the specified group name exist.
+ * Check if we are in the specified group.
*
* If yes return 1, else return -1.
*/
*
* If yes return 1, else return -1.
*/
/* Alloc group list of the right size */
grp_list = malloc(grp_list_size * sizeof(gid_t));
if (!grp_list) {
/* Alloc group list of the right size */
grp_list = malloc(grp_list_size * sizeof(gid_t));
if (!grp_list) {
goto end;
}
grp_id = getgroups(grp_list_size, grp_list);
goto end;
}
grp_id = getgroups(grp_list_size, grp_list);
perror("getgroups");
goto free_list;
}
perror("getgroups");
goto free_list;
}
- * 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)
{
*/
static int set_session_daemon_path(void)
{
ret = set_session_daemon_path();
if (ret < 0) {
ret = set_session_daemon_path();
if (ret < 0) {
+ return -1; /* set_session_daemon_path() returns -ENOMEM */
}
/* Connect to the sesssion daemon */
}
/* Connect to the sesssion daemon */
- * Clean disconnect the session daemon.
+ * Clean disconnect from the session daemon.
+ * On success, return 0. On error, return -1.
*/
static int disconnect_sessiond(void)
{
*/
static int disconnect_sessiond(void)
{
/*
* Create lttng handle and return pointer.
/*
* 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)
*/
struct lttng_handle *lttng_create_handle(const char *session_name,
struct lttng_domain *domain)
/*
* Register an outside consumer.
/*
* 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)
*/
int lttng_register_consumer(struct lttng_handle *handle,
const char *socket_path)
- * 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)
{
*/
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)
{
*/
int lttng_stop_tracing(const char *session_name)
{
+ * 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)
*/
int lttng_enable_event(struct lttng_handle *handle,
struct lttng_event *ev, const char *channel_name)
- * 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)
*/
int lttng_disable_event(struct lttng_handle *handle, const char *name,
const char *channel_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)
*/
int lttng_enable_channel(struct lttng_handle *handle,
struct lttng_channel *chan)
- * 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)
{
*/
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)
*/
int lttng_list_tracepoints(struct lttng_handle *handle,
struct lttng_event **events)
- * 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)
{
*/
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";
}
if (code > -LTTCOMM_OK) {
return "Ended with errors";
}
- * 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)
{
*/
int lttng_create_session(const char *name, const char *path)
{
/*
* Destroy session using name.
/*
* Destroy session using name.
+ * Returns size of returned session payload data or a negative error code.
*/
int lttng_destroy_session(const char *session_name)
{
*/
int lttng_destroy_session(const char *session_name)
{
/*
* Ask the session daemon for all available sessions.
/*
* 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)
{
*/
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)
*/
int lttng_list_domains(const char *session_name,
struct lttng_domain **domains)
- * 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)
*/
int lttng_list_channels(struct lttng_handle *handle,
struct lttng_channel **channels)
- * 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)
*/
int lttng_list_events(struct lttng_handle *handle,
const char *channel_name, struct lttng_event **events)
- * 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)
{
*/
int lttng_set_tracing_group(const char *name)
{
/*
* Set default channel attributes.
/*
* 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)
*/
void lttng_channel_set_default_attr(struct lttng_domain *domain,
struct lttng_channel_attr *attr)
* Check if session daemon is alive.
*
* Return 1 if alive or 0 if not.
* Check if session daemon is alive.
*
* Return 1 if alive or 0 if not.
+ * On error returns a negative value.
*/
int lttng_session_daemon_alive(void)
{
*/
int lttng_session_daemon_alive(void)
{