C Specification

To return build information for each device in the program object, call the function

// Provided by CL_VERSION_1_0
cl_int clGetProgramBuildInfo(
    cl_program program,
    cl_device_id device,
    cl_program_build_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.

  • device specifies the device for which build information is being queried. device must be a valid device associated with program.

  • param_name specifies the information to query. The list of supported param_name types and the information returned in param_value by clGetProgramBuildInfo is described in the Program Build 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 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 Program Build 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_name. If param_value_size_ret is NULL, it is ignored.

Description

Table 1. List of supported param_names by clGetProgramBuildInfo
Program Build Info Return Type Description

CL_PROGRAM_BUILD_STATUS

cl_build_status

Returns the build, compile or link status, whichever was performed last on the specified program object for device.

This can be one of the following:

CL_BUILD_NONE - The build status returned if no clBuildProgram, clCompileProgram or clLinkProgram has been performed on the specified program object for device).

CL_BUILD_ERROR - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - generated an error.

CL_BUILD_SUCCESS - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - was successful.

CL_BUILD_IN_PROGRESS - The build status returned if clBuildProgram, clCompileProgram or clLinkProgram - whichever was performed last on the specified program object for device - has not finished.

CL_PROGRAM_BUILD_OPTIONS

char[]

Return the build, compile or link options specified by the options argument in clBuildProgram, clCompileProgram or clLinkProgram, whichever was performed last on the specified program object for device.

If build status of the specified program for device is CL_BUILD_NONE, an empty string is returned.

CL_PROGRAM_BUILD_LOG

char[]

Return the build, compile or link log for clBuildProgram, clCompileProgram or clLinkProgram, whichever was performed last on program for device.

If build status of the specified program for device is CL_BUILD_NONE, an empty string is returned.

CL_PROGRAM_BINARY_TYPE

missing before version 1.2.

cl_program_binary_type

Return the program binary type for device. This can be one of the following values:

CL_PROGRAM_BINARY_TYPE_NONE - There is no binary associated with the specified program object for device.

CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT - A compiled binary is associated with device. This is the case when the specified program object was created using clCreateProgramWithSource and compiled using clCompileProgram, or when a compiled binary was loaded using clCreateProgramWithBinary.

CL_PROGRAM_BINARY_TYPE_LIBRARY - A library binary is associated with device. This is the case when the specified program object was linked by clLinkProgram using the -create-library link option, or when a compiled library binary was loaded using clCreateProgramWithBinary.

CL_PROGRAM_BINARY_TYPE_EXECUTABLE - An executable binary is associated with device. This is the case when the specified program object was linked by clLinkProgram without the -create-library link option, or when an executable binary was built using clBuildProgram.

CL_PROGRAM_BINARY_TYPE_INTERMEDIATE — An intermediate (non-source) representation for the program is loaded as a binary. The program must be further processed with clCompileProgram or clBuildProgram.

If processed with clCompileProgram, the result will be a binary of type CL_PROGRAM_BINARY_TYPE_COMPILED_OBJECT or CL_PROGRAM_BINARY_TYPE_LIBRARY. If processed with clBuildProgram, the result will be a binary of type CL_PROGRAM_BINARY_TYPE_EXECUTABLE.

CL_PROGRAM_BUILD_GLOBAL_VARIABLE_TOTAL_SIZE

missing before version 2.0.

size_t

The total amount of storage, in bytes, used by program variables in the global address space.

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

  • CL_INVALID_PROGRAM if program is a not a valid program object.

  • CL_INVALID_DEVICE if device is not in the list of devices associated with program.

  • 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 Program Build 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.

A program binary (compiled binary, library binary or executable binary) built for a parent device can be used by all its sub-devices. If a program binary has not been built for a sub-device, the program binary associated with the parent device will be used.

A program binary for a device specified with clCreateProgramWithBinary or queried using clGetProgramInfo can be used as the binary for the associated root device, and all sub-devices created from the root-level device or sub-devices thereof.

See Also

CL_VERSION_1_0, cl_device_id, cl_program, cl_program_build_info

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