Install Now
clGetProgramInfo - Returns information about the program object.
Contents
Copyright
Copyright © 2007-2011 The Khronos Group Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and/or
associated documentation files (the "Materials"), to deal in the Materials without restriction, including
without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Materials, and to permit persons to whom the Materials are furnished to do so, subject to
the condition that this copyright notice and permission notice shall be included in all copies or
substantial portions of the Materials.
Errors
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 table above and param_value is not NULL.
• CL_INVALID_PROGRAM if program is 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.
Name
clGetProgramInfo - Returns information about the program object.
cl_intclGetProgramInfo(cl_programprogram,cl_program_infoparam_name,size_tparam_value_size,void*param_value,size_t*param_value_size_ret);Notes
1. OpenCL Specification
page 150, section 5.6.7 - Program Object Queries (updated for 1.2 rev 14)
The Khronos Group 11/18/2024 CLGETPROGRAMINFO(3clc)
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 table below.
┌────────────────────────────┬──────────────────────────────────────────┐
│ cl_program_info │ ReturnTypeandInfo.returnedin │
│ │ param_value │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_REFERENCE_COUNT │ Return type: cl_uint │
│ │ │
│ │ Return the program reference count. │
│ │ │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_CONTEXT │ Return type: cl_context │
│ │ │
│ │ Return the context specified when the │
│ │ program object is created │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_NUM_DEVICES │ Return type: cl_uint │
│ │ │
│ │ Return the number of devices │
│ │ associated with program. │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_DEVICES │ Return type: 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 progam │
│ │ object is created using │
│ │ clCreateProgramWithBinary(3clc). │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_SOURCE │ Return type: char[] │
│ │ │
│ │ Return the program source code │
│ │ specified by │
│ │ clCreateProgramWithSource(3clc). The │
│ │ source string returned is a │
│ │ concatenation of all source strings │
│ │ specified to │
│ │ clCreateProgramWithSource(3clc) with │
│ │ a null terminator. The concatenation │
│ │ strips any nulls in the original │
│ │ source strings. │
│ │ │
│ │ If program is created using │
│ │ clCreateProgramWithBinary(3clc) or │
│ │ clCreateProgramWithBuiltInKernels(3clc), │
│ │ 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_BINARY_SIZES │ Return type: 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(3clc), │
│ │ the implementation may return zero in │
│ │ any entries of the returned array. │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_BINARIES │ Return type: 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(3clc) or it │
│ │ can be the executable binary generated │
│ │ by clBuildProgram(3clc) or │
│ │ clLinkProgram(3clc). If program is │
│ │ created with │
│ │ clCreateProgramWithSource(3clc), the │
│ │ binary returned is the binary generated │
│ │ by clBuildProgram(3clc), │
│ │ clCompileProgram(3clc), or │
│ │ clLinkProgram(3clc). 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. │
│ │ │
│ │ If an entry value in the array is NULL, │
│ │ the implementation skips copying the │
│ │ program binary for the specific device │
│ │ identified by the array index. │
├────────────────────────────┼──────────────────────────────────────────┤
│ CL_PROGRAM_NUM_KERNELS │ Return type: size_t │
│ │ │
│ │ Returns the number of kernels declared │
│ │ in program that can be created with │
│ │ clCreateKernel(3clc). 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 │ Return type: char[] │
│ │ │
│ │ Returns a semi-colon separated list of │
│ │ kernel names in program that can be │
│ │ created with clCreateKernel(3clc). 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. │
└────────────────────────────┴──────────────────────────────────────────┘
param_value
A pointer to memory where the appropriate result being queried is returned. If param_value is NULL,
it is ignored.
param_value_size
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 table above.
param_value_size_ret
Returns the actual size in bytes of data copied to param_value. If param_value_size_ret is NULL, it
is ignored.
See Also
clGetProgramBuildInfo(3clc)
Specification
OpenCLSpecification[1]
PNG Icons
