FUNCTION_POINTERS(MDOC) MDOC FUNCTION_POINTERS(MDOC)

NAME

style/function_pointersmarking up function pointers

DESCRIPTION

The mdoc(7) language does not provide perfect support for marking up syntax related to function pointers. Here are the best available methods:

Declaring a type representing a function pointer

The normal combination of Ft, Fo, Fa, and Fc can be used, except that the usual arguments of Ft are preceded by an additional first argument containing the keyword typedef and that the argument of Fo is prefixed with a pointer symbol and enclosed in parentheses:
.Ft typedef fp_ret_type 
.Fo (*function_pointer_type_name) 
.Fafp_arg_type fp_arg_name” 
.Fa ... 
.Fc

Functions taking function pointers as arguments

If the type of the function pointer was declared with typedef as shown above, the defined name of the type can simply be used for the Fa arguments.
Otherwise, the complete function pointer definition has to be given in a single Fa argument, without any markup:
.Ft return_type 
.Fo function_name 
.Faargument_type argument_name” 
.Fafp_ret_type (*arg_name_fp)(fp_arg_type fp_arg_name, ...)” 
.Fa ... 
.Fc

Functions returning function pointers

If the type of the function pointer was declared with typedef as shown above, the defined name of the type can simply be used as the Ft argument.
Otherwise, the complete prototype of the function returning the function pointer has to be given in the Fo argument, without any markup:
.Ft fp_ret_type 
.Fo “(*function_name(argument_name type_name, ...))” 
.Fafp_arg_type fp_arg_name” 
.Fa ... 
.Fc

EXAMPLES

Declare a type representing a function pointer:
.Ft typedef int 
.Fo (*GEN_SESSION_CB) 
.Fa "const SSL *ssl" 
.Fa "unsigned char *id" 
.Fa "unsigned int *id_len" 
.Fc
Use this function pointer type as a function argument:
.Ft int 
.Fo SSL_set_generate_session_id 
.Fa "SSL *ssl" 
.Fa "GEN_SESSION_CB cb" 
.Fc
Use a function pointer argument for which no typedef exists:
.Ft long 
.Fo SSL_callback_ctrl 
.Fa "SSL *ssl" 
.Fa "int cmd" 
.Fa "void (*fp)(void)" 
.Fc
The function described by
.Ft int 
.Fo "(*SSL_get_verify_callback(const SSL *s))" 
.Fa "int ok" 
.Fa "X509_STORE_CTX *ctx" 
.Fc
returns a function pointer matching the prototype
.Ft int 
.Fo (*callback) 
.Fa "int ok" 
.Fa "X509_STORE_CTX *ctx" 
.Fc
September 24, 2015 bsd.lv