C Specification

To query information about a command-buffer, call the function

// Provided by cl_khr_command_buffer
cl_int clGetCommandBufferInfoKHR(
    cl_command_buffer_khr command_buffer,
    cl_command_buffer_info_khr param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);
clGetCommandBufferInfoKHR is provided by the cl_khr_command_buffer extension.

Parameters

  • command_buffer specifies the command-buffer being queried.

  • param_name specifies the information to query.

  • param_value is a pointer to a memory location where the appropriate result being queried is returned. If param_value is NULL, it is ignored.

  • param_value_size specifies the size in bytes of memory pointed to by param_value. This size must be greater than or equal to the size of the return type specified in the Command-Buffer Queries table. If param_value is NULL, it is ignored.

  • param_value_size_ret returns the actual size in bytes of data being queried by param_value. If param_value_size_ret is NULL, it is ignored.

Description

The list of supported param_name values and the information returned in param_value by clGetCommandBufferInfoKHR is described in the table below.

Table 1. clGetCommandBufferInfoKHR values
Command Buffer Info Return Type Description

CL_COMMAND_BUFFER_NUM_QUEUES_KHR

provided by the cl_khr_command_buffer extension.

cl_uint

The number of command-queues specified when command_buffer was created.

CL_COMMAND_BUFFER_QUEUES_KHR

provided by the cl_khr_command_buffer extension.

cl_command_queue[]

Return the list of command-queues specified when the command_buffer was created.

CL_COMMAND_BUFFER_REFERENCE_COUNT_KHR [1]

provided by the cl_khr_command_buffer extension.

cl_uint

Return the command_buffer reference count.

CL_COMMAND_BUFFER_STATE_KHR

provided by the cl_khr_command_buffer extension.

cl_command_buffer_state_khr

Return the state of command_buffer.

CL_COMMAND_BUFFER_STATE_RECORDING_KHR is returned when command_buffer has not been finalized.

provided by the cl_khr_command_buffer extension.

CL_COMMAND_BUFFER_STATE_EXECUTABLE_KHR is returned when command_buffer has been finalized and there is not a Pending instance of command_buffer awaiting completion on a command_queue.

provided by the cl_khr_command_buffer extension.

CL_COMMAND_BUFFER_STATE_PENDING_KHR is returned when an instance of command_buffer has been enqueued for execution but not yet completed.

provided by the cl_khr_command_buffer extension.

CL_COMMAND_BUFFER_PROPERTIES_ARRAY_KHR

provided by the cl_khr_command_buffer extension.

cl_command_buffer_properties_khr[]

Return the properties argument specified in clCreateCommandBufferKHR.

If the properties argument specified in clCreateCommandBufferKHR used to create command_buffer was not NULL, the implementation must return the values specified in the properties argument.

If the properties argument specified in clCreateCommandBufferKHR used to create command_buffer was NULL, the implementation may return either a param_value_size_ret of 0 (i.e. there is are no properties to be returned), or the implementation may return a property value of 0 (where 0 is used to terminate the properties list).

CL_COMMAND_BUFFER_CONTEXT_KHR

provided by the cl_khr_command_buffer extension.

cl_context

Return the context associated with command_buffer.

clGetCommandBufferInfoKHR returns CL_SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_INVALID_COMMAND_BUFFER_KHR if command_buffer is not a valid command-buffer.

  • CL_INVALID_VALUE if param_name is not one of the supported values, or if the size in bytes specified by param_value_size is less than size of the return type specified in the Command-Buffer Queries table and param_value is not NULL.

  • CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device.

  • CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host.

See Also

cl_command_buffer_info_khr, cl_command_buffer_khr, cl_khr_command_buffer

Document Notes

For more information, see the OpenCL Specification

This page is extracted from the OpenCL Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

SPDX-License-Identifier: CC-BY-4.0

1. The reference count returned should be considered immediately stale. It is unsuitable for general use in applications. This feature is provided for identifying memory leaks.