All the function descriptions are based on a uniform principle, which is explained below.
The description of a function is divided into the following information categories:
Function name and brief description
Definition and general description
Parameters
Return value
Notes
Record I/O
Example
See also
Some of the above-mentioned sections may be omitted if they are not relevant to the function concerned or if the pertinent information (e.g. the data type of a parameter)is already evident from the syntax of the function call.
Definition and general description
The function definition includes the following information:
the name of the include file required for the function
the function header (data type and name of the function, list of formal parameters).
Function header marked with (C11) are only defined in the include file for translations with C/C++ version >= V4.0A and language mode C11 or C++ 2017.
Function header marked with (not C11) are not defined in the include file for translations with C/C++ version >= V4.0A and language mode C11 or C++ 2017.
Below this syntax you will find a general description of how the function works.
Parameters
In the case of complex functions, the function definition is followed by a detailed description of the parameters. This includes their meanings, possible values, associated effects, etc.
Parameters are differentiated into input parameters and result parameters. In the case of result parameters, as opposed to input parameters, the contents of variables transferred during the call are modified by the function. One also speaks of “implicit” function results in this context. Result parameters are defined as pointers to an object without the qualifier “const”. For result parameters you must always specify the variable address, i.e. a pointer argument, when you call the function. In addition, sufficient memory space must be allocated for arrays, string variables, and structures.
Return value
The possible function return values are listed here. If the return value indicates an error, you will find an additional note stating which error code, if any, is stored in the errno variable.
Notes
In this section, you will find information on the following:
possible sources of error (always the first item)
programming and application tips
interrelationship with other functions
technical details regarding how the function works
special points pertaining to BS2000.
Record I/O
This section is included for all input/output functions which can also be used on files with record-oriented input/output. It supplements the general “Notes” (principally formulated for stream-oriented input/output) with special notes applicable to record I/O (cf. section “Binaryfile” (Basic terms), “Stream-oriented input/output” (Basic terms), “Record-oriented input/output” (Basic terms)).
Example
Short example illustrating the application of the described function.
See also
References to the names of related functions.