Commit | Line | Data |
---|---|---|
b178f53e | 1 | /* |
ab5be9fa | 2 | * Copyright (C) 2019 Jérémie Galarneau <jeremie.galarneau@efficios.com> |
b178f53e | 3 | * |
ab5be9fa | 4 | * SPDX-License-Identifier: LGPL-2.1-only |
b178f53e | 5 | * |
b178f53e JG |
6 | */ |
7 | ||
8 | #ifndef LTTNG_SESSION_DESCRIPTOR_H | |
9 | #define LTTNG_SESSION_DESCRIPTOR_H | |
10 | ||
11 | #ifdef __cplusplus | |
12 | extern "C" { | |
13 | #endif | |
14 | ||
048f01ef PP |
15 | #include <lttng/lttng-export.h> |
16 | ||
17 | /*! | |
18 | @addtogroup api_session_descr | |
19 | @{ | |
20 | */ | |
21 | ||
22 | /*! | |
23 | @struct lttng_session_descriptor | |
24 | ||
25 | @brief | |
26 | Recording session descriptor (opaque type). | |
27 | */ | |
b178f53e JG |
28 | struct lttng_session_descriptor; |
29 | ||
30 | /* | |
31 | * Session descriptor API. | |
32 | * | |
33 | * A session descriptor is an object describing the immutable configuration | |
34 | * options of an LTTng tracing session. | |
35 | * | |
36 | * When used with the lttng_create_session_ext() function, a session descriptor | |
37 | * allows the creation of a tracing session of the following types: regular, | |
38 | * snapshot, and live. | |
39 | * | |
40 | * Certain parameters can be omitted at the time of creation of a session | |
41 | * descriptor to use default or auto-generated values selected by the | |
42 | * session daemon. For instance, a session's name can be left unspecified, | |
43 | * in which case one that is guaranteed not to clash with pre-existing | |
44 | * sessions will be automatically be generated by the session daemon. | |
45 | * | |
46 | * Most session descriptors can be created in either "no output", local, or | |
47 | * network output modes. The various output modes supported vary by session | |
48 | * type. | |
49 | * | |
50 | * Regular session creation functions and output modes: | |
51 | * * "no output": lttng_session_descriptor_create() | |
52 | * * local: lttng_session_descriptor_local_create() | |
53 | * * network: lttng_session_descriptor_network_create() | |
54 | * | |
55 | * Snapshot session creation functions and output modes: | |
56 | * * "no output": lttng_session_descriptor_snapshot_create() | |
57 | * * local: lttng_session_descriptor_snapshot_local_create() | |
58 | * * network: lttng_session_descriptor_snapshot_network_create() | |
59 | * | |
60 | * Live session creation functions and output modes: | |
61 | * * "no output": lttng_session_descriptor_live_create() | |
62 | * * network: lttng_session_descriptor_live_network_create() | |
63 | * | |
64 | * Local output functions accept a 'path' parameter that must be an absolute | |
65 | * path to which the user has write access. When a local output is automatically | |
66 | * generated, it adopts the form: | |
67 | * $LTTNG_HOME/DEFAULT_TRACE_DIR_NAME/SESSION_NAME-CREATION_TIME | |
68 | * | |
69 | * Where CREATION_TIME is time of the creation of the session on the session | |
70 | * daemon in the form "yyyymmdd-hhmmss". | |
71 | * | |
ca077825 | 72 | * Network output locations can also be auto-generated by leaving the |
b178f53e JG |
73 | * 'control_url' and 'data_url' output parameters unspecified. In such cases, |
74 | * the session daemon will create a default output targeting a relay daemon | |
75 | * at net://127.0.0.1, using the default 'control' and 'data' ports. | |
76 | * | |
ca077825 | 77 | * The format of the 'control_url' and 'data_url' parameters is: |
b178f53e JG |
78 | * NETPROTO://(HOST | IPADDR)[:CTRLPORT[:DATAPORT]][/TRACEPATH] |
79 | * | |
80 | * NETPROTO: Network protocol, amongst: | |
81 | * * net: TCP over IPv4; the default values of 'CTRLPORT' and 'DATAPORT' | |
82 | * are defined at build time of the lttng toolchain. | |
83 | * * net6: TCP over IPv6: same default ports as the 'net' protocol. | |
84 | * * tcp: Same as the 'net' protocol. | |
85 | * * tcp6: Same as the 'net6' protocol. | |
86 | * | |
87 | * HOST | IPADDR: Hostname or IP address (IPv6 address *must* be enclosed | |
88 | * in brackets; see RFC 2732). | |
89 | * | |
90 | * CTRLPORT: Control port. | |
91 | * | |
92 | * DATAPORT: Data port. | |
93 | * | |
94 | * TRACEPATH: Path of trace files on the remote file system. This path is | |
95 | * relative to the base output directory set on the relay daemon | |
96 | * end. | |
97 | * | |
98 | * The 'data_url' parameter is optional: | |
99 | * * This parameter is meaningless for local tracing. | |
100 | * * If 'control_url' is specified and a network protocol is used, the | |
101 | * default data port, and the 'control_url' host will be used. | |
102 | */ | |
103 | ||
048f01ef PP |
104 | /*! |
105 | @brief | |
106 | Return type of recording session descriptor fuctions. | |
107 | ||
108 | Error status enumerators have a negative value. | |
109 | */ | |
b178f53e | 110 | enum lttng_session_descriptor_status { |
048f01ef | 111 | /// Success. |
b178f53e | 112 | LTTNG_SESSION_DESCRIPTOR_STATUS_OK = 0, |
048f01ef PP |
113 | |
114 | /// Unsatisfied precondition. | |
115 | LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID = -1, | |
116 | ||
117 | /// Recording session descriptor property is not set. | |
b178f53e JG |
118 | LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET = 1, |
119 | }; | |
120 | ||
048f01ef PP |
121 | /*! |
122 | @brief | |
123 | Creates a recording session descriptor to create a no-output, | |
124 | \ref api-session-local-mode "local" recording session | |
125 | named \lt_p{session_name}. | |
126 | ||
127 | LTTng won't write any trace data for a recording session created from | |
128 | the returned descriptor. | |
129 | ||
130 | @param[in] session_name | |
131 | @parblock | |
132 | Recording session name. | |
133 | ||
134 | If \c NULL, LTTng automatically generates a recording session name | |
135 | when you call lttng_create_session_ext(). | |
136 | ||
137 | Call lttng_session_descriptor_get_session_name() with the returned | |
138 | recording session descriptor after successfully calling | |
139 | lttng_create_session_ext() to get the generated name. | |
140 | @endparblock | |
141 | ||
142 | @returns | |
143 | @parblock | |
144 | Recording session descriptor on success, or \c NULL on error. | |
145 | ||
146 | Destroy the returned descriptor with | |
147 | lttng_session_descriptor_destroy(). | |
148 | @endparblock | |
149 | ||
150 | @sa lttng_session_descriptor_local_create() -- | |
151 | Creates a recording session descriptor to create a | |
152 | \ref api-session-local-mode "local" recording session with an | |
153 | output. | |
154 | ||
155 | @lt_pre_sess_name_not_auto{session_name} | |
156 | */ | |
4bd69c5f | 157 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 158 | lttng_session_descriptor_create(const char *session_name); |
b178f53e | 159 | |
048f01ef PP |
160 | /*! |
161 | @brief | |
162 | Creates a recording session descriptor to create a | |
163 | \ref api-session-local-mode "local" recording session | |
164 | named \lt_p{session_name}. | |
165 | ||
166 | @param[in] session_name | |
167 | @parblock | |
168 | Recording session name. | |
169 | ||
170 | If \c NULL, LTTng automatically generates a recording session name | |
171 | when you call lttng_create_session_ext(). | |
172 | ||
173 | Call lttng_session_descriptor_get_session_name() with the returned | |
174 | recording session descriptor after successfully calling | |
175 | lttng_create_session_ext() to get the generated name. | |
176 | @endparblock | |
177 | @param[in] trace_dir | |
178 | @parblock | |
179 | Absolute path of the directory containing the traces of the | |
180 | recording session you create from the returned descriptor. | |
181 | ||
182 | If \c NULL, the output directory is, after calling | |
183 | lttng_create_session_ext(), | |
184 | <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>, | |
185 | with: | |
186 | ||
187 | <dl> | |
188 | <dt><code><em>$LTTNG_HOME</em></code> | |
189 | <dd> | |
190 | The value of the \c LTTNG_HOME environment variable, or | |
191 | of the \c HOME environment variable if \c LTTNG_HOME isn't | |
192 | set. | |
193 | ||
194 | <dt><code><em>NAME</em></code> | |
195 | <dd> | |
196 | Recording session name (\lt_p{session_name} if not \c NULL, or | |
197 | an automatically generated name otherwise). | |
198 | ||
199 | <dt><code><em>TS</em></code> | |
200 | <dd> | |
201 | \link lttng_session_get_creation_time() Timestamp of the | |
202 | creation\endlink of the recording session using the | |
203 | <code>YYYYmmdd-HHMMSS</code> form. | |
204 | </dl> | |
205 | @endparblock | |
206 | ||
207 | @returns | |
208 | @parblock | |
209 | Recording session descriptor on success, or \c NULL on error. | |
210 | ||
211 | Destroy the returned descriptor with | |
212 | lttng_session_descriptor_destroy(). | |
213 | @endparblock | |
214 | ||
215 | @lt_pre_sess_name_not_auto{session_name} | |
216 | @pre | |
217 | <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path. | |
218 | ||
219 | @sa lttng_session_descriptor_create() -- | |
220 | Creates a recording session descriptor to create a | |
221 | \ref api-session-local-mode "local" recording session without an | |
222 | output. | |
223 | */ | |
4bd69c5f | 224 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 225 | lttng_session_descriptor_local_create(const char *session_name, const char *trace_dir); |
b178f53e | 226 | |
048f01ef PP |
227 | /*! |
228 | @brief | |
229 | Creates a recording session descriptor to create a | |
230 | \ref api-session-net-mode "network streaming" recording session | |
231 | named \lt_p{session_name}. | |
232 | ||
233 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: | |
234 | ||
235 | <table> | |
236 | <tr> | |
237 | <th>\lt_p{control_url} | |
238 | <th>\lt_p{data_url} | |
239 | <th>Behaviour | |
240 | <tr> | |
241 | <td>\c NULL | |
242 | <td>\c NULL | |
243 | <td> | |
244 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. | |
245 | ||
246 | Use \lt_def_net_data_url as \lt_p{data_url}. | |
247 | <tr> | |
248 | <td>\ref api-session-one-port-url "Single-port output URL" | |
249 | <td>\c NULL | |
250 | <td> | |
251 | Use the protocol, host, and trace directory (if any) of | |
252 | \lt_p{control_url} and the port \lt_def_net_data_port | |
253 | as \lt_p{data_url}. | |
254 | <tr> | |
255 | <td>Single-port output URL | |
256 | <td> | |
257 | Single-port output URL with the exact same protocol, host, | |
258 | and trace directory (if any) as \lt_p{control_url}. | |
259 | <td> | |
260 | Use the specified output URLs. | |
261 | <tr> | |
262 | <td>\ref api-session-two-port-url "Two-port output URL" | |
263 | <td>\c NULL | |
264 | <td> | |
265 | Use the protocol, host, data port, and trace directory (if any) | |
266 | of \lt_p{control_url} as \lt_p{data_url}. | |
267 | </table> | |
268 | ||
269 | @param[in] session_name | |
270 | @parblock | |
271 | Recording session name. | |
272 | ||
273 | If \c NULL, LTTng automatically generates a recording session name | |
274 | when you call lttng_create_session_ext(). | |
275 | ||
276 | Call lttng_session_descriptor_get_session_name() with the returned | |
277 | recording session descriptor after successfully calling | |
278 | lttng_create_session_ext() to get the generated name. | |
279 | @endparblock | |
280 | @param[in] control_url | |
281 | @parblock | |
282 | One of: | |
283 | ||
284 | <dl> | |
285 | <dt>\ref api-session-one-port-url "Single-port output URL" | |
286 | <dd> | |
287 | Indicates where (to which relay daemon; see | |
288 | \lt_man{lttng-relayd,8}) to send the control data. | |
289 | ||
290 | <dt>\ref api-session-two-port-url "Two-port output URL" | |
291 | <dd> | |
292 | Indicates where to send the control \em and trace data. | |
293 | </dl> | |
294 | ||
295 | If \c NULL, this function uses \lt_def_net_url. | |
296 | @endparblock | |
297 | @param[in] data_url | |
298 | @parblock | |
299 | \ref api-session-one-port-url "Single-port output URL" which | |
300 | indicates where to send the trace data. | |
301 | ||
302 | May be <code>NULL</code>: see the table above for the default value | |
303 | depending on \lt_p{control_url}. | |
304 | @endparblock | |
305 | ||
306 | @returns | |
307 | @parblock | |
308 | Recording session descriptor on success, or \c NULL on error. | |
309 | ||
310 | Destroy the returned descriptor with | |
311 | lttng_session_descriptor_destroy(). | |
312 | @endparblock | |
313 | ||
314 | @lt_pre_sess_name_not_auto{session_name} | |
315 | @pre | |
316 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid | |
317 | combinations shown in the table above. | |
318 | */ | |
28f23191 | 319 | LTTNG_EXPORT extern struct lttng_session_descriptor *lttng_session_descriptor_network_create( |
048f01ef | 320 | const char *session_name, const char *control_url, const char *data_url); |
b178f53e | 321 | |
048f01ef PP |
322 | /*! |
323 | @brief | |
324 | Creates a recording session descriptor to create a | |
325 | \ref api-session-snapshot-mode "snapshot" recording session | |
326 | named \lt_p{session_name} without an initial output. | |
327 | ||
328 | A recording session which lttng_create_session_ext() creates from the | |
329 | returned descriptor has no initial snapshot output: you need to either | |
330 | add one with lttng_snapshot_add_output() or provide one when you take a | |
331 | snapshot with lttng_snapshot_record(). | |
332 | ||
333 | @param[in] session_name | |
334 | @parblock | |
335 | Recording session name. | |
336 | ||
337 | If \c NULL, LTTng automatically generates a recording session name | |
338 | when you call lttng_create_session_ext(). | |
339 | ||
340 | Call lttng_session_descriptor_get_session_name() with the returned | |
341 | recording session descriptor after successfully calling | |
342 | lttng_create_session_ext() to get the generated name. | |
343 | @endparblock | |
344 | ||
345 | @returns | |
346 | @parblock | |
347 | Recording session descriptor on success, or \c NULL on error. | |
348 | ||
349 | Destroy the returned descriptor with | |
350 | lttng_session_descriptor_destroy(). | |
351 | @endparblock | |
352 | ||
353 | @lt_pre_sess_name_not_auto{session_name} | |
354 | ||
355 | @sa lttng_session_descriptor_snapshot_local_create() -- | |
356 | Creates a recording session descriptor to create a | |
357 | \ref api-session-snapshot-mode "snapshot" recording session | |
358 | with an initial local output. | |
359 | @sa lttng_session_descriptor_snapshot_network_create() -- | |
360 | Creates a recording session descriptor to create a | |
361 | \ref api-session-snapshot-mode "snapshot" recording session | |
362 | with an initial remote output. | |
363 | */ | |
4bd69c5f | 364 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 365 | lttng_session_descriptor_snapshot_create(const char *session_name); |
b178f53e | 366 | |
048f01ef PP |
367 | /*! |
368 | @brief | |
369 | Creates a recording session descriptor to create a | |
370 | \ref api-session-snapshot-mode "snapshot" recording session | |
371 | named \lt_p{session_name} and having an initial local output. | |
372 | ||
373 | Using the returned descriptor when you call lttng_create_session_ext() | |
374 | to create a snapshot recording session is similar to using a descriptor | |
375 | which lttng_session_descriptor_snapshot_create() returns and calling | |
376 | lttng_snapshot_add_output() after creating the recording session. | |
377 | ||
378 | The name of this initial snapshot output is <code>snapshot-0</code>. | |
379 | ||
380 | @param[in] session_name | |
381 | @parblock | |
382 | Recording session name. | |
383 | ||
384 | If \c NULL, LTTng automatically generates a recording session name | |
385 | when you call lttng_create_session_ext(). | |
386 | ||
387 | Call lttng_session_descriptor_get_session_name() with the returned | |
388 | recording session descriptor after successfully calling | |
389 | lttng_create_session_ext() to get the generated name. | |
390 | @endparblock | |
391 | @param[in] trace_dir | |
392 | @parblock | |
393 | Absolute path of an initial snapshot output. | |
394 | ||
395 | If \c NULL, the snapshot output directory is, after calling | |
396 | lttng_create_session_ext(), | |
397 | <code><em>$LTTNG_HOME</em>/lttng-traces/<em>NAME</em>-<em>TS</em></code>, | |
398 | with: | |
399 | ||
400 | <dl> | |
401 | <dt><code><em>$LTTNG_HOME</em></code> | |
402 | <dd> | |
403 | The value of the \c LTTNG_HOME environment variable, or | |
404 | of the \c HOME environment variable if \c LTTNG_HOME isn't | |
405 | set. | |
406 | ||
407 | <dt><code><em>NAME</em></code> | |
408 | <dd> | |
409 | Recording session name (\lt_p{session_name} if not \c NULL, or | |
410 | an automatically generated name otherwise). | |
411 | ||
412 | <dt><code><em>TS</em></code> | |
413 | <dd> | |
414 | \link lttng_session_get_creation_time() Timestamp of the | |
415 | creation\endlink of the recording session using the | |
416 | <code>YYYYmmdd-HHMMSS</code> form. | |
417 | </dl> | |
418 | @endparblock | |
419 | ||
420 | @returns | |
421 | @parblock | |
422 | Recording session descriptor on success, or \c NULL on error. | |
423 | ||
424 | Destroy the returned descriptor with | |
425 | lttng_session_descriptor_destroy(). | |
426 | @endparblock | |
427 | ||
428 | @lt_pre_sess_name_not_auto{session_name} | |
429 | @pre | |
430 | <strong>If not \c NULL</strong>, \lt_p{trace_dir} is a valid path. | |
431 | ||
432 | @sa lttng_session_descriptor_snapshot_create() -- | |
433 | Creates a recording session descriptor to create a | |
434 | \ref api-session-snapshot-mode "snapshot" recording session | |
435 | without an initial output. | |
436 | @sa lttng_session_descriptor_snapshot_network_create() -- | |
437 | Creates a recording session descriptor to create a | |
438 | \ref api-session-snapshot-mode "snapshot" recording session | |
439 | with an initial remote output. | |
440 | */ | |
4bd69c5f | 441 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 442 | lttng_session_descriptor_snapshot_local_create(const char *session_name, const char *trace_dir); |
b178f53e | 443 | |
048f01ef PP |
444 | /*! |
445 | @brief | |
446 | Creates a recording session descriptor to create a | |
447 | \ref api-session-snapshot-mode "snapshot" recording session | |
448 | named \lt_p{session_name} and having an initial remote output. | |
449 | ||
450 | Using the returned descriptor when you call lttng_create_session_ext() | |
451 | to create a snapshot recording session is similar to using a descriptor | |
452 | which lttng_session_descriptor_snapshot_create() returns and calling | |
453 | lttng_snapshot_add_output() after creating the recording session. | |
454 | ||
455 | The name of this initial snapshot output is <code>snapshot-0</code>. | |
456 | ||
457 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: | |
458 | ||
459 | <table> | |
460 | <tr> | |
461 | <th>\lt_p{control_url} | |
462 | <th>\lt_p{data_url} | |
463 | <th>Behaviour | |
464 | <tr> | |
465 | <td>\c NULL | |
466 | <td>\c NULL | |
467 | <td> | |
468 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. | |
469 | ||
470 | Use \lt_def_net_data_url as \lt_p{data_url}. | |
471 | <tr> | |
472 | <td>\ref api-session-one-port-url "Single-port output URL" | |
473 | <td>\c NULL | |
474 | <td> | |
475 | Use the protocol, host, and trace directory (if any) of | |
476 | \lt_p{control_url} and the port \lt_def_net_data_port | |
477 | as \lt_p{data_url}. | |
478 | <tr> | |
479 | <td>Single-port output URL | |
480 | <td> | |
481 | Single-port output URL with the exact same protocol, host, | |
482 | and trace directory (if any) as \lt_p{control_url}. | |
483 | <td> | |
484 | Use the specified output URLs. | |
485 | <tr> | |
486 | <td>\ref api-session-two-port-url "Two-port output URL" | |
487 | <td>\c NULL | |
488 | <td> | |
489 | Use the protocol, host, data port, and trace directory (if any) | |
490 | of \lt_p{control_url} as \lt_p{data_url}. | |
491 | </table> | |
492 | ||
493 | @param[in] session_name | |
494 | @parblock | |
495 | Recording session name. | |
496 | ||
497 | If \c NULL, LTTng automatically generates a recording session name | |
498 | when you call lttng_create_session_ext(). | |
499 | ||
500 | Call lttng_session_descriptor_get_session_name() with the returned | |
501 | recording session descriptor after successfully calling | |
502 | lttng_create_session_ext() to get the generated name. | |
503 | @endparblock | |
504 | @param[in] control_url | |
505 | @parblock | |
506 | Control data URL of an initial snapshot output. | |
507 | ||
508 | One of: | |
509 | ||
510 | <dl> | |
511 | <dt>\ref api-session-one-port-url "Single-port output URL" | |
512 | <dd> | |
513 | Indicates where (to which relay daemon; see | |
514 | \lt_man{lttng-relayd,8}) to send the control data. | |
515 | ||
516 | <dt>\ref api-session-two-port-url "Two-port output URL" | |
517 | <dd> | |
518 | Indicates where to send the control \em and trace data. | |
519 | </dl> | |
520 | ||
521 | If \c NULL, this function uses \lt_def_net_url. | |
522 | @endparblock | |
523 | @param[in] data_url | |
524 | @parblock | |
525 | Trace data URL of an initial snapshot output. | |
526 | ||
527 | \ref api-session-one-port-url "Single-port output URL" which | |
528 | indicates where to send the trace data. | |
529 | ||
530 | May be <code>NULL</code>: see the table above for the default value | |
531 | depending on \lt_p{control_url}. | |
532 | @endparblock | |
533 | ||
534 | @returns | |
535 | @parblock | |
536 | Recording session descriptor on success, or \c NULL on error. | |
537 | ||
538 | Destroy the returned descriptor with | |
539 | lttng_session_descriptor_destroy(). | |
540 | @endparblock | |
541 | ||
542 | @lt_pre_sess_name_not_auto{session_name} | |
543 | @pre | |
544 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid | |
545 | combinations shown in the table above. | |
546 | ||
547 | @sa lttng_session_descriptor_snapshot_create() -- | |
548 | Creates a recording session descriptor to create a | |
549 | \ref api-session-snapshot-mode "snapshot" recording session | |
550 | without an initial output. | |
551 | @sa lttng_session_descriptor_snapshot_local_create() -- | |
552 | Creates a recording session descriptor to create a | |
553 | \ref api-session-snapshot-mode "snapshot" recording session | |
554 | with an initial local output. | |
555 | */ | |
4bd69c5f | 556 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 557 | lttng_session_descriptor_snapshot_network_create(const char *session_name, |
28f23191 JG |
558 | const char *control_url, |
559 | const char *data_url); | |
b178f53e JG |
560 | |
561 | /* | |
048f01ef PP |
562 | * NOTE: Not documented with Doxygen as what lttng_create_session_ext() |
563 | * creates from such a descriptor is useless (a live recording session | |
564 | * without any output). Original documentation follows. | |
565 | * | |
b178f53e JG |
566 | * Create a live session descriptor without an output. |
567 | * | |
568 | * The 'name' parameter can be left NULL to auto-generate a session name. | |
569 | * | |
570 | * The 'live_timer_interval_us' parameter is the live timer's period, specified | |
571 | * in microseconds. | |
572 | * | |
573 | * This parameter can't be 0. There is no default value defined for a live | |
574 | * timer's period. | |
575 | * | |
576 | * Returns an lttng_session_descriptor instance on success, NULL on error. | |
577 | */ | |
4bd69c5f | 578 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
28f23191 | 579 | lttng_session_descriptor_live_create(const char *name, unsigned long long live_timer_interval_us); |
b178f53e | 580 | |
048f01ef PP |
581 | /*! |
582 | @brief | |
583 | Creates a recording session descriptor to create a | |
584 | \ref api-session-live-mode "live" recording session | |
585 | named \lt_p{session_name}. | |
586 | ||
587 | The valid combinations of \lt_p{control_url} and \lt_p{data_url} are: | |
588 | ||
589 | <table> | |
590 | <tr> | |
591 | <th>\lt_p{control_url} | |
592 | <th>\lt_p{data_url} | |
593 | <th>Behaviour | |
594 | <tr> | |
595 | <td>\c NULL | |
596 | <td>\c NULL | |
597 | <td> | |
598 | Use \lt_def_net_ctrl_url as \lt_p{control_url}. | |
599 | ||
600 | Use \lt_def_net_data_url as \lt_p{data_url}. | |
601 | <tr> | |
602 | <td>\ref api-session-one-port-url "Single-port output URL" | |
603 | <td>\c NULL | |
604 | <td> | |
605 | Use the protocol, host, and trace directory (if any) of | |
606 | \lt_p{control_url} and the port \lt_def_net_data_port | |
607 | as \lt_p{data_url}. | |
608 | <tr> | |
609 | <td>Single-port output URL | |
610 | <td> | |
611 | Single-port output URL with the exact same protocol, host, | |
612 | and trace directory (if any) as \lt_p{control_url}. | |
613 | <td> | |
614 | Use the specified output URLs. | |
615 | <tr> | |
616 | <td>\ref api-session-two-port-url "Two-port output URL" | |
617 | <td>\c NULL | |
618 | <td> | |
619 | Use the protocol, host, data port, and trace directory (if any) | |
620 | of \lt_p{control_url} as \lt_p{data_url}. | |
621 | </table> | |
622 | ||
623 | @param[in] session_name | |
624 | @parblock | |
625 | Recording session name. | |
626 | ||
627 | If \c NULL, LTTng automatically generates a recording session name | |
628 | when you call lttng_create_session_ext(). | |
629 | ||
630 | Call lttng_session_descriptor_get_session_name() with the returned | |
631 | recording session descriptor after successfully calling | |
632 | lttng_create_session_ext() to get the generated name. | |
633 | @endparblock | |
634 | @param[in] control_url | |
635 | @parblock | |
636 | One of: | |
637 | ||
638 | <dl> | |
639 | <dt>\ref api-session-one-port-url "Single-port output URL" | |
640 | <dd> | |
641 | Indicates where (to which relay daemon; see | |
642 | \lt_man{lttng-relayd,8}) to send the control data. | |
643 | ||
644 | <dt>\ref api-session-two-port-url "Two-port output URL" | |
645 | <dd> | |
646 | Indicates where to send the control \em and trace data. | |
647 | </dl> | |
648 | ||
649 | If \c NULL, this function uses \lt_def_net_url. | |
650 | @endparblock | |
651 | @param[in] data_url | |
652 | @parblock | |
653 | \ref api-session-one-port-url "Single-port output URL" which | |
654 | indicates where to send the trace data. | |
655 | ||
656 | May be <code>NULL</code>: see the table above for the default value | |
657 | depending on \lt_p{control_url}. | |
658 | @endparblock | |
659 | @param[in] live_timer_period | |
660 | Period (µs) of the \ref api-channel-live-timer "live timers" of all | |
661 | the channels of a recording session which lttng_create_session_ext() | |
662 | creates from the returned descriptor. | |
663 | ||
664 | @returns | |
665 | @parblock | |
666 | Recording session descriptor on success, or \c NULL on error. | |
667 | ||
668 | Destroy the returned descriptor with | |
669 | lttng_session_descriptor_destroy(). | |
670 | @endparblock | |
671 | ||
672 | @lt_pre_sess_name_not_auto{session_name} | |
673 | @pre | |
674 | \lt_p{control_url} and \lt_p{data_url} satisfy one of the valid | |
675 | combinations shown in the table above. | |
676 | @pre | |
677 | \lt_p{live_timer_period} ≥ 1 | |
678 | */ | |
4bd69c5f | 679 | LTTNG_EXPORT extern struct lttng_session_descriptor * |
048f01ef | 680 | lttng_session_descriptor_live_network_create(const char *session_name, |
28f23191 JG |
681 | const char *control_url, |
682 | const char *data_url, | |
048f01ef | 683 | unsigned long long live_timer_period); |
b178f53e JG |
684 | |
685 | /* | |
686 | * Get a session descriptor's session name. | |
687 | * | |
688 | * The 'name' parameter is used as an output parameter and will point to | |
689 | * the session descriptor's session name on success | |
690 | * (LTTNG_SESSION_DESCRIPTOR_STATUS_OK). Its content of is left unspecified | |
691 | * for other return codes. The pointer returned through 'name' is only | |
692 | * guaranteed to remain valid until the next method call on the session | |
693 | * descriptor. | |
694 | * | |
695 | * Returns LTTNG_SESSION_DESCRIPTOR_STATUS_OK on success, | |
696 | * LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID if 'descriptor' or 'name' are | |
697 | * NULL, and LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET if the descriptor's | |
698 | * name parameter is unset. | |
699 | */ | |
048f01ef PP |
700 | |
701 | /*! | |
702 | @brief | |
703 | Sets \lt_p{*session_name} to the name of the recording session | |
704 | which lttng_create_session_ext() created from the recording | |
705 | session descriptor \lt_p{session_descriptor}. | |
706 | ||
707 | Call this function after successfully calling lttng_create_session_ext() | |
708 | when \lt_p{session_descriptor} wasn't created with a specific recording | |
709 | session name to get the automatically generated name of the created | |
710 | recording session. | |
711 | ||
712 | @param[in] session_descriptor | |
713 | Recording session descriptor from which lttng_create_session_ext() | |
714 | previously created the recording session of which to get the name. | |
715 | @param[out] session_name | |
716 | @parblock | |
717 | <strong>On success</strong>, this function sets \lt_p{*session_name} | |
718 | to the name of the recording session which | |
719 | lttng_create_session_ext() previously created from | |
720 | \lt_p{session_descriptor}. | |
721 | ||
722 | \lt_p{session_descriptor} owns \lt_p{*session_name}. | |
723 | ||
724 | \lt_p{*session_name} remains valid until the next recording | |
725 | session descriptor function call with \lt_p{session_descriptor}. | |
726 | @endparblock | |
727 | ||
728 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_OK | |
729 | Success. | |
730 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_INVALID | |
731 | Unsatisfied precondition. | |
732 | @retval #LTTNG_SESSION_DESCRIPTOR_STATUS_UNSET | |
733 | The name property of \lt_p{session_descriptor} is not set. | |
734 | ||
735 | @lt_pre_not_null{session_descriptor} | |
736 | @pre | |
737 | You successfully called lttng_create_session_ext() with | |
738 | \lt_p{session_descriptor}. | |
739 | @lt_pre_not_null{session_name} | |
740 | */ | |
4bd69c5f | 741 | LTTNG_EXPORT extern enum lttng_session_descriptor_status |
048f01ef PP |
742 | lttng_session_descriptor_get_session_name(const struct lttng_session_descriptor *session_descriptor, |
743 | const char **session_name); | |
b178f53e | 744 | |
048f01ef PP |
745 | /*! |
746 | @brief | |
747 | Destroys the recording session descriptor \lt_p{session_descriptor}. | |
748 | ||
749 | @note | |
750 | @parblock | |
751 | This function doesn't destroy the recording session which | |
752 | lttng_create_session_ext() created from \lt_p{session_descriptor}, | |
753 | but only the descriptor itself. | |
754 | ||
755 | Use lttng_destroy_session_ext() to destroy a recording session. | |
756 | @endparblock | |
757 | ||
758 | @param[in] session_descriptor | |
759 | @parblock | |
760 | Recording session descriptor to destroy. | |
761 | ||
762 | May be \c NULL. | |
763 | @endparblock | |
764 | */ | |
28f23191 | 765 | LTTNG_EXPORT extern void |
048f01ef PP |
766 | lttng_session_descriptor_destroy(struct lttng_session_descriptor *session_descriptor); |
767 | ||
768 | /// @} | |
b178f53e JG |
769 | |
770 | #ifdef __cplusplus | |
771 | } | |
772 | #endif | |
773 | ||
774 | #endif /* LTTNG_SESSION_DESCRIPTOR_H */ |