-
Notifications
You must be signed in to change notification settings - Fork 4
/
part1-4.xml
267 lines (267 loc) · 10.2 KB
/
part1-4.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
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
<?xml version="1.0" encoding="UTF-8"?>
<html>
<head>
<meta http-equiv="Content-Type" content="text/xml; charset=utf-8"/>
<title>System Call</title>
<link rel="stylesheet" href="css/book.css" type="text/css"/>
</head>
<body>
<h2 id="sec_system_call">
System Call
</h2>
<p>
A system call differs from a user-land function in that it triggers the operating system kernel to perform some
operation. This usually applies to I/O, such as reading from files or sockets with <span class="func">write</span>.
Other than that, system calls are no different than regular functions — they're invoked, have return values, and
so on.
</p>
<p>
In <span class="lang">mdoc</span>, however, a system call is a special function consisting of at least one section not
found in ordinary function manuals.
</p>
<p>
The first difference between ordinary functions and system calls is the manual category. Let's study a function <span
class="func">khello</span>, <q>kernel hello</q>, which is similar to the <span class="func">hello</span>
function described earlier.
</p>
<div class="mdocin">
.Dd May 30, 2011
<br />
.Dt KHELLO 2
<br />
.Os
</div>
<p>
All system calls are in category <span class="cat">2</span>. Furthermore, unless under special circumstances, system call
are each accorded their own manual.
</p>
<p>
I'll use the same descriptive text as in the <span class="func">hello</span> example. Note that for system calls, the
<span class="header">hello.h</span> header file should be in the compiler's standard include path. This is usually
<span class="path">/usr/include</span> on UNIX systems.
</p>
<div class="mdocin">
.Sh NAME
<br />
.Nm hello
<br />
.Nd print greeting messages
<br />
.Sh SYNOPSIS
<br />
.In hello.h
<br />
.Ft int
<br />
.Fo hello
<br />
.Fa "int C" "const char *prefix"
<br />
.Fc
<br />
.Sh DESCRIPTION
<br />
The
<br />
.Nm
<br />
function prints out a greeting message.
<br />
.Pp
<br />
It accepts a value
<br />
.Fa C ,
<br />
which if non-zero indicates output should be uppercase; and
<br />
.Fa prefix ,
<br />
which, if not
<br />
.Dv NULL ,
<br />
shall be prefixed to the output.
<br />
The
<br />
.Fa prefix
<br />
argument, if not
<br />
.Dv NULL ,
<br />
must be nil-terminated.
</div>
<p>
You'll notice I've omitted the <span class="sec">LIBRARY</span> section in this example, as system calls by definition
aren't a part of a library. Furthermore, I've used the <a href="macros.xml#macro_dv" class="macro">Dv</a> macro to
annotate the term <span class="screen">NULL</span> as a constant variable.
</p>
<p>
Let's examine the output so far.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hello.h</span>></b>
<p></p>
<i class="mdoc-ftype">int</i>
<br/>
<b class="mdoc-fname">hello</b>(<i class="mdoc-farg">int C</i>, <i class="mdoc-farg">const char *prefix</i>);
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
The <b class="mdoc-name">hello</b> function prints out a greeting message.
<p></p>
It accepts a value <i class="mdoc-farg">C</i>, which if non-zero indicates output should be uppercase; and <i
class="mdoc-farg">prefix</i>, which, if not <span class="mdoc-define">NULL</span>, shall be prefixed to the
output. The <i class="mdoc-farg">prefix</i> argument, if not <span class="mdoc-define">NULL</span>, must be
nil-terminated.
</div>
</div>
<p>
In the <span class="func">hello</span> example, I included a section <span class="sec">RETURN VALUES</span> detailing
the return value of the function. System calls, however, usually return a standard value and have a side effect of
setting the C library <span class="var">errno</span> variable when invoked within a C language context. This is
documented with a special macro <a href="macros.xml#macro_rv" class="macro">Rv</a>.
</p>
<div class="mdocin">
.Sh RETURN VALUES
<br />
.Rv -std
</div>
<p>
The <span class="macroflag">std</span> flag is by convention always specified. This macro will produce standard text
regarding the <span class="var">errno</span> value and that the function returns <span class="value">-1</span> on
failure and <span class="value">0</span> on success.
</p>
<p>
If you have multiple functions specified in your manual, you must list them individually as arguments to <a
href="macros.xml#macro_rv" class="macro">Rv</a>.
</p>
<p>
Next, the possible values of <span class="var">errno</span> must be specified in the <span class="sec">ERRORS</span>
section as a list. Let's assume that <span class="var">EFAULT</span> may be set if the pointer is invalid.
</p>
<div class="mdocin">
.Sh ERRORS
<br />
.Bl -tag -width Er
<br />
.It Er EFAULT
<br />
.Fa prefix
<br />
points outside the allocated address space.
<br />
.El
</div>
<p>
The syntax of this list differs from lists we've already encountered. Earlier we used the special term <span
class="screen">Ds</span> as an argument to <span class="macroflag">width</span> to specify a generic width.
Here, we used <a href="macros.xml#macro_er" class="macro">Er</a>, which is also specified at the start of each list
tag (lines beginning with <a href="macros.xml#macro_it" class="macro">It</a>).
</p>
<p>
The macro <a href="macros.xml#macro_er" class="macro">Er</a> specifies a possible value of <span
class="var">errno</span>. There are many standard variable names for <span class="var">errno</span> values,
such as <span class="var">EFAULT</span> used in our example. When we stipulate this as the argument of <span
class="macroflag">width</span>, the formatter is able to translate this into a generic width of most <a
href="macros.xml#macro_er" class="macro">Er</a> macro contents.
</p>
<p>
You should avoid using this construct unless it's in a conventional way, as it is here.
</p>
<p>
If your system call is part of an operating system, it's common to add some lines as to when it was added. Let's assume
you're adding the function to a fictional Foo OS. Most modern UNIX operating systems have their own macros, such as <a
href="macros.xml#macro_bx" class="macro">Bx</a> for <a class="term" href="glossary.xml#bsd_unix">BSD UNIX</a>.
Be sure to note the version of the operating system.
</p>
<div class="mdocin">
.Sh HISTORY
<br />
The
<br />
.Nm
<br />
function call appeared in Foo OS version 1.0.
</div>
<p>
Let's put all of these sections together and preview the output.
</p>
<div class="mdocout">
<div class="mdoc-section">
<h1>NAME</h1>
<b class="mdoc-name">hello</b> — <span class="mdoc-desc">print greeting messages</span>
</div>
<div class="mdoc-section">
<h1>SYNOPSIS</h1>
<b class="mdoc-includes">#include <<span class="mdoc-link-includes">hello.h</span>></b>
<p></p>
<i class="mdoc-ftype">int</i><br/>
<b class="mdoc-fname">hello</b>(<i class="mdoc-farg">int C</i>, <i class="mdoc-farg">const char *prefix</i>);
</div>
<div class="mdoc-section">
<h1>DESCRIPTION</h1>
The <b class="mdoc-name">hello</b> function prints out a greeting message.
<p></p>
It accepts a value <i class="mdoc-farg">C</i>, which if non-zero indicates output should be uppercase; and <i
class="mdoc-farg">prefix</i>, which, if not <span class="mdoc-define">NULL</span>, shall be prefixed to
the output. The <i class="mdoc-farg">prefix</i> argument, if not <span class="mdoc-define">NULL</span>, must be
nil-terminated.
</div>
<div class="mdoc-section">
<h1>RETURN VALUES</h1>
The <b class="mdoc-fname">hello</b>() function returns the value 0 if successful; otherwise the value -1 is
returned and the global variable <b class="mdoc-var">errno</b> is set to indicate the error.
</div>
<div class="mdoc-section">
<h1>ERRORS</h1>
<dl style="margin-top: 0.00em;margin-bottom: 0.00em;" class="mdoc-list list-tag">
<dt class="mdoc-list-tag" style="margin-top: 1.00em;">
<span class="mdoc-errno">EFAULT</span></dt>
<dd class="mdoc-list-tag" style="margin-left: 17.00ex;">
<i class="mdoc-farg">prefix</i> points outside the allocated address space.</dd>
</dl>
</div>
<div class="mdoc-section">
<h1> HISTORY</h1>
The <b class="mdoc-name">hello</b> function call appeared in Foo OS version 1.0.
</div>
</div>
<p>
We can make sure the manual is complete by reviewing the checklist for function documentation.
</p>
<p>
First we implied linking information by using category two (which does not need to be specially linked). Then we
introduced the calling syntax of the function, naming its arguments. We also stipulated the necessary header files. In
the <span class="sec">DESCRIPTION</span>, we described the function and its arguments in full. Lastly, we documented
return values in the <span class="sec">RETURN VALUES</span> section and the errors set in <span
class="sec">ERRORS</span>.
</p>
<p>
We also added a <span class="sec">HISTORY</span> section, which isn't mentioned as part of our checklist but is
considered good practise for system calls. In general, a note on historical information is useful to put your component
in the general context of related machinery.
</p>
<table class="nav">
<tbody>
<tr>
<td class="nav-contents"><a href="toc.xml">Contents</a></td>
<td class="nav-next"><a href="part1-4-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-4.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>