[lttng-tools.git] / src / common / fs-handle.h

/*
 * Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef FS_HANDLE_H
#define FS_HANDLE_H

#include <common/macros.h>
#include <stdio.h>

struct fs_handle;

/*
 * Marks the handle as the most recently used and marks the 'fd' as
 * "in-use". This prevents the tracker from recycling the underlying
 * file descriptor while it is actively being used by a thread.
 *
 * Don't forget that the tracker may be initiating an fd 'suspension'
 * from another thread as the need to free an fd slot may arise from any
 * thread within the daemon.
 *
 * Note that a restorable fd should never be held for longer than
 * strictly necessary (e.g. the duration of a syscall()).
 *
 * Returns the fd on success, otherwise a negative value may be returned
 * if the restoration of the fd failed.
 */
LTTNG_HIDDEN
int fs_handle_get_fd(struct fs_handle *handle);

/*
 * Used by the caller to signal that it is no longer using the underlying fd and
 * that it may be safely suspended.
 */
LTTNG_HIDDEN
void fs_handle_put_fd(struct fs_handle *handle);

/*
 * Unlink the file associated to an fs_handle. Note that the unlink
 * operation will not be performed immediately. It will only be performed
 * once all references to the underlying file (through other fs_handle objects)
 * have been released.
 *
 * However, note that the file will be renamed so as to provide the observable
 * effect of an unlink(), that is removing a name from the filesystem.
 *
 * Returns 0 on success, otherwise a negative value will be returned
 * if the operation failed.
 */
LTTNG_HIDDEN
int fs_handle_unlink(struct fs_handle *handle);

/*
 * Frees the handle and discards the underlying fd.
 */
LTTNG_HIDDEN
int fs_handle_close(struct fs_handle *handle);

LTTNG_HIDDEN
ssize_t fs_handle_read(struct fs_handle *handle, void *buf, size_t count);

LTTNG_HIDDEN
ssize_t fs_handle_write(struct fs_handle *handle, const void *buf, size_t count);

LTTNG_HIDDEN
int fs_handle_truncate(struct fs_handle *handle, off_t offset);

LTTNG_HIDDEN
off_t fs_handle_seek(struct fs_handle *handle, off_t offset, int whence);

#endif /* FS_HANDLE_H */
Commit	Line	Data
f5ea0241	1	/*
ab5be9fa	2	* Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
f5ea0241	3	*
ab5be9fa	4	* SPDX-License-Identifier: LGPL-2.1-only
f5ea0241	5	*
f5ea0241 JG	6	*/
	7
	8	#ifndef FS_HANDLE_H
	9	#define FS_HANDLE_H
	10
	11	#include <common/macros.h>
8bb66c3c	12	#include <stdio.h>
f5ea0241 JG	13
	14	struct fs_handle;
	15
	16	/*
	17	* Marks the handle as the most recently used and marks the 'fd' as
	18	* "in-use". This prevents the tracker from recycling the underlying
	19	* file descriptor while it is actively being used by a thread.
	20	*
	21	* Don't forget that the tracker may be initiating an fd 'suspension'
	22	* from another thread as the need to free an fd slot may arise from any
	23	* thread within the daemon.
	24	*
	25	* Note that a restorable fd should never be held for longer than
	26	* strictly necessary (e.g. the duration of a syscall()).
	27	*
	28	* Returns the fd on success, otherwise a negative value may be returned
	29	* if the restoration of the fd failed.
	30	*/
	31	LTTNG_HIDDEN
	32	int fs_handle_get_fd(struct fs_handle *handle);
	33
	34	/*
	35	* Used by the caller to signal that it is no longer using the underlying fd and
	36	* that it may be safely suspended.
	37	*/
	38	LTTNG_HIDDEN
	39	void fs_handle_put_fd(struct fs_handle *handle);
	40
	41	/*
	42	* Unlink the file associated to an fs_handle. Note that the unlink
	43	* operation will not be performed immediately. It will only be performed
	44	* once all references to the underlying file (through other fs_handle objects)
	45	* have been released.
	46	*
	47	* However, note that the file will be renamed so as to provide the observable
	48	* effect of an unlink(), that is removing a name from the filesystem.
	49	*
	50	* Returns 0 on success, otherwise a negative value will be returned
	51	* if the operation failed.
	52	*/
	53	LTTNG_HIDDEN
	54	int fs_handle_unlink(struct fs_handle *handle);
	55
	56	/*
	57	* Frees the handle and discards the underlying fd.
	58	*/
	59	LTTNG_HIDDEN
	60	int fs_handle_close(struct fs_handle *handle);
	61
8bb66c3c JG	62	LTTNG_HIDDEN
	63	ssize_t fs_handle_read(struct fs_handle handle, void buf, size_t count);
	64
	65	LTTNG_HIDDEN
	66	ssize_t fs_handle_write(struct fs_handle handle, const void buf, size_t count);
	67
	68	LTTNG_HIDDEN
	69	int fs_handle_truncate(struct fs_handle *handle, off_t offset);
	70
	71	LTTNG_HIDDEN
3e778ab0	72	off_t fs_handle_seek(struct fs_handle *handle, off_t offset, int whence);
8bb66c3c	73
f5ea0241	74	#endif /* FS_HANDLE_H */