'\" t .\" Title: clGetProgramInfo .\" Author: The Khronos Group .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 01/14/2021 .\" Manual: OpenCL Manual .\" Source: The Khronos Group .\" Language: English .\" .TH "CLGETPROGRAMINFO" "3clc" "01/14/2021" "The Khronos Group" "OpenCL Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" clGetProgramInfo \- Returns information about the program object\&. .SH "" .HP \w'cl_int\ clGetProgramInfo('u .BI "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" ");" .SH "PARAMETERS" .PP \fI program \fR .RS 4 Specifies the program object being queried\&. .RE .PP \fI param_name \fR .RS 4 Specifies the information to query\&. The list of supported \fIparam_name\fR types and the information returned in \fIparam_value\fR by \fBclGetProgramInfo\fR is described in the table below\&. .TS allbox tab(:); lB lB. T{ cl_program_info T}:T{ Return Type and Info\&. returned in \fIparam_value\fR T} .T& l l l l l l l l l l l l l l l l l l. T{ \fBCL_PROGRAM_REFERENCE_COUNT\fR T}:T{ Return type: cl_uint Return the \fIprogram\fR reference count\&. .sp 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\&. T} T{ \fBCL_PROGRAM_CONTEXT\fR T}:T{ Return type: cl_context Return the context specified when the program object is created T} T{ \fBCL_PROGRAM_NUM_DEVICES\fR T}:T{ Return type: cl_uint Return the number of devices associated with \fIprogram\fR\&. T} T{ \fBCL_PROGRAM_DEVICES\fR T}:T{ 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 \fBclCreateProgramWithBinary\fR(3clc)\&. T} T{ \fBCL_PROGRAM_SOURCE\fR T}:T{ Return type: char[] Return the program source code specified by \fBclCreateProgramWithSource\fR(3clc)\&. The source string returned is a concatenation of all source strings specified to \fBclCreateProgramWithSource\fR(3clc) with a null terminator\&. The concatenation strips any nulls in the original source strings\&. .sp If \fIprogram\fR is created using \fBclCreateProgramWithBinary\fR(3clc) or \fBclCreateProgramWithBuiltInKernels\fR(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\&. .sp The actual number of characters that represents the program source code including the null terminator is returned in \fIparam_value_size_ret\fR\&. T} T{ \fBCL_PROGRAM_BINARY_SIZES\fR T}:T{ 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 \fIprogram\fR\&. The size of the array is the number of devices associated with \fIprogram\fR\&. If a binary is not available for a device(s), a size of zero is returned\&. .sp If \fIprogram\fR is created using \fBclCreateProgramWithBuiltInKernels\fR(3clc), the implementation may return zero in any entries of the returned array\&. T} T{ \fBCL_PROGRAM_BINARIES\fR T}:T{ Return type: unsigned char *[] Return the program binaries (could be an executable binary, compiled binary or library binary) for all devices associated with \fIprogram\fR\&. For each device in \fIprogram\fR, the binary returned can be the binary specified for the device when \fIprogram\fR is created with \fBclCreateProgramWithBinary\fR(3clc) or it can be the executable binary generated by \fBclBuildProgram\fR(3clc) or \fBclLinkProgram\fR(3clc)\&. If program is created with \fBclCreateProgramWithSource\fR(3clc), the binary returned is the binary generated by \fBclBuildProgram\fR(3clc), \fBclCompileProgram\fR(3clc), or \fBclLinkProgram\fR(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\&. .sp \fIparam_value\fR 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 \fBCL_PROGRAM_BINARY_SIZES\fR query as described in this table\&. .sp 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 \fBCL_PROGRAM_DEVICES\fR query to get the list of devices\&. There is a one\-to\-one correspondence between the array of n pointers returned by \fBCL_PROGRAM_BINARIES\fR and array of devices returned by \fBCL_PROGRAM_DEVICES\&.\fR .sp 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\&. T} T{ \fBCL_PROGRAM_NUM_KERNELS\fR T}:T{ Return type: size_t Returns the number of kernels declared in \fIprogram\fR that can be created with \fBclCreateKernel\fR(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 \fIprogram\fR\&. T} T{ \fBCL_PROGRAM_KERNEL_NAMES\fR T}:T{ Return type: char[] Returns a semi\-colon separated list of kernel names in \fIprogram\fR that can be created with \fBclCreateKernel\fR(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 \fIprogram\fR\&. T} .TE .sp 1 .RE .PP \fI param_value \fR .RS 4 A pointer to memory where the appropriate result being queried is returned\&. If \fIparam_value\fR is NULL, it is ignored\&. .RE .PP \fI param_value_size \fR .RS 4 Used to specify the size in bytes of memory pointed to by \fIparam_value\fR\&. This size must be ≥ size of return type as described in the table above\&. .RE .PP \fI param_value_size_ret \fR .RS 4 Returns the actual size in bytes of data copied to \fIparam_value\fR\&. If \fIparam_value_size_ret\fR is NULL, it is ignored\&. .RE .SH "ERRORS" .PP Returns CL_SUCCESS if the function is executed successfully\&. Otherwise, it returns one of the following errors: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} CL_INVALID_VALUE if \fIparam_name\fR is not valid, or if size in bytes specified by \fIparam_value_size\fR is < size of return type as described in the table above and \fIparam_value\fR is not NULL\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} CL_INVALID_PROGRAM if \fIprogram\fR is not a valid program object\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} CL_INVALID_PROGRAM_EXECUTABLE if \fIparam_name\fR is \fBCL_PROGRAM_NUM_KERNELS\fR or \fBCL_PROGRAM_KERNEL_NAMES\fR and a successful program executable has not been built for at least one device in the list of devices associated with \fIprogram\fR\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} CL_OUT_OF_RESOURCES if there is a failure to allocate resources required by the OpenCL implementation on the device\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} CL_OUT_OF_HOST_MEMORY if there is a failure to allocate resources required by the OpenCL implementation on the host\&. .RE .SH "SPECIFICATION" .PP \m[blue]\fBOpenCL Specification\fR\m[]\&\s-2\u[1]\d\s+2 .SH "SEE ALSO" .PP \fBclGetProgramBuildInfo\fR(3clc) .SH "AUTHORS" .PP \fBThe Khronos Group\fR .SH "COPYRIGHT" .br Copyright \(co 2007-2011 The Khronos Group Inc. .br 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. .sp .SH "NOTES" .IP " 1." 4 OpenCL Specification .RS 4 \%page 150, section 5.6.7 - Program Object Queries (updated for 1.2 rev 14) .RE