parameter types

Desctribes the different parameter types of functions.

Summary

parameter types	Desctribes the different parameter types of functions.
Different Types	There exist four kind of parameter types.
Examples
Function initializing an object
Extended Error Description

Different Types

There exist four kind of parameter types. Function parameters are distinguished according to their direction of information flow.

/in/	Input parameter. The value is read by the called function but not changed. If it accepts only a pointer to the value the parameter should be marked with const (const type_t * value). To flag it with the label /in/ is redundant.
/inout/	This kind of parameter is read from as well as written to. Preallocated return parameters like queried names fall in this category. Marking it with label /inout/ is redundant, cause every pointer to a non-const value is considered to be inout, provided that is not assigned a label indicating otherwise. The returned value is not changed in case of error. If the return value is constructed in several steps and the out parameter is used as buffer it is allowed to clear/reset the parameter in case of error. But this behaviour must be documented.
/out/	The parameter is only written to. It carries the result value of a function and is only valid if the function returns success. In case of error it is not changed. But in case of a complex init function which can carry out its operation only on the original out parameter it is allowed to operate on the out parameter directly. In case of an error the complex init function must ensure that the out parameter is reset to a FREE state (free can be called without error).
/ret/	The parameter contains the result or return value in case of success. In case of error it is either left unchanged or reset or cleared. The parameter must be initialized by the caller of the function before the function is called. It must be freed by the caller after the return value is no more required. The type wbuffer_t is used typically as a parameter of such a type. It can store return values of unknown size.
/err/	This parameter is only written to and conveys an extended error description. The returned value is only valid if the function returns an error. In case of success this value is never changed.

Examples

Function initializing an object

extern int init_slist( /*out*/slist_t * list ) ;
int err ;
slist_t list ;
err = init_slist( &list ) ;
if (err) { printf("error\n") ; }

Extended Error Description

int new_regexpression(
   /*out*/regexpression_t    ** regex,
   /*err*/regexpression_err_t * syntax_err,
          const char          * definition ) ;
int err ;
regexpression_err_t syntax_err ;
regexpression_t   * regex = 0 ;
err = new_regexpression( &regex, &syntax_err, ".*:[0-9]*: .*") ;
if (err) { /* check syntax_err for extended error information about syntax error */ ... }