| blob | 0fb5a1006f7b673413134ffc18a80587227e7510 |
1 .\" Copyright (c) [year] [your name]
2 .\" All rights reserved.
3 .\"
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
6 .\" are met:
7 .\" 1. Redistributions of source code must retain the above copyright
8 .\" notice, this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
12 .\"
13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23 .\" SUCH DAMAGE.
24 .\"
25 .\" $FreeBSD$
26 .\"
27 .\" Note: The date here should be updated whenever a non-trivial
28 .\" change is made to the manual page.
29 .Dd September 27, 2006
30 .Dt EXAMPLE 9
31 .Os
32 .Sh NAME
33 .Nm example
34 .Nd "example kernel interface manual page"
35 .Sh SYNOPSIS
36 .In sys/example.h
37 .Ft int
38 .Fn example "char *ptr" "int mode"
39 .Sh DESCRIPTION
40 This is an example manual page for the
41 .Fn example
42 kernel function.
43 It is intended that this example can be used as a template
44 when writing a new manual page.
45 .Pp
46 The
47 .Fn example
48 function takes two arguments:
49 .Fa ptr
50 and
51 .Fa mode .
52 The argument
53 .Fa mode
54 may have one of the following values:
55 .Bl -tag -width ".Dv EXAMPLE_ONE"
56 .It Dv EXAMPLE_ONE
57 First example of a defined variable.
58 .Dv EXAMPLE_ONE
59 is described below.
60 .It Dv EXAMPLE_TWO
61 Second example.
62 .El
63 .Pp
64 The above values are defined in
65 .In example.h
66 as follows:
67 .Bd -literal
68 #define EXAMPLE_ONE 1
69 #define EXAMPLE_TWO 2
70 .Ed
71 .Sh IMPLEMENTATION NOTES
72 The
73 .Fn example
74 function is not actually implemented.
75 .Sh LOCKING
76 The
77 .Va example_lock
78 lock must be held before
79 .Fn example
80 is called.
81 .Pp
82 Since
83 .Va example_lock
84 is a
85 .Xr mutex 9 ,
86 no sleepable locks (i.e.,
87 .Xr sx 9
88 locks) can be acquired in
89 .Fn example .
90 .Sh RETURN VALUES
91 The
92 .Fn example
93 function returns the value 0 if successful;
94 otherwise one of the values listed in the
95 .Sx ERRORS
96 section is returned, to indicate the error.
97 .Sh EXAMPLES
98 .Bd -literal
99 int error;
101 mtx_lock(&example_lock);
102 if ((error = example(NULL, EXAMPLE_ONE)) != 0) {
103 mtx_unlock(&example_lock);
104 return (error);
105 }
106 mtx_unlock(&example_lock);
107 .Ed
108 .Sh COMPATIBILITY
109 The
110 .Fn example
111 function has no known compatibility issues.
112 .Sh ERRORS
113 .\" Delete any errno's that are not returned by your
114 .\" function or system call and then tailor the
115 .\" remaining text as needed.
116 The
117 .Fn example
118 function will fail if:
119 .Bl -tag -width Er
120 .It Bq Er EPERM
121 Operation not permitted.
122 .It Bq Er ENOENT
123 No such file or directory.
124 .It Bq Er ESRCH
125 No such process.
126 .It Bq Er EINTR
127 Interrupted system call.
128 .It Bq Er EIO
129 Input/output error.
130 .It Bq Er ENXIO
131 Device not configured.
132 .It Bq Er E2BIG
133 Argument list too long.
134 .It Bq Er ENOEXEC
135 Exec format error.
136 .It Bq Er EBADF
137 Bad file descriptor.
138 .It Bq Er ECHILD
139 No child processes.
140 .It Bq Er EDEADLK
141 Resource deadlock avoided.
142 .It Bq Er ENOMEM
143 Cannot allocate memory.
144 .It Bq Er EACCES
145 Permission denied.
146 .It Bq Er EFAULT
147 Bad address.
148 .It Bq Er ENOTBLK
149 Block device required.
150 .It Bq Er EBUSY
151 Device busy.
152 .It Bq Er EEXIST
153 File exists.
154 .It Bq Er EXDEV
155 Cross-device link.
156 .It Bq Er ENODEV
157 Operation not supported by device.
158 .It Bq Er ENOTDIR
159 Not a directory.
160 .It Bq Er EISDIR
161 Is a directory.
162 .It Bq Er EINVAL
163 Invalid argument.
164 .It Bq Er ENFILE
165 Too many open files in system.
166 .It Bq Er EMFILE
167 Too many open files.
168 .It Bq Er ENOTTY
169 Inappropriate ioctl for device.
170 .It Bq Er ETXTBSY
171 Text file busy.
172 .It Bq Er EFBIG
173 File too large.
174 .It Bq Er ENOSPC
175 No space left on device.
176 .It Bq Er ESPIPE
177 Illegal seek.
178 .It Bq Er EROFS
179 Read-only file system.
180 .It Bq Er EMLINK
181 Too many links.
182 .It Bq Er EPIPE
183 Broken pipe.
184 .It Bq Er EDOM
185 Numerical argument out of domain.
186 .It Bq Er ERANGE
187 Result too large.
188 .It Bq Er EAGAIN
189 Resource temporarily unavailable.
190 .It Bq Er EWOULDBLOCK
191 Operation would block.
192 .It Bq Er EINPROGRESS
193 Operation now in progress.
194 .It Bq Er EALREADY
195 Operation already in progress.
196 .It Bq Er ENOTSOCK
197 Socket operation on non-socket.
198 .It Bq Er EDESTADDRREQ
199 Destination address required.
200 .It Bq Er EMSGSIZE
201 Message too long.
202 .It Bq Er EPROTOTYPE
203 Protocol wrong type for socket.
204 .It Bq Er ENOPROTOOPT
205 Protocol not available.
206 .It Bq Er EPROTONOSUPPORT
207 Protocol not supported.
208 .It Bq Er ESOCKTNOSUPPORT
209 Socket type not supported.
210 .It Bq Er EOPNOTSUPP
211 Operation not supported.
212 .It Bq Er EPFNOSUPPORT
213 Protocol family not supported.
214 .It Bq Er EAFNOSUPPORT
215 Address family not supported by protocol family.
216 .It Bq Er EADDRINUSE
217 Address already in use.
218 .It Bq Er EADDRNOTAVAIL
219 Cannot assign requested address.
220 .It Bq Er ENETDOWN
221 Network is down.
222 .It Bq Er ENETUNREACH
223 Network is unreachable.
224 .It Bq Er ENETRESET
225 Network dropped connection on reset.
226 .It Bq Er ECONNABORTED
227 Software causes connection abort.
228 .It Bq Er ENOBUFS
229 No buffer space available.
230 .It Bq Er EISCONN
231 Socket is already connected.
232 .It Bq Er ENOTCONN
233 Socket is not connected.
234 .It Bq Er ESHUTDOWN
235 Cannot send after socket shutdown.
236 .It Bq Er ETOOMANYREFS
237 Too many references: cannot splice.
238 .It Bq Er ETIMEDOUT
239 Operation timed out.
240 .It Bq Er ECONNREFUSED
241 Connection refused.
242 .It Bq Er ELOOP
243 Too many levels of symbolic links.
244 .It Bq Er ENAMETOOLONG
245 File name too long.
246 .It Bq Er EHOSTDOWN
247 Host is down.
248 .It Bq Er EHOSTUNREACH
249 No route to host.
250 .It Bq Er ENOTEMPTY
251 Directory not empty.
252 .It Bq Er EPROCLIM
253 Too many processes.
254 .It Bq Er EUSERS
255 Too many users.
256 .It Bq Er EDQUOT
257 Disc quota exceeded.
258 .It Bq Er ESTALE
259 Stale NFS file handle.
260 .It Bq Er EREMOTE
261 Too many levels of remote in path.
262 .It Bq Er EBADRPC
263 RPC struct is bad.
264 .It Bq Er ERPCMISMATCH
265 RPC version wrong.
266 .It Bq Er EPROGUNAVAIL
267 RPC program not available.
268 .It Bq Er EPROGMISMATCH
269 Program version wrong.
270 .It Bq Er EPROCUNAVAIL
271 Bad procedure for program.
272 .It Bq Er ENOLCK
273 No locks available.
274 .It Bq Er ENOSYS
275 Function not implemented.
276 .It Bq Er EFTYPE
277 Inappropriate file type or format.
278 .It Bq Er EAUTH
279 Authentication error.
280 .It Bq Er ENEEDAUTH
281 Need authenticator.
282 .It Bq Er EIDRM
283 Identifier removed.
284 .It Bq Er ENOMSG
285 No message of desired type.
286 .It Bq Er EOVERFLOW
287 Value too large to be stored in data type.
288 .It Bq Er ECANCELED
289 Operation canceled.
290 .It Bq Er EILSEQ
291 Illegal byte sequence.
292 .It Bq Er ENOATTR
293 Attribute not found.
294 .It Bq Er EDOOFUS
295 Programming error.
296 .El
297 .Sh SEE ALSO
298 .Xr example 1 ,
299 .Xr example 3 ,
300 .Xr example 4 ,
301 .Xr mdoc 7 ,
302 .Xr mutex 9
303 .Rs
304 .%A "A. B. Author"
305 .%T "Example RFC Title"
306 .%O RFC0000
307 .Re
308 .Rs
309 .%A "A. B. Author"
310 .%B "Example Book Title"
311 .%O ISBN-0-000-00000-0
312 .Re
313 .Rs
314 .%A "A. B. Author"
315 .%D "January 1997"
316 .%J "Example Journal Name"
317 .%T "Example Article Title"
318 .Re
319 .Sh HISTORY
320 The
321 .Nm
322 manual page example first appeared in
323 .Fx 6.0 .
324 .Pp
325 Some other common
326 .Sx HISTORY
327 section examples are:
328 .Pp
329 The
330 .Nm
331 manual page example first appeared in
332 .Bx 4.4 .
333 .Pp
334 The
335 .Nm
336 manual page example first appeared in
337 .At v6 .
338 .Sh AUTHORS
339 This
340 manual page was written by
341 .An Giorgos Keramidas Aq keramida@FreeBSD.org .
342 .Sh BUGS
343 The actual code for this function is vaporware.