| .ds lang COBOL | |
| .ds gcobol GCC\ \*[lang]\ Front-end | |
| .Dd \& September 2026 | |
| .Dt CBL_GET_PROGRAM_INFO 3\& "\&GNU Compatibility Library" | |
| .Os Linux | |
| .Sh NAME | |
| .Nm CBL_GET_PROGRAM_INFO | |
| .Nd Get metadata from a given program. | |
| .Sh LIBRARY | |
| libgcobol_compat_gnu | |
| . | |
| .Sh SYNOPSIS | |
| .Ic COPY CBL_GET_PROGRAM_INFO | |
| .Pp | |
| .Ic call Dq "CBL_GET_PROGRAM_INFO" | |
| using | |
| by value | |
| .Ar fn | |
| by reference | |
| .Ar param-block | |
| .Ar return-buf | |
| .Ar return-buf-len | |
| returning | |
| .Ar status-code | |
| . | |
| .Sh DESCRIPTION | |
| Parameters: | |
| .Pp | |
| .Bl -tag -compact -width fn | |
| .It Ar fn | |
| is the function number to execute, from 0 to 10. | |
| The list of supported functions is shown below: | |
| .Ar 0 : | |
| Return the program name for the innermost program in the call stack above | |
| .Nm | |
| and assign | |
| .Ar cblte-gpi-handle . | |
| .Ar 2 : | |
| Return the | |
| .Ar caller | |
| program name associated with a | |
| .Ar cblte-gpi-handle | |
| instance previously allocated by function 0. | |
| .Ar cblte-gpi-handle | |
| is updated to the caller function. | |
| .Ar 3 : | |
| close a | |
| .Ar cblte-gpi-handle | |
| instance previously allocated by function 0. | |
| .It Ar param-block | |
| an instance of type | |
| .Ar cblt-prog-info-params , | |
| defined in the | |
| .Ar cbltypes | |
| copybook as: | |
| .Bd -literal: | |
| 01 cblt-prog-info-params typedef. | |
| 03 cblte-gpi-size pic x(4) comp-5. | |
| 03 cblte-gpi-flags pic x(4) comp-5. | |
| 03 cblte-gpi-handle usage pointer. | |
| 03 cblte-gpi-prog-id usage pointer. | |
| 03 cblte-gpi-attrs pic x(4) comp-5. | |
| .Ar cblte-gpi-flags | |
| can further modify the behaviour of the 11 functions inside | |
| .Nm . | |
| A list of the currently supported bits is shown below: | |
| .Ar 0 : | |
| assign | |
| .Ar cblte-gpi-handle . | |
| This bit is only relevant for function | |
| .Ar 0 , | |
| and is ignored by all other functions. | |
| .Ar 1 : | |
| fill | |
| .Ar return-buf | |
| with the program name. | |
| This bit is only relevant for functions | |
| .Ar 0 | |
| and | |
| .Ar 2 . | |
| .Ar 2 : | |
| if set, the program name stored into | |
| .Ar return-buf | |
| shall be null-terminated, | |
| or space-terminated otherwise. | |
| .It Ar return-buf | |
| points to a buffer to be filled by | |
| .Nm . | |
| .It Ar return-buf-len | |
| on entry, | |
| .Ar return-buf-len | |
| indicates the length of the | |
| .Ar return-buf | |
| buffer, | |
| .Sy including | |
| the terminator byte (nul or space). | |
| On exit, | |
| .Ar return-buf-len | |
| is updated to the length of the program name, | |
| .Sy excluding | |
| the terminator byte. | |
| However, if | |
| .Ar return-buf-len | |
| is too small, | |
| .Ar return-buf | |
| is left untouched and | |
| .Ar return-buf-len | |
| is updated to the required buffer length, | |
| .Sy including | |
| the terminator byte. | |
| .Sh RETURN STATUS | |
| .Nm | |
| returns | |
| .Sy "PIC X(2) COMP-5" . | |
| The return status is 0 on success, else nonzero. | |
| The following return values are defined: | |
| .Ar 500 : | |
| (function 2 only) no parent available from the call stack. | |
| .Ar 1001 : | |
| invalid | |
| .Ar cblte-gpi-handle . | |
| .Ar 1009 : | |
| invalid parameter. | |
| .Ar 1011 : | |
| invalid or undefined program name. | |
| Additionally, | |
| .Ar libgcobol_compat_gnu | |
| uses this return value when no call stack was found for the given program. | |
| .Ar 1013 : | |
| .Ar return-buf-len | |
| is too small to write the function basename to | |
| .Ar return-buf . | |
| The required buffer length is therefore written to | |
| .Ar return-buf-len . | |
| . | |
| .Sh SEE ALSO | |
| .Xr CBL_CLOSE_FILE | |
| .Xr CBL_CREATE_FILE | |
| .Xr CBL_DELETE_FILE | |
| .Xr CBL_OPEN_FILE | |
| .Xr CBL_READ_FILE | |
| .Xr CBL_WRITE_FILE | |
| .Xr CBL_CHECK_FILE_EXIST | |
| . | |
| .Sh COPYRIGHT | |
| .Bd -unfilled -indent | |
| Copyright (c) 2021-2026 Symas Corporation | |
| Redistribution and use in source and binary forms, with or without | |
| modification, are permitted provided that the following conditions are | |
| met: | |
| * Redistributions of source code must retain the above copyright | |
| notice, this list of conditions and the following disclaimer. | |
| * Redistributions in binary form must reproduce the above | |
| copyright notice, this list of conditions and the following disclaimer | |
| in the documentation and/or other materials provided with the | |
| distribution. | |
| * Neither the name of the Symas Corporation nor the names of its | |
| contributors may be used to endorse or promote products derived from | |
| this software without specific prior written permission. | |
| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS | |
| "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT | |
| LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR | |
| A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT | |
| OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, | |
| SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT | |
| LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, | |
| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY | |
| THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT | |
| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE | |
| OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. | |
| .Ed |