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

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

#ifndef FD_HANDLE_H
#define FD_HANDLE_H

#include <common/macros.h>

/*
 * Wrapper around a file descriptor providing reference counting semantics.
 *
 * An fd_handle will close() the underlying file descriptor when its reference
 * count reaches zero.
 */
struct fd_handle;

/* Create a file descriptor handle. */
struct fd_handle *fd_handle_create(int fd);

/* Acquire reference to a file descriptor handle. */
void fd_handle_get(struct fd_handle *handle);

/* Release reference to a file descriptor handle. */
void fd_handle_put(struct fd_handle *handle);

/*
 * Return the underlying file descriptor of a file descriptor handle.
 *
 * This function can't fail.
 */
int fd_handle_get_fd(struct fd_handle *handle);

/*
 * Obtain a copy of a file descriptor handle.
 *
 * On success, the caller becomes the sole owner of the returned file descriptor
 * handle. The underlying file descriptor is duplicated using dup(). Refer to
 * the system documentation for the semantics of dup() for this particular file
 * descriptor type.
 */
struct fd_handle *fd_handle_copy(const struct fd_handle *handle);

#endif /* FS_HANDLE_H */
Commit	Line	Data
dd1bac00 JG	1	/*
	2	* Copyright (C) 2020 Jérémie Galarneau <jeremie.galarneau@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef FD_HANDLE_H
	9	#define FD_HANDLE_H
	10
	11	#include <common/macros.h>
	12
	13	/*
	14	* Wrapper around a file descriptor providing reference counting semantics.
	15	*
	16	* An fd_handle will close() the underlying file descriptor when its reference
	17	* count reaches zero.
	18	*/
	19	struct fd_handle;
	20
	21	/* Create a file descriptor handle. */
dd1bac00 JG	22	struct fd_handle *fd_handle_create(int fd);
	23
	24	/* Acquire reference to a file descriptor handle. */
dd1bac00 JG	25	void fd_handle_get(struct fd_handle *handle);
	26
	27	/* Release reference to a file descriptor handle. */
dd1bac00 JG	28	void fd_handle_put(struct fd_handle *handle);
	29
	30	/*
	31	* Return the underlying file descriptor of a file descriptor handle.
	32	*
	33	* This function can't fail.
	34	*/
dd1bac00 JG	35	int fd_handle_get_fd(struct fd_handle *handle);
	36
	37	/*
	38	* Obtain a copy of a file descriptor handle.
	39	*
	40	* On success, the caller becomes the sole owner of the returned file descriptor
	41	* handle. The underlying file descriptor is duplicated using dup(). Refer to
	42	* the system documentation for the semantics of dup() for this particular file
	43	* descriptor type.
	44	*/
dd1bac00 JG	45	struct fd_handle fd_handle_copy(const struct fd_handle handle);
	46
	47	#endif /* FS_HANDLE_H */