[lttng-tools.git] / include / lttng / snapshot.h

/*
 * Copyright (C) 2013 David Goulet <dgoulet@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_SNAPSHOT_H
#define LTTNG_SNAPSHOT_H

#include <limits.h>
#include <stdint.h>
#include <sys/types.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Snapshot output object is opaque to the user. Use the helper functions below
 * to use them.
 */
struct lttng_snapshot_output;
struct lttng_snapshot_output_list;

/*
 * Return an newly allocated snapshot output object or NULL on error.
 */
struct lttng_snapshot_output *lttng_snapshot_output_create(void);

/*
 * Free a given snapshot output object.
 */
void lttng_snapshot_output_destroy(struct lttng_snapshot_output *output);

/*
 * Snapshot output getter family functions. They all return the value present
 * in the object.
 */

/* Return snapshot ID. */
uint32_t lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output);
/* Return maximum size of a snapshot. */
uint64_t lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output);
/* Return snapshot name. */
const char *lttng_snapshot_output_get_name(const struct lttng_snapshot_output *output);
/* Return snapshot control URL in a text format. */
const char *lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output *output);
/* Return snapshot data URL in a text format. */
const char *lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output *output);

/*
 * Snapshot output setter family functions.
 *
 * For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is
 * returned indicating that at least one given parameter is invalid.
 */

/* Set a custom ID. */
int lttng_snapshot_output_set_id(uint32_t id,
		struct lttng_snapshot_output *output);
/* Set the maximum size. */
int lttng_snapshot_output_set_size(uint64_t size,
		struct lttng_snapshot_output *output);
/* Set the snapshot name. */
int lttng_snapshot_output_set_name(const char *name,
		struct lttng_snapshot_output *output);

/*
 * Set the output destination to be a path on the local filesystem.
 *
 * The path must be absolute. It can optionally begin with `file://`.
 *
 * Return 0 on success or else a negative LTTNG_ERR code.
 */
int lttng_snapshot_output_set_local_path(const char *path,
		struct lttng_snapshot_output *output);

/*
 * Set the output destination to be the network from a combined control/data
 * URL.
 *
 * `url` must start with `net://` or `net6://`.
 *
 * Return 0 on success or else a negative LTTNG_ERR code.
 */
int lttng_snapshot_output_set_network_url(const char *url,
		struct lttng_snapshot_output *output);

/*
 * Set the output destination to be the network using separate URLs for control
 * and data.
 *
 * Both ctrl_url and data_url must be non-null.
 *
 * `ctrl_url` and `data_url` must start with `tcp://` or `tcp6://`.
 *
 * Return 0 on success or else a negative LTTNG_ERR code.
 */
int lttng_snapshot_output_set_network_urls(
		const char *ctrl_url, const char *data_url,
		struct lttng_snapshot_output *output);

/* Set the control URL. Local and remote URL are supported. */
int lttng_snapshot_output_set_ctrl_url(const char *url,
		struct lttng_snapshot_output *output);
/* Set the data URL. Local and remote URL are supported. */
int lttng_snapshot_output_set_data_url(const char *url,
		struct lttng_snapshot_output *output);

/*
 * Add an output object to a session identified by name.
 *
 * Return 0 on success or else a negative LTTNG_ERR code.
 */
int lttng_snapshot_add_output(const char *session_name,
		struct lttng_snapshot_output *output);

/*
 * Delete an output object to a session identified by name.
 *
 * Return 0 on success or else a negative LTTNG_ERR code.
 */
int lttng_snapshot_del_output(const char *session_name,
		struct lttng_snapshot_output *output);

/*
 * List all snapshot output(s) of a session identified by name. The output list
 * object is populated and can be iterated over with the get_next call below.
 *
 * Return 0 on success or else a negative LTTNG_ERR code and the list pointer
 * is untouched.
 */
int lttng_snapshot_list_output(const char *session_name,
		struct lttng_snapshot_output_list **list);

/*
 * Return the next available snapshot output object in the given list. A list
 * output command MUST have been done before.
 *
 * Return the next object on success or else NULL indicating the end of the
 * list.
 */
struct lttng_snapshot_output *lttng_snapshot_output_list_get_next(
		struct lttng_snapshot_output_list *list);

/*
 * Free an output list object.
 */
void lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list);

/*
 * Snapshot a trace for the given session.
 *
 * The output object can be NULL but an add output MUST be done prior to this
 * call. If it's not NULL, it will be used to snapshot a trace.
 *
 * The wait parameter is ignored for now. The snapshot record command will
 * ALWAYS wait for the snapshot to complete before returning meaning the
 * snapshot has been written on disk or streamed over the network to a relayd.
 *
 * Return 0 on success or else a negative LTTNG_ERR value.
 */
int lttng_snapshot_record(const char *session_name,
		struct lttng_snapshot_output *output, int wait);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_SNAPSHOT_H */
Commit	Line	Data
	1	/*
	2	* Copyright (C) 2013 David Goulet <dgoulet@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef LTTNG_SNAPSHOT_H
	9	#define LTTNG_SNAPSHOT_H
	10
	11	#include <limits.h>
	12	#include <stdint.h>
	13	#include <sys/types.h>
	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
	19	/*
	20	* Snapshot output object is opaque to the user. Use the helper functions below
	21	* to use them.
	22	*/
	23	struct lttng_snapshot_output;
	24	struct lttng_snapshot_output_list;
	25
	26	/*
	27	* Return an newly allocated snapshot output object or NULL on error.
	28	*/
	29	struct lttng_snapshot_output *lttng_snapshot_output_create(void);
	30
	31	/*
	32	* Free a given snapshot output object.
	33	*/
	34	void lttng_snapshot_output_destroy(struct lttng_snapshot_output *output);
	35
	36	/*
	37	* Snapshot output getter family functions. They all return the value present
	38	* in the object.
	39	*/
	40
	41	/* Return snapshot ID. */
	42	uint32_t lttng_snapshot_output_get_id(const struct lttng_snapshot_output *output);
	43	/* Return maximum size of a snapshot. */
	44	uint64_t lttng_snapshot_output_get_maxsize(const struct lttng_snapshot_output *output);
	45	/* Return snapshot name. */
	46	const char lttng_snapshot_output_get_name(const struct lttng_snapshot_output output);
	47	/* Return snapshot control URL in a text format. */
	48	const char lttng_snapshot_output_get_ctrl_url(const struct lttng_snapshot_output output);
	49	/* Return snapshot data URL in a text format. */
	50	const char lttng_snapshot_output_get_data_url(const struct lttng_snapshot_output output);
	51
	52	/*
	53	* Snapshot output setter family functions.
	54	*
	55	* For every set* call, 0 is returned on success or else -LTTNG_ERR_INVALID is
	56	* returned indicating that at least one given parameter is invalid.
	57	*/
	58
	59	/* Set a custom ID. */
	60	int lttng_snapshot_output_set_id(uint32_t id,
	61	struct lttng_snapshot_output *output);
	62	/* Set the maximum size. */
	63	int lttng_snapshot_output_set_size(uint64_t size,
	64	struct lttng_snapshot_output *output);
	65	/* Set the snapshot name. */
	66	int lttng_snapshot_output_set_name(const char *name,
	67	struct lttng_snapshot_output *output);
	68
	69	/*
	70	* Set the output destination to be a path on the local filesystem.
	71	*
	72	* The path must be absolute. It can optionally begin with `file://`.
	73	*
	74	* Return 0 on success or else a negative LTTNG_ERR code.
	75	*/
	76	int lttng_snapshot_output_set_local_path(const char *path,
	77	struct lttng_snapshot_output *output);
	78
	79	/*
	80	* Set the output destination to be the network from a combined control/data
	81	* URL.
	82	*
	83	* `url` must start with `net://` or `net6://`.
	84	*
	85	* Return 0 on success or else a negative LTTNG_ERR code.
	86	*/
	87	int lttng_snapshot_output_set_network_url(const char *url,
	88	struct lttng_snapshot_output *output);
	89
	90	/*
	91	* Set the output destination to be the network using separate URLs for control
	92	* and data.
	93	*
	94	* Both ctrl_url and data_url must be non-null.
	95	*
	96	* `ctrl_url` and `data_url` must start with `tcp://` or `tcp6://`.
	97	*
	98	* Return 0 on success or else a negative LTTNG_ERR code.
	99	*/
	100	int lttng_snapshot_output_set_network_urls(
	101	const char ctrl_url, const char data_url,
	102	struct lttng_snapshot_output *output);
	103
	104	/* Set the control URL. Local and remote URL are supported. */
	105	int lttng_snapshot_output_set_ctrl_url(const char *url,
	106	struct lttng_snapshot_output *output);
	107	/* Set the data URL. Local and remote URL are supported. */
	108	int lttng_snapshot_output_set_data_url(const char *url,
	109	struct lttng_snapshot_output *output);
	110
	111	/*
	112	* Add an output object to a session identified by name.
	113	*
	114	* Return 0 on success or else a negative LTTNG_ERR code.
	115	*/
	116	int lttng_snapshot_add_output(const char *session_name,
	117	struct lttng_snapshot_output *output);
	118
	119	/*
	120	* Delete an output object to a session identified by name.
	121	*
	122	* Return 0 on success or else a negative LTTNG_ERR code.
	123	*/
	124	int lttng_snapshot_del_output(const char *session_name,
	125	struct lttng_snapshot_output *output);
	126
	127	/*
	128	* List all snapshot output(s) of a session identified by name. The output list
	129	* object is populated and can be iterated over with the get_next call below.
	130	*
	131	* Return 0 on success or else a negative LTTNG_ERR code and the list pointer
	132	* is untouched.
	133	*/
	134	int lttng_snapshot_list_output(const char *session_name,
	135	struct lttng_snapshot_output_list **list);
	136
	137	/*
	138	* Return the next available snapshot output object in the given list. A list
	139	* output command MUST have been done before.
	140	*
	141	* Return the next object on success or else NULL indicating the end of the
	142	* list.
	143	*/
	144	struct lttng_snapshot_output *lttng_snapshot_output_list_get_next(
	145	struct lttng_snapshot_output_list *list);
	146
	147	/*
	148	* Free an output list object.
	149	*/
	150	void lttng_snapshot_output_list_destroy(struct lttng_snapshot_output_list *list);
	151
	152	/*
	153	* Snapshot a trace for the given session.
	154	*
	155	* The output object can be NULL but an add output MUST be done prior to this
	156	* call. If it's not NULL, it will be used to snapshot a trace.
	157	*
	158	* The wait parameter is ignored for now. The snapshot record command will
	159	* ALWAYS wait for the snapshot to complete before returning meaning the
	160	* snapshot has been written on disk or streamed over the network to a relayd.
	161	*
	162	* Return 0 on success or else a negative LTTNG_ERR value.
	163	*/
	164	int lttng_snapshot_record(const char *session_name,
	165	struct lttng_snapshot_output *output, int wait);
	166
	167	#ifdef __cplusplus
	168	}
	169	#endif
	170
	171	#endif /* LTTNG_SNAPSHOT_H */