src/common/fd-handle.h

   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. */
  22 struct fd_handle *fd_handle_create(int fd);
  23
  24 /* Acquire reference to a file descriptor handle. */
  25 void fd_handle_get(struct fd_handle *handle);
  26
  27 /* Release reference to a file descriptor handle. */
  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  */
  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  */
  45 struct fd_handle *fd_handle_copy(const struct fd_handle *handle);
  46
  47 #endif /* FS_HANDLE_H */