@@ -270,13 +270,13 @@ struct tracecmd_option;
struct tracecmd_msg_handle;
struct tracecmd_output *tracecmd_output_allocate(int fd);
-int tracecmd_output_set_msg(struct tracecmd_output *handler,
+int tracecmd_output_set_msg(struct tracecmd_output *handle,
struct tracecmd_msg_handle *msg_handle);
-int tracecmd_output_set_trace_dir(struct tracecmd_output *handler, const char *tracing_dir);
-int tracecmd_output_set_kallsyms(struct tracecmd_output *handler, const char *kallsyms);
-int tracecmd_output_set_from_input(struct tracecmd_output *handler, struct tracecmd_input *ihandle);
-int tracecmd_output_write_init(struct tracecmd_output *handler);
-int tracecmd_output_write_headers(struct tracecmd_output *handler,
+int tracecmd_output_set_trace_dir(struct tracecmd_output *handle, const char *tracing_dir);
+int tracecmd_output_set_kallsyms(struct tracecmd_output *handle, const char *kallsyms);
+int tracecmd_output_set_from_input(struct tracecmd_output *handle, struct tracecmd_input *ihandle);
+int tracecmd_output_write_init(struct tracecmd_output *handle);
+int tracecmd_output_write_headers(struct tracecmd_output *handle,
struct tracecmd_event_list *list);
struct tracecmd_output *tracecmd_create_file_latency(const char *output_file, int cpus);
@@ -880,16 +880,16 @@ out_free:
}
/**
- * tracecmd_output_allocate - allocate new output handler to a trace file
- * @handle: file descriptor to an empty file, it can be -1 if the handler
- * will not write to a file
+ * tracecmd_output_allocate - allocate new output handle to a trace file
+ * @fd: File descriptor for the handle to write to.
*
- * This API only allocates a handler and performs minimal initialization.
- * No data is written in the file.
+ * Allocate a tracecmd_output descriptor and perform minimal initialization.
+ * @fd will be set as the file descriptor for the handle. Nothing is
+ * written in the file yet, and if @fd is -1, then all writes will be ignored.
*
- * Returns pointer to a newly allocated file descriptor, that can be used
- * with other library APIs. In case of an error, NULL is returned. The returned
- * handler must be freed with tracecmd_output_close() or tracecmd_output_free()
+ * Returns a pointer to a newly allocated file descriptor for the use of creating
+ * a tracecmd data file. In case of an error, NULL is returned. The returned
+ * handle must be freed with tracecmd_output_close() or tracecmd_output_free()
*/
struct tracecmd_output *tracecmd_output_allocate(int fd)
{
@@ -914,121 +914,133 @@ struct tracecmd_output *tracecmd_output_allocate(int fd)
}
/**
- * tracecmd_output_set_msg - associated an output file handler with network message handler
- * @handle: output handler to a trace file.
- * @msg_handle: network handler, allocated by tracecmd_msg_handle_alloc()
+ * tracecmd_output_set_msg - associated an output file handle with network message handle
+ * @handle: output handle to a trace file.
+ * @msg_handle: network handle, allocated by tracecmd_msg_handle_alloc()
*
- * This API associates an output file handler with a network stream. All subsequent API calls
- * with this output file handler will send data over the network using the @msg_handle, instead
- * of writing to a file.
- * This API must be called after the handler file version is set and before
+ * Associate an output file handle (@handle) to a network stream (@msg_handle).
+ * All subsequent calls to @handle will send data over the network using @msg_handle
+ * instead of writing to a file.
+ *
+ * This mut be called after the handle file version is set and before calling
* tracecmd_output_write_init().
*
- * Returns 0 on success, or -1 if the output file handler is not allocated or not in expected state.
+ * Returns 0 on success, or -1 if the output file handle is not allocated or not
+ * in the expected state.
*/
-int tracecmd_output_set_msg(struct tracecmd_output *handler, struct tracecmd_msg_handle *msg_handle)
+int tracecmd_output_set_msg(struct tracecmd_output *handle, struct tracecmd_msg_handle *msg_handle)
{
- if (!handler || handler->file_state != TRACECMD_FILE_ALLOCATED)
+ if (!handle || handle->file_state != TRACECMD_FILE_ALLOCATED)
return -1;
- handler->msg_handle = msg_handle;
+ handle->msg_handle = msg_handle;
return 0;
}
/**
* tracecmd_output_set_trace_dir - Set a custom tracing dir, instead of system default
- * @handle: output handler to a trace file.
+ * @handle: output handle to a trace file.
* @tracing_dir: full path to a directory with tracing files
*
- * This API associates an output file handler with a custom tracing directory, to be used when
- * creating the trace file instead of the system default tracing directory.
- * This API must be called before tracecmd_output_write_init().
+ * Associate the output file handle (@handle) with a custom tracing directory
+ * (@tracing_dir), to be used when creating the trace file instead of using the
+ * system default tracig directory.
+ *
+ * Must be called before tracecmd_output_write_init().
*
- * Returns 0 on success, or -1 if the output file handler is not allocated or not in expected state.
+ * Returns 0 on success, or -1 if the output file handle is not allocated or not
+ * in the expected state.
*/
-int tracecmd_output_set_trace_dir(struct tracecmd_output *handler, const char *tracing_dir)
+int tracecmd_output_set_trace_dir(struct tracecmd_output *handle, const char *tracing_dir)
{
- if (!handler || handler->file_state != TRACECMD_FILE_ALLOCATED)
+ if (!handle || handle->file_state != TRACECMD_FILE_ALLOCATED)
return -1;
- free(handler->tracing_dir);
+ free(handle->tracing_dir);
if (tracing_dir) {
- handler->tracing_dir = strdup(tracing_dir);
- if (!handler->tracing_dir)
+ handle->tracing_dir = strdup(tracing_dir);
+ if (!handle->tracing_dir)
return -1;
} else
- handler->tracing_dir = NULL;
+ handle->tracing_dir = NULL;
return 0;
}
/**
- * tracecmd_output_set_kallsyms - Set a custom kernel symbols file, instead of system default
- * @handle: output handler to a trace file.
+ * tracecmd_output_set_kallsyms - Set a custom kernel symbols file
+ * @handle: output handle to a trace file.
* @tracing_dir: full path to a file with kernel symbols
*
- * This API associates an output file handler with a custom kernel symbols file, to be used when
- * creating the trace file instead of the system default kernel symbols file.
- * This API must be called before tracecmd_output_write_init().
+ * Have the output file handle (@handle) use a custom kernel symbols file instead
+ * of the default /proc/kallsyms.
+ *
+ * Must be called before tracecmd_output_write_init().
*
- * Returns 0 on success, or -1 if the output file handler is not allocated or not in expected state.
+ * Returns 0 on success, or -1 if the output file handle is not allocated or
+ * not in the expected state.
*/
-int tracecmd_output_set_kallsyms(struct tracecmd_output *handler, const char *kallsyms)
+int tracecmd_output_set_kallsyms(struct tracecmd_output *handle, const char *kallsyms)
{
- if (!handler || handler->file_state != TRACECMD_FILE_ALLOCATED)
+ if (!handle || handle->file_state != TRACECMD_FILE_ALLOCATED)
return -1;
- free(handler->kallsyms);
+ free(handle->kallsyms);
if (kallsyms) {
- handler->kallsyms = strdup(kallsyms);
- if (!handler->kallsyms)
+ handle->kallsyms = strdup(kallsyms);
+ if (!handle->kallsyms)
return -1;
} else
- handler->kallsyms = NULL;
+ handle->kallsyms = NULL;
return 0;
}
/**
* tracecmd_output_set_from_input - Inherit parameters from an existing trace file
- * @handle: output handler to a trace file.
- * @ihandle: input handler to an existing trace file.
+ * @handle: output handle to a trace file.
+ * @ihandle: input handle to an existing trace file.
*
- * This API copies parameters from input handler @ihandle, associated with an existing trace file,
- * to the output handler @handle, associated with file that is going to be created.
- * These parameters are copied:
- * - tep handler
+ * Have the output file handle (@handle) inherit the properties of a given
+ * input file handle (@ihandle).
+ *
+ * The parameters that are copied are:
+ * - tep handle
* - page size
* - file endian
* - file version
* - file compression protocol
- * This API must be called before tracecmd_output_write_init().
*
- * Returns 0 on success, or -1 if the output file handler is not allocated or not in expected state.
+ * Must be called before tracecmd_output_write_init().
+ *
+ * Returns 0 on success, or -1 if the output file handle is not allocated or
+ * not in expected state.
*/
-int tracecmd_output_set_from_input(struct tracecmd_output *handler, struct tracecmd_input *ihandle)
+int tracecmd_output_set_from_input(struct tracecmd_output *handle, struct tracecmd_input *ihandle)
{
- if (!handler || !ihandle || handler->file_state != TRACECMD_FILE_ALLOCATED)
+ if (!handle || !ihandle || handle->file_state != TRACECMD_FILE_ALLOCATED)
return -1;
/* get endian, page size, file version and compression */
/* Use the pevent of the ihandle for later writes */
- handler->pevent = tracecmd_get_tep(ihandle);
- tep_ref(handler->pevent);
- handler->page_size = tracecmd_page_size(ihandle);
- handler->file_version = tracecmd_get_in_file_version(ihandle);
- handler->big_endian = tep_is_file_bigendian(handler->pevent);
+ handle->pevent = tracecmd_get_tep(ihandle);
+ tep_ref(handle->pevent);
+ handle->page_size = tracecmd_page_size(ihandle);
+ handle->file_version = tracecmd_get_in_file_version(ihandle);
+ handle->big_endian = tep_is_file_bigendian(handle->pevent);
return 0;
}
/**
- * tracecmd_output_write_init - Write the initial magics in the trace file
- * @handle: output handler to a trace file.
+ * tracecmd_output_write_init - Write the initial data into the trace file
+ * @handle: output handle to a trace file.
*
- * This API must be called after all tracecmd_output_set_...() APIs and before writing anything
- * to the trace file. This initial information is written in the file:
+ * Must be called after tracecmd_output_set_*() functions and before writing
+ * anything else.
+ *
+ * The initial information to be written into the file:
* - initial file magic bytes
* - file version
* - data endian
@@ -1036,14 +1048,15 @@ int tracecmd_output_set_from_input(struct tracecmd_output *handler, struct trace
* - page size
* - compression header
*
- * Returns 0 on success, or -1 if the output file handler is not allocated or not in expected state.
+ * Returns 0 on success, or -1 if the output file handle is not allocated or
+ * not in the expected state.
*/
-int tracecmd_output_write_init(struct tracecmd_output *handler)
+int tracecmd_output_write_init(struct tracecmd_output *handle)
{
char buf[BUFSIZ];
int endian4;
- if (!handler || handler->file_state != TRACECMD_FILE_ALLOCATED)
+ if (!handle || handle->file_state != TRACECMD_FILE_ALLOCATED)
return -1;
buf[0] = 23;
@@ -1051,35 +1064,35 @@ int tracecmd_output_write_init(struct tracecmd_output *handler)
buf[2] = 68;
memcpy(buf + 3, "tracing", 7);
- if (do_write_check(handler, buf, 10))
+ if (do_write_check(handle, buf, 10))
return -1;
- sprintf(buf, "%lu", handler->file_version);
- if (do_write_check(handler, buf, strlen(buf) + 1))
+ sprintf(buf, "%lu", handle->file_version);
+ if (do_write_check(handle, buf, strlen(buf) + 1))
return -1;
- if (handler->big_endian)
+ if (handle->big_endian)
buf[0] = 1;
else
buf[0] = 0;
- if (do_write_check(handler, buf, 1))
+ if (do_write_check(handle, buf, 1))
return -1;
/* save size of long (this may not be what the kernel is) */
buf[0] = sizeof(long);
- if (do_write_check(handler, buf, 1))
+ if (do_write_check(handle, buf, 1))
return -1;
- endian4 = convert_endian_4(handler, handler->page_size);
- if (do_write_check(handler, &endian4, 4))
+ endian4 = convert_endian_4(handle, handle->page_size);
+ if (do_write_check(handle, &endian4, 4))
return -1;
- handler->file_state = TRACECMD_FILE_INIT;
+ handle->file_state = TRACECMD_FILE_INIT;
return 0;
}
/**
* tracecmd_output_write_headers - Write the trace file headers
- * @handle: output handler to a trace file.
+ * @handle: output handle to a trace file.
* @list: desired events that will be included in the trace file.
* It can be NULL for all available events
*
@@ -1092,24 +1105,24 @@ int tracecmd_output_write_init(struct tracecmd_output *handler)
*
* Returns 0 on success, or -1 in case of an error.
*/
-int tracecmd_output_write_headers(struct tracecmd_output *handler,
+int tracecmd_output_write_headers(struct tracecmd_output *handle,
struct tracecmd_event_list *list)
{
- if (!handler || handler->file_state < TRACECMD_FILE_ALLOCATED)
+ if (!handle || handle->file_state < TRACECMD_FILE_ALLOCATED)
return -1;
/* Write init data, if not written yet */
- if (handler->file_state < TRACECMD_FILE_INIT && tracecmd_output_write_init(handler))
+ if (handle->file_state < TRACECMD_FILE_INIT && tracecmd_output_write_init(handle))
return -1;
- if (read_header_files(handler))
+ if (read_header_files(handle))
return -1;
- if (read_ftrace_files(handler))
+ if (read_ftrace_files(handle))
return -1;
- if (read_event_files(handler, list))
+ if (read_event_files(handle, list))
return -1;
- if (read_proc_kallsyms(handler))
+ if (read_proc_kallsyms(handle))
return -1;
- if (read_ftrace_printk(handler))
+ if (read_ftrace_printk(handle))
return -1;
return 0;
}