trackers: change error code from "pid" to "id"
[lttng-tools.git] / include / lttng / clear-handle.h
1 /*
2 * Copyright (C) 2019 - Jérémie Galarneau <jeremie.galarneau@efficios.com>
3 * Copyright (C) 2019 - Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
4 *
5 * This library is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU Lesser General Public License, version 2.1 only,
7 * as published by the Free Software Foundation.
8 *
9 * This library is distributed in the hope that it will be useful, but WITHOUT
10 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
11 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License
12 * for more details.
13 *
14 * You should have received a copy of the GNU Lesser General Public License
15 * along with this library; if not, write to the Free Software Foundation,
16 * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
17 */
18
19 #ifndef LTTNG_CLEAR_HANDLE_H
20 #define LTTNG_CLEAR_HANDLE_H
21
22 #include <lttng/lttng-error.h>
23
24 #ifdef __cplusplus
25 extern "C" {
26 #endif
27
28 /*
29 * Handle used to represent a specific instance of session clear
30 * operation.
31 */
32 struct lttng_clear_handle;
33
34 /*
35 * Negative values indicate errors. Values >= 0 indicate success.
36 */
37 enum lttng_clear_handle_status {
38 LTTNG_CLEAR_HANDLE_STATUS_ERROR = -2,
39 LTTNG_CLEAR_HANDLE_STATUS_INVALID = -1,
40 LTTNG_CLEAR_HANDLE_STATUS_OK = 0,
41 LTTNG_CLEAR_HANDLE_STATUS_COMPLETED = 1,
42 LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT = 2,
43 };
44
45 /*
46 * Destroy an lttng_clear_handle.
47 * The handle should be discarded after this call.
48 */
49 extern void lttng_clear_handle_destroy(struct lttng_clear_handle *handle);
50
51 /*
52 * Wait for a session clear operation to complete.
53 *
54 * A negative timeout_ms value can be used to wait indefinitely.
55 *
56 * Returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED if the session clear
57 * operation was completed. LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT is returned
58 * to indicate that the wait timed out.
59 * On error, one of the negative lttng_clear_handle_status is returned.
60 *
61 * Note: This function returning a success status does not mean that
62 * the clear operation itself succeeded; it indicates that the _wait_
63 * operation completed successfully.
64 */
65 extern enum lttng_clear_handle_status
66 lttng_clear_handle_wait_for_completion(
67 struct lttng_clear_handle *handle, int timeout_ms);
68
69 /*
70 * Get the result of a session clear operation.
71 *
72 * This function must be used on a clear handle which was successfully waited
73 * on.
74 *
75 * Returns LTTNG_CLEAR_HANDLE_STATUS_OK if the result of the session
76 * clear operation could be obtained. Check the value of 'result' to
77 * determine if the session clear operation completed successfully or not.
78 *
79 * On error, one of the negative lttng_clear_handle_status is returned.
80 * Returns LTTNG_CLEAR_HANDLE_STATUS_INVALID if the clear operation
81 * was not waited-on using the handle or if the arguments of the function are
82 * invalid (e.g. NULL).
83 */
84 extern enum lttng_clear_handle_status
85 lttng_clear_handle_get_result(
86 const struct lttng_clear_handle *handle,
87 enum lttng_error_code *result);
88
89 #endif /* LTTNG_CLEAR_HANDLE_H */
This page took 0.046993 seconds and 4 git commands to generate.