C Specification

To return information about a program object, call the function

cl_int clGetProgramInfo(
    cl_program program,
    cl_program_info param_name,
    size_t param_value_size,
    void* param_value,
    size_t* param_value_size_ret);

Parameters

  • program specifies the program object being queried.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramInfo is described in the Program Object Queries table.

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

  • param_value_size is used to specify the size in bytes of memory pointed to by param_value. This size must be ≥ size of return type as described in the Program Object Queries table.

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

Description

Table 1. List of supported param_names by https://www.khronos.org/registry/OpenCL/specs/2.2/html/OpenCL_API.html#clGetProgramInfo
cl_program_info Return Type Info. returned in param_value

CL_​PROGRAM_​REFERENCE_​COUNT14

cl_uint

Return the program reference count.

CL_​PROGRAM_​CONTEXT

cl_context

Return the context specified when the program object is created

CL_​PROGRAM_​NUM_​DEVICES

cl_uint

Return the number of devices associated with program.

CL_​PROGRAM_​DEVICES

cl_device_id[]

Return the list of devices associated with the program object. This can be the devices associated with context on which the program object has been created or can be a subset of devices that are specified when a program object is created using clCreateProgramWithBinary.

CL_​PROGRAM_​SOURCE

char[]

Return the program source code specified by clCreateProgramWithSource. The source string returned is a concatenation of all source strings specified to clCreateProgramWithSource with a null terminator. The concatenation strips any nulls in the original source strings.

If program is created using clCreateProgramWithBinary, clCreateProgramWithIL or clCreateProgramWithBuiltInKernels, a null string or the appropriate program source code is returned depending on whether or not the program source code is stored in the binary.

The actual number of characters that represents the program source code including the null terminator is returned in param_value_size_ret.

CL_​PROGRAM_​IL

Missing before version 2.1. Also see extension cl_khr_il_program.

char[]

Returns the program IL for programs created with clCreateProgramWithIL.

If program is created with clCreateProgramWithSource, clCreateProgramWithBinary or clCreateProgramWithBuiltInKernels the memory pointed to by param_value will be unchanged and param_value_size_retwill be set to 0.

CL_​PROGRAM_​BINARY_​SIZES

size_t[]

Returns an array that contains the size in bytes of the program binary (could be an executable binary, compiled binary or library binary) for each device associated with program. The size of the array is the number of devices associated with program. If a binary is not available for a device(s), a size of zero is returned.

If program is created using clCreateProgramWithBuiltInKernels, the implementation may return zero in any entries of the returned array.

CL_​PROGRAM_​BINARIES

unsigned char *[]

Return the program binaries (could be an executable binary, compiled binary or library binary) for all devices associated with program. For each device in program, the binary returned can be the binary specified for the device when program is created with clCreateProgramWithBinary or it can be the executable binary generated by clBuildProgram or clLinkProgram. If program is created with clCreateProgramWithSource or clCreateProgramWithIL, the binary returned is the binary generated by clBuildProgram, clCompileProgram or clLinkProgram. The bits returned can be an implementation-specific intermediate representation (a.k.a. IR) or device specific executable bits or both. The decision on which information is returned in the binary is up to the OpenCL implementation.

param_value points to an array of n pointers allocated by the caller, where n is the number of devices associated with program. The buffer sizes needed to allocate the memory that these n pointers refer to can be queried using the CL_​PROGRAM_​BINARY_​SIZES query as described in this table.

Each entry in this array is used by the implementation as the location in memory where to copy the program binary for a specific device, if there is a binary available. To find out which device the program binary in the array refers to, use the CL_​PROGRAM_​DEVICES query to get the list of devices. There is a one-to-one correspondence between the array of n pointers returned by CL_​PROGRAM_​BINARIES and array of devices returned by CL_​PROGRAM_​DEVICES.

CL_​PROGRAM_​NUM_​KERNELS

Missing before version 1.2.

size_t

Returns the number of kernels declared in program that can be created with clCreateKernel. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program.

CL_​PROGRAM_​KERNEL_​NAMES

Missing before version 1.2.

char[]

Returns a semi-colon separated list of kernel names in program that can be created with clCreateKernel. This information is only available after a successful program executable has been built for at least one device in the list of devices associated with program.

CL_​PROGRAM_​SCOPE_​GLOBAL_​CTORS_​PRESENT

Missing before version 2.2.

cl_bool

This indicates that the program object contains non-trivial constructor(s) that will be executed by runtime before any kernel from the program is executed.

CL_​PROGRAM_​SCOPE_​GLOBAL_​DTORS_​PRESENT

Missing before version 2.2.

cl_bool

This indicates that the program object contains non-trivial destructor(s) that will be executed by runtime when program is destroyed.

14

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.

clGetProgramInfo returns CL_​SUCCESS if the function is executed successfully. Otherwise, it returns one of the following errors:

  • CL_​INVALID_​VALUE if param_name is not valid, or if size in bytes specified by param_value_size is < size of return type as described in the Program Object Queries table and param_value is not NULL.

  • CL_​INVALID_​PROGRAM if program is a not a valid program object.

  • CL_​INVALID_​PROGRAM_​EXECUTABLE if param_name is CL_​PROGRAM_​NUM_​KERNELS or CL_​PROGRAM_​KERNEL_​NAMES and a successful program executable has not been built for at least one device in the list of devices associated with program.

  • 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

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 (c) 2014-2020 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.