Fix: don't hide EBADF error subbuffer write
[lttng-tools.git] / include / lttng / session.h
CommitLineData
1239a312
DG
1/*
2 * Copyright (C) 2014 - David Goulet <dgoulet@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, version 2.1 only,
6 * as published by the Free Software Foundation.
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 LTTNG_SESSION_H
19#define LTTNG_SESSION_H
20
21#ifdef __cplusplus
22extern "C" {
23#endif
24
b178f53e
JG
25struct lttng_session_descriptor;
26
1239a312
DG
27/*
28 * Basic session information.
29 *
30 * The "enabled" field is only used when listing the sessions which indicate if
31 * it's started or not.
32 *
33 * The structures should be initialized to zero before use.
34 */
35#define LTTNG_SESSION_PADDING1 12
36struct lttng_session {
36d2e35d 37 char name[LTTNG_NAME_MAX];
beede00c
JG
38 /*
39 * Human-readable representation of the trace's destination.
40 * In the case of a local tracing session, a path is provided:
41 * /path/to/the/output
42 *
43 * In the case of a remote (network) tracing session, the string has
44 * the following format:
45 * net://hostname/path:ctrl_port [data: data_port]
46 */
1239a312
DG
47 char path[PATH_MAX];
48 uint32_t enabled; /* enabled/started: 1, disabled/stopped: 0 */
49 uint32_t snapshot_mode;
50 unsigned int live_timer_interval; /* usec */
51
b178f53e
JG
52 union {
53 char padding[LTTNG_SESSION_PADDING1];
54 void *ptr;
55 } extended;
1239a312
DG
56};
57
b178f53e
JG
58/*
59 * Create a session on the session daemon from a session descriptor.
60 *
61 * See the session descriptor API description in session-descriptor.h
62 *
63 * Note that unspecified session descriptor parameters, such as a session's
64 * name, are updated in the session descriptor if the creation of the session
65 * succeeds. This allows users to query the session's auto-generated name
66 * after its creation. Note that other attributes can be queried using the
67 * session listing API.
68 *
69 * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
70 * return codes.
71 */
72extern enum lttng_error_code lttng_create_session_ext(
73 struct lttng_session_descriptor *session_descriptor);
74
1239a312
DG
75/*
76 * Create a tracing session using a name and an optional URL.
77 *
78 * If _url_ is NULL, no consumer is created for the session. The name can't be
79 * NULL here.
80 *
81 * Return 0 on success else a negative LTTng error code.
82 */
83extern int lttng_create_session(const char *name, const char *url);
84
85/*
86 * Create a tracing session that will exclusively be used for snapshot meaning
87 * the session will be in no output mode and every channel enabled for that
88 * session will be set in overwrite mode and in mmap output since splice is not
89 * supported.
90 *
91 * Name can't be NULL. If an url is given, it will be used to create a default
92 * snapshot output using it as a destination. If NULL, no output will be
93 * defined and an add-output call will be needed.
94 *
95 * Return 0 on success else a negative LTTng error code.
96 */
97extern int lttng_create_session_snapshot(const char *name,
98 const char *snapshot_url);
99
100/*
101 * Create a session exclusively used for live reading.
102 *
103 * In this mode, the switch-timer parameter is forced for each UST channel, a
104 * live-switch-timer is enabled for kernel channels, manually setting
105 * switch-timer is forbidden. Synchronization beacons are sent to the relayd,
106 * indexes are sent and metadata is checked for each packet.
107 *
108 * Name can't be NULL. If no URL is given, the default is to send the data to
1aacaae2 109 * net://127.0.0.1. The timer_interval is in usec.
1239a312
DG
110 *
111 * Return 0 on success else a negative LTTng error code.
112 */
113extern int lttng_create_session_live(const char *name, const char *url,
114 unsigned int timer_interval);
115
116/*
117 * Destroy a tracing session.
118 *
119 * The session will not be usable, tracing will be stopped thus buffers will be
120 * flushed.
121 *
e20ee7c2
JD
122 * This call will wait for data availability for each domain of the session,
123 * which can take an arbitrary amount of time. However, when returning the
124 * tracing data is guaranteed to be ready to be read and analyzed.
125 *
126 * lttng_destroy_session_no_wait() may be used if such a guarantee is not
127 * needed.
128 *
1239a312
DG
129 * The name can't be NULL here.
130 *
131 * Return 0 on success else a negative LTTng error code.
132 */
133extern int lttng_destroy_session(const char *name);
134
e20ee7c2
JD
135/*
136 * Behaves exactly like lttng_destroy_session but does not wait for data
137 * availability.
138 */
139extern int lttng_destroy_session_no_wait(const char *name);
140
1239a312
DG
141/*
142 * List all the tracing sessions.
143 *
b178f53e
JG
144 * Return the number of entries of the "lttng_session" array. The caller
145 * must free the returned sessions array directly using free().
146 *
147 * On error, a negative LTTng error code is returned.
1239a312
DG
148 */
149extern int lttng_list_sessions(struct lttng_session **sessions);
150
b178f53e
JG
151/*
152 * Get the creation time of an lttng_session object on the session daemon.
153 *
154 * This function must only be used with lttng_session objects returned
155 * by lttng_list_sessions() or lttng_session_create().
156 *
157 * The creation time returned is a UNIX timestamp; the number of seconds since
158 * Epoch (1970-01-01 00:00:00 +0000 (UTC)).
159 *
160 * Returns LTTNG_OK on success. See lttng-error.h for the meaning of the other
161 * return codes.
162 */
163extern enum lttng_error_code lttng_session_get_creation_time(
164 const struct lttng_session *session, uint64_t *creation_time);
165
d7ba1388
MD
166/*
167 * Set the shared memory path for a session.
168 *
169 * Sets the (optional) file system path where shared memory buffers will
170 * be created for the session. This is useful for buffer extraction on
171 * crash, when used with filesystems like pramfs.
172 *
173 * Return 0 on success else a negative LTTng error code.
174 */
175extern int lttng_set_session_shm_path(const char *session_name,
176 const char *shm_path);
177
ccf10263
MD
178/*
179 * Add PID to session tracker.
180 *
181 * A pid argument >= 0 adds the PID to the session tracker.
182 * A pid argument of -1 means "track all PIDs".
183 *
184 * Return 0 on success else a negative LTTng error code.
185 */
186extern int lttng_track_pid(struct lttng_handle *handle, int pid);
187
188/*
189 * Remove PID from session tracker.
190 *
191 * A pid argument >= 0 removes the PID from the session tracker.
192 * A pid argument of -1 means "untrack all PIDs".
193 *
194 * Return 0 on success else a negative LTTng error code.
195 */
196extern int lttng_untrack_pid(struct lttng_handle *handle, int pid);
197
a5dfbb9d
MD
198/*
199 * List PIDs in the tracker.
200 *
36dc4128
JG
201 * enabled is set to whether the PID tracker is enabled.
202 * pids is set to an allocated array of PIDs currently tracked. On
203 * success, pids must be freed by the caller.
204 * nr_pids is set to the number of entries contained by the pids array.
a5dfbb9d
MD
205 *
206 * Returns 0 on success, else a negative LTTng error code.
207 */
208extern int lttng_list_tracker_pids(struct lttng_handle *handle,
209 int *enabled, int32_t **pids, size_t *nr_pids);
210
1239a312
DG
211#ifdef __cplusplus
212}
213#endif
214
215#endif /* LTTNG_SESSION_H */
This page took 0.058437 seconds and 4 git commands to generate.