intro/synopsis_func —
SYNOPSIS section for library functions
The most important idioms are, mentioning the frequency in the
OpenBSD base tree in parentheses:
-
-
In
filename (1360)- Before listing any function prototype, cite the header file or header
files that need to be included to use the function.
-
-
Ft
function return type (3330)- Start each function prototype with one
Ft macro line. Provide the function
return type as arguments. No quoting is required, not even if the type
consists of multiple words or contains pointer symbols
(‘*’).
-
-
Fo
function_name (400)- After the
Ft line, provide the function
name in an Fo macro line.
-
-
Fa
“argument_type argument_name”
(1000)- After the
Fo line, provide one
Fa macro for each function argument.
Since function arguments usually consist of a type and a name and there is
a space between the type and the name, each function argument usually
requires quoting.
-
-
Fc
(400)- After all arguments, close each
Fo
block by an explicit Fc block end
macro.
-
-
Fd
#define macro
definition (65)- Use the
Fd macro to present
preprocessor macro definitions.
-
-
Vt
variable_type variable_name (45)- Use the
Vt macro for declarations of
global variables.
A minimal example showing just the macros that are almost always needed:
.In sys/stat.h
.Ft int
.Fo chmod
.Fa "const char *path"
.Fa "mode_t mode"
.Fc
Style guide:
the
SYNOPSIS section for library functions