[lttng-tools.git] / src / common / trace-chunk.h

/*
 * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License, version 2.1 only,
 * as published by the Free Software Foundation.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
 * for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
 */

#ifndef LTTNG_TRACE_CHUNK_H
#define LTTNG_TRACE_CHUNK_H

#include <common/compat/directory-handle.h>
#include <common/credentials.h>
#include <common/fd-tracker/fd-tracker.h>
#include <common/macros.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>

/*
 * A trace chunk is a group of directories and files forming a (or a set of)
 * complete and independant trace(s). For instance, a trace archive chunk,
 * a snapshot, or a regular LTTng trace are all instances of a trace archive.
 *
 * A trace chunk is always contained within a session output directory.
 *
 * This facility is used by the session daemon, consumer daemon(s), and relay
 * daemon to:
 *   - Control file (data stream, metadata, and index) creation relative to
 *     a given output directory,
 *   - Track the use of an output directory by other objects in order to
 *     know if/when an output directory can be safely consumed, renamed,
 *     deleted, etc.
 *
 *
 * OWNER VS USER
 * ---
 *
 * A trace chunk can either be a owner or a user of its
 * "chunk output directory".
 *
 * A "user" trace chunk is provided with a handle to the chunk output directory
 * which can then be used to create subdirectories and files.
 *
 * An "owner" chunk, on top of being able to perform the operations of a "user"
 * chunk can perform operations on its chunk output directory, such as renaming
 * or deleting it.
 *
 * A trace chunk becomes an "owner" or "user" chunk based on which of
 * 'lttng_trace_chunk_set_as_owner()' or 'lttng_trace_chunk_set_as_user()' is
 * used. These methods are _exclusive_ and must only be used once on a
 * trace chunk.
 */

struct lttng_trace_chunk;
struct fd_tracker;

enum lttng_trace_chunk_status {
        LTTNG_TRACE_CHUNK_STATUS_OK,
	LTTNG_TRACE_CHUNK_STATUS_NONE,
	LTTNG_TRACE_CHUNK_STATUS_INVALID_ARGUMENT,
	LTTNG_TRACE_CHUNK_STATUS_INVALID_OPERATION,
	LTTNG_TRACE_CHUNK_STATUS_ERROR,
	LTTNG_TRACE_CHUNK_STATUS_NO_FILE,
};

enum lttng_trace_chunk_command_type {
	LTTNG_TRACE_CHUNK_COMMAND_TYPE_MOVE_TO_COMPLETED = 0,
	LTTNG_TRACE_CHUNK_COMMAND_TYPE_NO_OPERATION = 1,
	LTTNG_TRACE_CHUNK_COMMAND_TYPE_DELETE = 2,
	LTTNG_TRACE_CHUNK_COMMAND_TYPE_MAX,
};

LTTNG_HIDDEN
struct lttng_trace_chunk *lttng_trace_chunk_create_anonymous(void);

LTTNG_HIDDEN
struct lttng_trace_chunk *lttng_trace_chunk_create(
		uint64_t chunk_id,
		time_t chunk_creation_time,
		const char *path);

LTTNG_HIDDEN
void lttng_trace_chunk_set_fd_tracker(struct lttng_trace_chunk *chunk,
		struct fd_tracker *fd_tracker);

/*
 * Copy a trace chunk. The copy that is returned is always a _user_
 * mode chunk even if the source chunk was an _owner_ as there can never be
 * two _owners_ of the same trace output.
 */
LTTNG_HIDDEN
struct lttng_trace_chunk *lttng_trace_chunk_copy(
		struct lttng_trace_chunk *source_chunk);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_id(
		struct lttng_trace_chunk *chunk, uint64_t *id);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_creation_timestamp(
		struct lttng_trace_chunk *chunk, time_t *creation_ts);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_close_timestamp(
		struct lttng_trace_chunk *chunk, time_t *close_ts);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_close_timestamp(
		struct lttng_trace_chunk *chunk, time_t close_ts);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_name(
		struct lttng_trace_chunk *chunk, const char **name,
		bool *name_overridden);

LTTNG_HIDDEN
bool lttng_trace_chunk_get_name_overridden(struct lttng_trace_chunk *chunk);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_override_name(
		struct lttng_trace_chunk *chunk, const char *name);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_rename_path(
		struct lttng_trace_chunk *chunk, const char *path);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_credentials(
		struct lttng_trace_chunk *chunk,
		struct lttng_credentials *credentials);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_credentials(
		struct lttng_trace_chunk *chunk,
		const struct lttng_credentials *credentials);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_credentials_current_user(
		struct lttng_trace_chunk *chunk);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_as_owner(
		struct lttng_trace_chunk *chunk,
		struct lttng_directory_handle *session_output_directory);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_as_user(
		struct lttng_trace_chunk *chunk,
		struct lttng_directory_handle *chunk_directory);

LTTNG_HIDDEN
enum lttng_trace_chunk_status
lttng_trace_chunk_get_session_output_directory_handle(
		struct lttng_trace_chunk *chunk,
		struct lttng_directory_handle **handle);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_borrow_chunk_directory_handle(
		struct lttng_trace_chunk *chunk,
		const struct lttng_directory_handle **handle);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_create_subdirectory(
		struct lttng_trace_chunk *chunk,
		const char *subdirectory_path);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_open_file(
		struct lttng_trace_chunk *chunk,
		const char *filename,
		int flags,
		mode_t mode,
		int *out_fd,
		bool expect_no_file);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_open_fs_handle(
		struct lttng_trace_chunk *chunk,
		const char *filename,
		int flags,
		mode_t mode,
		struct fs_handle **out_handle,
		bool expect_no_file);

LTTNG_HIDDEN
int lttng_trace_chunk_unlink_file(struct lttng_trace_chunk *chunk,
		const char *filename);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_get_close_command(
		struct lttng_trace_chunk *chunk,
		enum lttng_trace_chunk_command_type *command_type);

LTTNG_HIDDEN
enum lttng_trace_chunk_status lttng_trace_chunk_set_close_command(
		struct lttng_trace_chunk *chunk,
		enum lttng_trace_chunk_command_type command_type);

LTTNG_HIDDEN
const char *lttng_trace_chunk_command_type_get_name(
		enum lttng_trace_chunk_command_type command);

/* Returns true on success. */
LTTNG_HIDDEN
bool lttng_trace_chunk_get(struct lttng_trace_chunk *chunk);

LTTNG_HIDDEN
void lttng_trace_chunk_put(struct lttng_trace_chunk *chunk);

#endif /* LTTNG_TRACE_CHUNK_H */
Commit	Line	Data
2c5ff4e4 JG	1	/*
	2	* Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	*
	4	* This program is free software; you can redistribute it and/or modify it
	5	* under the terms of the GNU Lesser General Public License, version 2.1 only,
	6	* as published by the Free Software Foundation.
	7	*
	8	* This program is distributed in the hope that it will be useful, but WITHOUT
	9	* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	10	* FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
	11	* for more details.
	12	*
	13	* You should have received a copy of the GNU Lesser General Public License
	14	* along with this program; if not, write to the Free Software Foundation,
	15	* Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
	16	*/
	17
	18	#ifndef LTTNG_TRACE_CHUNK_H
	19	#define LTTNG_TRACE_CHUNK_H
	20
2c5ff4e4	21	#include <common/compat/directory-handle.h>
8bb66c3c JG	22	#include <common/credentials.h>
	23	#include <common/fd-tracker/fd-tracker.h>
	24	#include <common/macros.h>
	25	#include <stdbool.h>
2c5ff4e4 JG	26	#include <stddef.h>
2c5ff4e4 JG	27	#include <stdint.h>
2c5ff4e4 JG	28
	29	/*
	30	* A trace chunk is a group of directories and files forming a (or a set of)
	31	* complete and independant trace(s). For instance, a trace archive chunk,
	32	* a snapshot, or a regular LTTng trace are all instances of a trace archive.
	33	*
	34	* A trace chunk is always contained within a session output directory.
	35	*
	36	* This facility is used by the session daemon, consumer daemon(s), and relay
	37	* daemon to:
	38	* - Control file (data stream, metadata, and index) creation relative to
	39	* a given output directory,
	40	* - Track the use of an output directory by other objects in order to
	41	* know if/when an output directory can be safely consumed, renamed,
	42	* deleted, etc.
	43	*
	44	*
	45	* OWNER VS USER
	46	* ---
	47	*
	48	* A trace chunk can either be a owner or a user of its
	49	* "chunk output directory".
	50	*
	51	* A "user" trace chunk is provided with a handle to the chunk output directory
	52	* which can then be used to create subdirectories and files.
	53	*
	54	* An "owner" chunk, on top of being able to perform the operations of a "user"
	55	* chunk can perform operations on its chunk output directory, such as renaming
	56	* or deleting it.
	57	*
	58	* A trace chunk becomes an "owner" or "user" chunk based on which of
	59	* 'lttng_trace_chunk_set_as_owner()' or 'lttng_trace_chunk_set_as_user()' is
	60	* used. These methods are _exclusive_ and must only be used once on a
	61	* trace chunk.
	62	*/
	63
	64	struct lttng_trace_chunk;
b2621f79	65	struct fd_tracker;
2c5ff4e4 JG	66
	67	enum lttng_trace_chunk_status {
	68	LTTNG_TRACE_CHUNK_STATUS_OK,
	69	LTTNG_TRACE_CHUNK_STATUS_NONE,
	70	LTTNG_TRACE_CHUNK_STATUS_INVALID_ARGUMENT,
	71	LTTNG_TRACE_CHUNK_STATUS_INVALID_OPERATION,
	72	LTTNG_TRACE_CHUNK_STATUS_ERROR,
3ff5c5db	73	LTTNG_TRACE_CHUNK_STATUS_NO_FILE,
2c5ff4e4 JG	74	};
	75
	76	enum lttng_trace_chunk_command_type {
	77	LTTNG_TRACE_CHUNK_COMMAND_TYPE_MOVE_TO_COMPLETED = 0,
343defc2 MD	78	LTTNG_TRACE_CHUNK_COMMAND_TYPE_NO_OPERATION = 1,
	79	LTTNG_TRACE_CHUNK_COMMAND_TYPE_DELETE = 2,
	80	LTTNG_TRACE_CHUNK_COMMAND_TYPE_MAX,
2c5ff4e4 JG	81	};
	82
	83	LTTNG_HIDDEN
	84	struct lttng_trace_chunk *lttng_trace_chunk_create_anonymous(void);
	85
	86	LTTNG_HIDDEN
	87	struct lttng_trace_chunk *lttng_trace_chunk_create(
	88	uint64_t chunk_id,
a7ceb342 MD	89	time_t chunk_creation_time,
a7ceb342 MD	90	const char *path);
2c5ff4e4	91
b2621f79 JG	92	LTTNG_HIDDEN
	93	void lttng_trace_chunk_set_fd_tracker(struct lttng_trace_chunk *chunk,
	94	struct fd_tracker *fd_tracker);
	95
1a414e3a JG	96	/*
	97	* Copy a trace chunk. The copy that is returned is always a _user_
	98	* mode chunk even if the source chunk was an _owner_ as there can never be
	99	* two _owners_ of the same trace output.
	100	*/
	101	LTTNG_HIDDEN
	102	struct lttng_trace_chunk *lttng_trace_chunk_copy(
	103	struct lttng_trace_chunk *source_chunk);
	104
2c5ff4e4 JG	105	LTTNG_HIDDEN
	106	enum lttng_trace_chunk_status lttng_trace_chunk_get_id(
	107	struct lttng_trace_chunk chunk, uint64_t id);
	108
	109	LTTNG_HIDDEN
	110	enum lttng_trace_chunk_status lttng_trace_chunk_get_creation_timestamp(
	111	struct lttng_trace_chunk chunk, time_t creation_ts);
	112
	113	LTTNG_HIDDEN
	114	enum lttng_trace_chunk_status lttng_trace_chunk_get_close_timestamp(
	115	struct lttng_trace_chunk chunk, time_t close_ts);
	116
	117	LTTNG_HIDDEN
	118	enum lttng_trace_chunk_status lttng_trace_chunk_set_close_timestamp(
	119	struct lttng_trace_chunk *chunk, time_t close_ts);
	120
	121	LTTNG_HIDDEN
	122	enum lttng_trace_chunk_status lttng_trace_chunk_get_name(
	123	struct lttng_trace_chunk chunk, const char *name,
913a542b	124	bool *name_overridden);
2c5ff4e4	125
0e2d816a MD	126	LTTNG_HIDDEN
	127	bool lttng_trace_chunk_get_name_overridden(struct lttng_trace_chunk *chunk);
	128
2c5ff4e4 JG	129	LTTNG_HIDDEN
	130	enum lttng_trace_chunk_status lttng_trace_chunk_override_name(
	131	struct lttng_trace_chunk chunk, const char name);
	132
a7ceb342 MD	133	LTTNG_HIDDEN
	134	enum lttng_trace_chunk_status lttng_trace_chunk_rename_path(
	135	struct lttng_trace_chunk chunk, const char path);
	136
2c5ff4e4 JG	137	LTTNG_HIDDEN
	138	enum lttng_trace_chunk_status lttng_trace_chunk_get_credentials(
	139	struct lttng_trace_chunk *chunk,
	140	struct lttng_credentials *credentials);
	141
	142	LTTNG_HIDDEN
	143	enum lttng_trace_chunk_status lttng_trace_chunk_set_credentials(
	144	struct lttng_trace_chunk *chunk,
	145	const struct lttng_credentials *credentials);
	146
	147	LTTNG_HIDDEN
	148	enum lttng_trace_chunk_status lttng_trace_chunk_set_credentials_current_user(
	149	struct lttng_trace_chunk *chunk);
	150
2c5ff4e4 JG	151	LTTNG_HIDDEN
	152	enum lttng_trace_chunk_status lttng_trace_chunk_set_as_owner(
	153	struct lttng_trace_chunk *chunk,
	154	struct lttng_directory_handle *session_output_directory);
	155
2c5ff4e4 JG	156	LTTNG_HIDDEN
	157	enum lttng_trace_chunk_status lttng_trace_chunk_set_as_user(
	158	struct lttng_trace_chunk *chunk,
	159	struct lttng_directory_handle *chunk_directory);
	160
7ceefac4 JG	161	LTTNG_HIDDEN
	162	enum lttng_trace_chunk_status
	163	lttng_trace_chunk_get_session_output_directory_handle(
	164	struct lttng_trace_chunk *chunk,
	165	struct lttng_directory_handle **handle);
	166
2c5ff4e4	167	LTTNG_HIDDEN
cbf53d23	168	enum lttng_trace_chunk_status lttng_trace_chunk_borrow_chunk_directory_handle(
2c5ff4e4 JG	169	struct lttng_trace_chunk *chunk,
	170	const struct lttng_directory_handle **handle);
	171
	172	LTTNG_HIDDEN
	173	enum lttng_trace_chunk_status lttng_trace_chunk_create_subdirectory(
	174	struct lttng_trace_chunk *chunk,
	175	const char *subdirectory_path);
	176
	177	LTTNG_HIDDEN
	178	enum lttng_trace_chunk_status lttng_trace_chunk_open_file(
8bb66c3c JG	179	struct lttng_trace_chunk *chunk,
	180	const char *filename,
	181	int flags,
	182	mode_t mode,
	183	int *out_fd,
	184	bool expect_no_file);
	185
	186	LTTNG_HIDDEN
	187	enum lttng_trace_chunk_status lttng_trace_chunk_open_fs_handle(
	188	struct lttng_trace_chunk *chunk,
	189	const char *filename,
	190	int flags,
	191	mode_t mode,
	192	struct fs_handle **out_handle,
	193	bool expect_no_file);
2c5ff4e4 JG	194
	195	LTTNG_HIDDEN
	196	int lttng_trace_chunk_unlink_file(struct lttng_trace_chunk *chunk,
	197	const char *filename);
	198
bbc4768c JG	199	LTTNG_HIDDEN
	200	enum lttng_trace_chunk_status lttng_trace_chunk_get_close_command(
	201	struct lttng_trace_chunk *chunk,
	202	enum lttng_trace_chunk_command_type *command_type);
	203
2c5ff4e4 JG	204	LTTNG_HIDDEN
	205	enum lttng_trace_chunk_status lttng_trace_chunk_set_close_command(
	206	struct lttng_trace_chunk *chunk,
	207	enum lttng_trace_chunk_command_type command_type);
	208
bbc4768c JG	209	LTTNG_HIDDEN
	210	const char *lttng_trace_chunk_command_type_get_name(
	211	enum lttng_trace_chunk_command_type command);
	212
2c5ff4e4 JG	213	/* Returns true on success. */
	214	LTTNG_HIDDEN
	215	bool lttng_trace_chunk_get(struct lttng_trace_chunk *chunk);
	216
	217	LTTNG_HIDDEN
	218	void lttng_trace_chunk_put(struct lttng_trace_chunk *chunk);
	219
	220	#endif /* LTTNG_TRACE_CHUNK_H */