src/common/fs-handle.h

   1 /*
   2  * Copyright (C) 2020 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
   3  *
   4  * This library is free software; you can redistribute it and/or modify it
   5  * under the terms of the GNU Lesser General Public License as published by the
   6  * Free Software Foundation; version 2.1 of the License.
   7  *
   8  * This library 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 library; if not, write to the Free Software Foundation,
  15  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA
  16  */
  17
  18 #ifndef FS_HANDLE_H
  19 #define FS_HANDLE_H
  20
  21 #include <common/macros.h>
  22
  23 struct fs_handle;
  24
  25 /*
  26  * Marks the handle as the most recently used and marks the 'fd' as
  27  * "in-use". This prevents the tracker from recycling the underlying
  28  * file descriptor while it is actively being used by a thread.
  29  *
  30  * Don't forget that the tracker may be initiating an fd 'suspension'
  31  * from another thread as the need to free an fd slot may arise from any
  32  * thread within the daemon.
  33  *
  34  * Note that a restorable fd should never be held for longer than
  35  * strictly necessary (e.g. the duration of a syscall()).
  36  *
  37  * Returns the fd on success, otherwise a negative value may be returned
  38  * if the restoration of the fd failed.
  39  */
  40 LTTNG_HIDDEN
  41 int fs_handle_get_fd(struct fs_handle *handle);
  42
  43 /*
  44  * Used by the caller to signal that it is no longer using the underlying fd and
  45  * that it may be safely suspended.
  46  */
  47 LTTNG_HIDDEN
  48 void fs_handle_put_fd(struct fs_handle *handle);
  49
  50 /*
  51  * Unlink the file associated to an fs_handle. Note that the unlink
  52  * operation will not be performed immediately. It will only be performed
  53  * once all references to the underlying file (through other fs_handle objects)
  54  * have been released.
  55  *
  56  * However, note that the file will be renamed so as to provide the observable
  57  * effect of an unlink(), that is removing a name from the filesystem.
  58  *
  59  * Returns 0 on success, otherwise a negative value will be returned
  60  * if the operation failed.
  61  */
  62 LTTNG_HIDDEN
  63 int fs_handle_unlink(struct fs_handle *handle);
  64
  65 /*
  66  * Frees the handle and discards the underlying fd.
  67  */
  68 LTTNG_HIDDEN
  69 int fs_handle_close(struct fs_handle *handle);
  70
  71 #endif /* FS_HANDLE_H */