omp_control_tool (GNU libgomp)

#### 3.13.1 `omp_control_tool` – pass commands to a tool ¶

Description:

  The `omp_control_tool` routine can be used to pass commands to a tool. The values for modifier and arg are specific for the particular tool; for Fortran, arg is NULL. The following predefined values for command are supported by all tools:

  - `omp_control_tool_start`: Request that monitoring is started or resumed; it has no effect if monitoring is already on or was turned off permanently.
  - `omp_control_tool_pause`: Request that monitoring is temporarily paused; it has no effect if monitoring is already paused or stopped.
  - `omp_control_tool_flush`: Request flushing of any buffered data, independently whether monitoring is currently active.
  - `omp_control_tool_end`: Request that monitoring is turned off permanently, flushing all output and terminating the tool.

  For the listed standard commands, the modifier and arg arguments are ignored by the tool.

  Negative return values indicate that the tool has not processed the command; in particular, the return value is `omp_control_tool_notool` if OMPT is inactive and no tool is active; if it is active but no callback is registered for the tool-control event, `omp_control_tool_nocallback` is returned. On success, `omp_control_tool_success` is returned and `omp_control_tool_ignored` indicates that the tool received the command but ignored it. Positive return values greater than 64 are tool specific.

  GCC implements the OpenMP 6.0 version of this function for C and C++, which is not compatible with its type signature in previous versions of the OpenMP specification. In older versions, the type `int` was used for the command argument in place of the enumerated type `omp_control_tool_t`; the return type likewise changed from `int` to `omp_control_tool_result_t`.

C/C++:

  Prototype: | `omp_control_tool_result_t omp_control_tool(`
  | `omp_control_tool_t command, int modifier, void *arg)`

Fortran:

  Interface: | `integer (kind=omp_control_tool_result_kind) &`
  | `function omp_control_tool(command, modifier)`
  | `integer (kind=omp_control_tool_kind) command`
  | `integer :: modifier`

Reference:

  OpenMP specification v6.0, Section 31.1