style/function_pointers —
marking up function pointers
The
mdoc(7)
language does not provide perfect support for marking up syntax related to
function pointers. Here are the best available methods:
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)
.Fa “fp_arg_type fp_arg_name”
.Fa ...
.Fc
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
.Fa “argument_type argument_name”
.Fa “fp_ret_type (*arg_name_fp)(fp_arg_type fp_arg_name, ...)”
.Fa ...
.Fc
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, ...))”
.Fa “fp_arg_type fp_arg_name”
.Fa ...
.Fc
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