-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathpart1-2.xml
79 lines (79 loc) · 3.98 KB
/
part1-2.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>Functions</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h2 id="functions">
Functions
</h2>
<p>
Programming functions are a significant part of the UNIX canon, from the system call interface to the <a class="term"
href="glossary.xml#libc">C library</a>. If you're a C or C++ developer, chances are you've at least glanced
through the manuals of functions such as <span class="func">socket</span>, <span class="func">printf</span>, or <span
class="func">memmove</span>.
</p>
<p>
In general, the <span class="lang">mdoc</span> macros used for documenting programming functions are the same as those
used for <a href="part1-1.xml#commands">Commands</a>; 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
<a href="macros.xml#macro_fl" class="macro">Fl</a> for a flag, has an analogue for programming functions, such as
the <a href="macros.xml#macro_fa" class="macro">Fa</a>, for a function argument.
</p>
<p>
The <span class="lang">mdoc</span> format is used primarily for the <a class="term" href="glossary.xml#c">C language</a>
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 <span class="lang">mdoc</span>.
</p>
<p>
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.
</p>
<ul>
<li>Do I describe the preprocessing and linking information?</li>
<li>Do I describe the calling syntax of each function and variable?</li>
<li>Do I describe the type of each function and variable?</li>
<li>Do I describe each argument in each calling syntax?</li>
<li>Do I describe each function's operation?</li>
<li>Do I describe each function's side effects?</li>
</ul>
<p>
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.
</p>
<p>
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 <span class="file">.h</span> suffix. A C function prototype indicates the calling syntax of a function, such
as the following.
</p>
<div class="mdocin">
int
<br />
isspace(int c);
</div>
<p>
In this, the C function <span class="screen">isspace</span>, notationally referred to as <span
class="func">isspace</span>, has a single argument <span class="screen">int c</span> (an integer named <span
class="var">c</span>) and returns a value of type <span class="type">int</span> (another integer). Multiple
arguments are comma-separated.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-2-1.xml">Next</a></td>
<td class="nav-home"><a href="http://manpages.bsd.lv/index.html">Home</a></td>
<td class="nav-history"><a href="http://manpages.bsd.lv/cgi-bin/cvsweb/part1-2.xml?cvsroot=manpages">History</a></td>
</tr>
</tbody>
</table>
<p class="edits">
Last edited by $Author$ on $Date$. Copyright © 2011, Kristaps Dzonsons. CC BY-SA.
</p>
</body>
</html>