Functions

Programming functions are a significant part of the UNIX canon, from the system call interface to the C library. If you're a C or C++ developer, chances are you've at least glanced through the manuals of functions such as socket, printf, or memmove.

In general, the mdoc macros used for documenting programming functions are the same as those used for Commands; however, there are some domain-specific bits to annotate the various parts of function versus command invocation. You'll see that each command invocation macro, such as Fl for a flag, has an analogue for programming functions, such as the Fa, for a function argument.

The mdoc format is used primarily for the C language and Fortran, but it works with C++, Perl, Tcl, and other imperative languages. In fact, most any language with functions (or subroutines) and variables will work, typed or not. In this book, I focus exclusively on the C language. This is due to the overwhelming presence of C libraries and functions documented with mdoc.

Before beginning, we need to change our mental checklist for a complete manual. Since function manuals can document more than just function parts, our manual must grow to account for complexity.

• Do I describe the preprocessing and linking information?
• Do I describe the calling syntax of each function and variable?
• Do I describe the type of each function and variable?
• Do I describe each argument in each calling syntax?
• Do I describe each function's operation?
• Do I describe each function's side effects?

A function is any callable instruction, be it a C function, routine, or macro. A variable may also be a C variable or macro. I'll consistently use the function and variable terminology in this book.

In general, you don't have to be knowledgeable of C to understand this section, but it helps to have a grasp of basic programming structure, such as functions, function prototypes, and header files. In any event, I'll refer to a header file as a text file consisting of function prototypes. Header files for the C language, such as in our examples, end with the .h suffix. A C function prototype indicates the calling syntax of a function, such as the following.

In this, the C function isspace, notationally referred to as isspace, has a single argument int c (an integer named c) and returns a value of type int (another integer). Multiple arguments are comma-separated.

Last edited by $Author: kristaps $ on $Date: 2011/11/05 16:50:11 $. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.