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 #include <stdio.h>
  23
  24 struct fs_handle;
  25
  26 /*
  27  * Marks the handle as the most recently used and marks the 'fd' as
  28  * "in-use". This prevents the tracker from recycling the underlying
  29  * file descriptor while it is actively being used by a thread.
  30  *
  31  * Don't forget that the tracker may be initiating an fd 'suspension'
  32  * from another thread as the need to free an fd slot may arise from any
  33  * thread within the daemon.
  34  *
  35  * Note that a restorable fd should never be held for longer than
  36  * strictly necessary (e.g. the duration of a syscall()).
  37  *
  38  * Returns the fd on success, otherwise a negative value may be returned
  39  * if the restoration of the fd failed.
  40  */
  41 LTTNG_HIDDEN
  42 int fs_handle_get_fd(struct fs_handle *handle);
  43
  44 /*
  45  * Used by the caller to signal that it is no longer using the underlying fd and
  46  * that it may be safely suspended.
  47  */
  48 LTTNG_HIDDEN
  49 void fs_handle_put_fd(struct fs_handle *handle);
  50
  51 /*
  52  * Unlink the file associated to an fs_handle. Note that the unlink
  53  * operation will not be performed immediately. It will only be performed
  54  * once all references to the underlying file (through other fs_handle objects)
  55  * have been released.
  56  *
  57  * However, note that the file will be renamed so as to provide the observable
  58  * effect of an unlink(), that is removing a name from the filesystem.
  59  *
  60  * Returns 0 on success, otherwise a negative value will be returned
  61  * if the operation failed.
  62  */
  63 LTTNG_HIDDEN
  64 int fs_handle_unlink(struct fs_handle *handle);
  65
  66 /*
  67  * Frees the handle and discards the underlying fd.
  68  */
  69 LTTNG_HIDDEN
  70 int fs_handle_close(struct fs_handle *handle);
  71
  72 LTTNG_HIDDEN
  73 ssize_t fs_handle_read(struct fs_handle *handle, void *buf, size_t count);
  74
  75 LTTNG_HIDDEN
  76 ssize_t fs_handle_write(struct fs_handle *handle, const void *buf, size_t count);
  77
  78 LTTNG_HIDDEN
  79 int fs_handle_truncate(struct fs_handle *handle, off_t offset);
  80
  81 LTTNG_HIDDEN
  82 int fs_handle_seek(struct fs_handle *handle, off_t offset, int whence);
  83
  84 #endif /* FS_HANDLE_H */