Recording session clearing API

Collaboration diagram for Recording session clearing API:

Data Structures
struct	lttng_clear_handle
	Recording session clearing handle (opaque type). More...

Enumerations
enum	lttng_clear_handle_status {   LTTNG_CLEAR_HANDLE_STATUS_OK , LTTNG_CLEAR_HANDLE_STATUS_COMPLETED , LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT , LTTNG_CLEAR_HANDLE_STATUS_INVALID ,   LTTNG_CLEAR_HANDLE_STATUS_ERROR }
	Return type of recording session clearing handle functions. More...

Functions
void	lttng_clear_handle_destroy (struct lttng_clear_handle *handle)
	Destroys the recording session clearing handle handle.
enum lttng_clear_handle_status	lttng_clear_handle_get_result (const struct lttng_clear_handle *handle, enum lttng_error_code *result)
	Sets *result to the result of the recording session clearing operation identified by handle.
enum lttng_clear_handle_status	lttng_clear_handle_wait_for_completion (struct lttng_clear_handle *handle, int timeout_ms)
	Waits for the recording session clearing operation identified by handle to complete.
enum lttng_error_code	lttng_clear_session (const char *session_name, struct lttng_clear_handle **handle)
	Initiates a clearing operation of the recording session named session_name.

Detailed Description

This API makes it possible to clear a recording session, that is, to delete the contents of its tracing buffers and/or of all its local and streamed trace data.

To clear a recording session:

1. Call lttng_clear_session(), passing the name of the recording session to clear.

   This function initiates a clearing operation, returning immediately.

   This function can set a pointer to a clearing handle so that you can wait for the completion of the operation. Without such a handle, you can't know when the clearing operation completes and whether or not it does successfully.

2. If you have a clearing handle from step 1, then:
   1. Call lttng_clear_handle_wait_for_completion() to wait for the completion of the clearing operation.
   2. Call lttng_clear_handle_get_result() to get whether or not the clearing operation successfully completed.
   3. Destroy the clearing handle with lttng_clear_handle_destroy().

See also

lttng-clear(1)

Enumeration Type Documentation

lttng_clear_handle_status

enum lttng_clear_handle_status

Return type of recording session clearing handle functions.

Error status enumerators have a negative value.

Enumerator
LTTNG_CLEAR_HANDLE_STATUS_OK	Success.
LTTNG_CLEAR_HANDLE_STATUS_COMPLETED	Recording session clearing operation completed.
LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT	Timeout reached.
LTTNG_CLEAR_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_CLEAR_HANDLE_STATUS_ERROR	Other error.

Function Documentation

lttng_clear_handle_destroy()

void lttng_clear_handle_destroy ( struct lttng_clear_handle *  handle )

extern

Destroys the recording session clearing handle handle.

Parameters

[in]

handle

Recording session clearing handle to destroy. May be NULL.

lttng_clear_handle_get_result()

enum lttng_clear_handle_status lttng_clear_handle_get_result ( const struct lttng_clear_handle *  handle, enum lttng_error_code *  result  )

extern

Sets *result to the result of the recording session clearing operation identified by handle.

You must successfully wait for the completion of the recording session clearing operation identified by handle with lttng_clear_handle_wait_for_completion() before you call this function.

On success, *result is LTTNG_OK if the clearing operation was successful.

Parameters

[in]	handle	Handle of the recording session clearing operation of which to get the result.
[out]	result	On success, this function sets *result to the result of the recording session clearing operation identified by handle. *result is LTTNG_OK if the clearing operation was successful.

Return values

LTTNG_CLEAR_HANDLE_STATUS_OK	Success: *result is the result of the recording session clearing operation identified by handle.
LTTNG_CLEAR_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_CLEAR_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.
• You successfully waited for the completion of the recording session clearing operation identified by handle with lttng_clear_handle_wait_for_completion().
• result is not NULL.

See also

lttng_clear_handle_wait_for_completion() – Waits for a recording session clearing operation to complete.

lttng_clear_handle_wait_for_completion()

enum lttng_clear_handle_status lttng_clear_handle_wait_for_completion ( struct lttng_clear_handle *  handle, int  timeout_ms  )

extern

Waits for the recording session clearing operation identified by handle to complete.

If this function returns LTTNG_CLEAR_HANDLE_STATUS_COMPLETED, then the recording session clearing operation identified by handle completed. This doesn't mean, however, that the clearing operation itself succeeded; use lttng_clear_handle_get_result() to know this.

Parameters

[in]	handle	Recording session clearing handle which identifies the clearing operation of which to wait for completion.
[in]	timeout_ms	Maximum time (milliseconds) to wait for the completion of the recording session clearing operation identified by handle before returning LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT, or -1 to wait indefinitely.

Return values

LTTNG_CLEAR_HANDLE_STATUS_COMPLETED	The recording session clearing operation identified by handle completed (with or without success).
LTTNG_CLEAR_HANDLE_STATUS_INVALID	Unsatisfied precondition.
LTTNG_CLEAR_HANDLE_STATUS_TIMEOUT	The function waited for the completion of the recording session clearing operation for more than timeout_ms ms.
LTTNG_CLEAR_HANDLE_STATUS_ERROR	Other error.

Precondition

• handle is not NULL.

See also

lttng_clear_handle_get_result() – Returns whether or not a recording session clearing operation succeeded.

lttng_clear_session()

enum lttng_error_code lttng_clear_session ( const char *  session_name, struct lttng_clear_handle **  handle  )

extern

Initiates a clearing operation of the recording session named session_name.

Depending on the mode of the recording session RS named session_name, the clearing operation attempts to:

Local

Network streaming

Delete the contents of the recording buffers of RS.

Delete the local/remote data stream files of RS.

Snapshot

Delete the contents of the recording buffers of RS.

LTTng doesn't touch prior snapshots of RS.

Live

Delete the contents of the recording buffers of RS.

Delete the remote data stream files of RS.

Any active live reader currently reading a data stream packet may continue to read said packet completely.

In all modes, the clearing operation also resets to 0 the values of all the maps of all the map channels of RS, and resets every value overflow flag to false. It does not remove keys from maps: it only resets their values.

The clearing operation which this function initiates, if successful, guarantees that any trace data which LTTng produced before you call this function won't be part of any trace, except:

• Preexisting recording session snapshots.
• Preexisting trace chunk archives.

It's possible that trace data which LTTng produces while you're calling this function makes it to a trace.

Use *handle to wait for the completion of the recording session clearing operation.

Parameters

[in]	session_name	Name of the recording session to clear.
[out]	handle	On success, this function sets *handle to a handle which identifies this recording session clearing operation. May be NULL. Wait for the completion of this clearing operation with lttng_clear_handle_wait_for_completion(). Destroy *handle with lttng_clear_handle_destroy().

Returns

LTTNG_OK on success, or another enumerator otherwise.

Notable return values:

LTTNG_ERR_CLEAR_RELAY_DISALLOWED	The relay daemon doesn't allow recording session clearing operations.
LTTNG_ERR_CLEAR_NOT_AVAILABLE_RELAY	The relay daemon doesn't support the recording session clearing operation.
LTTNG_ERR_CLEAR_FAIL_CONSUMER	A consumer daemon failed to clear the recording session named session_name.

Precondition

• liblttng-ctl can connect to a session daemon.
• session_name is not NULL.
• session_name names an accessible recording session within the connected session daemon.
• No clearing operation is in progress for the recording session named session_name.