share/examples: use .Mt for emails in man pages
[dragonfly.git] / share / examples / mdoc / example.3
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: src/share/examples/mdoc/example.3,v 1.12.2.7 2001/08/17 13:08:35 ru Exp $
26 .\"
27 .\" Note: The date here should be updated whenever a non-trivial
28 .\" change is made to the manual page.
29 .Dd December 8, 1999
30 .Dt EXAMPLE 3
31 .Os
32 .Sh NAME
33 .Nm example
34 .Nd example library function manual page
35 .Sh LIBRARY
36 .\" Note: list of available libraries is available in mdoc(7)
37 .Lb libc
38 .Sh SYNOPSIS
39 .In example.h
40 .Ft int
41 .Fn example "char *ptr" "int mode"
42 .Sh DESCRIPTION
43 This is an example library function manual page for the
44 .Fn example
45 function.
46 It is intended that this example can be used as a template
47 when writing a new manual page.
48 .Pp
49 The
50 .Fn example
51 function takes two arguments:
52 .Fa ptr
53 and
54 .Fa mode .
55 The argument
56 .Fa mode
57 may have one of the following values:
58 .Bl -tag -width ".Dv EXAMPLE_ONE"
59 .It Dv EXAMPLE_ONE
60 First example of a defined variable.
61 .Dv EXAMPLE_ONE
62 is described below.
63 .It Dv EXAMPLE_TWO
64 Second example.
65 .El
66 .Pp
67 The above values are defined in
68 .In example.h
69 as follows:
70 .Bd -literal
71 #define EXAMPLE_ONE  1
72 #define EXAMPLE_TWO  2
73 .Ed
74 .Sh IMPLEMENTATION NOTES
75 The
76 .Fn example
77 function is not actually implemented.
78 .Sh RETURN VALUES
79 .Rv -std example
80 .Sh ENVIRONMENT
81 The
82 .Fn example
83 library function ignores the
84 .Ev EXAMPLE
85 environment variable.
86 .Sh FILES
87 .Bl -tag -width ".Pa /dev/null" -compact
88 .It Pa /dev/null
89 Example of a file in the
90 .Sx FILES
91 section.
92 .El
93 .Sh DIAGNOSTICS
94 None.
95 .Sh COMPATIBILITY
96 The
97 .Fn example
98 function has no known compatibility issues.
99 .Sh ERRORS
100 .\" Delete any errno's that are not returned by your
101 .\" function or system call and then tailor the
102 .\" remaining text as needed.
103 .Fn Example
104 will fail if:
105 .Bl -tag -width Er
106 .It Bq Er EPERM
107 Operation not permitted.
108 .It Bq Er ENOENT
109 No such file or directory.
110 .It Bq Er ESRCH
111 No such process.
112 .It Bq Er EINTR
113 Interrupted system call.
114 .It Bq Er EIO
115 Input/output error.
116 .It Bq Er ENXIO
117 Device not configured.
118 .It Bq Er E2BIG
119 Argument list too long.
120 .It Bq Er ENOEXEC
121 Exec format error.
122 .It Bq Er EBADF
123 Bad file descriptor.
124 .It Bq Er ECHILD
125 No child processes.
126 .It Bq Er EDEADLK
127 Resource deadlock avoided.
128 .It Bq Er ENOMEM
129 Cannot allocate memory.
130 .It Bq Er EACCES
131 Permission denied.
132 .It Bq Er EFAULT
133 Bad address.
134 .It Bq Er ENOTBLK
135 Block device required.
136 .It Bq Er EBUSY
137 Device busy.
138 .It Bq Er EEXIST
139 File exists.
140 .It Bq Er EXDEV
141 Cross-device link.
142 .It Bq Er ENODEV
143 Operation not supported by device.
144 .It Bq Er ENOTDIR
145 Not a directory.
146 .It Bq Er EISDIR
147 Is a directory.
148 .It Bq Er EINVAL
149 Invalid argument.
150 .It Bq Er ENFILE
151 Too many open files in system.
152 .It Bq Er EMFILE
153 Too many open files.
154 .It Bq Er ENOTTY
155 Inappropriate ioctl for device.
156 .It Bq Er ETXTBSY
157 Text file busy.
158 .It Bq Er EFBIG
159 File too large.
160 .It Bq Er ENOSPC
161 No space left on device.
162 .It Bq Er ESPIPE
163 Illegal seek.
164 .It Bq Er EROFS
165 Read-only file system.
166 .It Bq Er EMLINK
167 Too many links.
168 .It Bq Er EPIPE
169 Broken pipe.
170 .It Bq Er EDOM
171 Numerical argument out of domain.
172 .It Bq Er ERANGE
173 Result too large.
174 .It Bq Er EAGAIN
175 Resource temporarily unavailable.
176 .It Bq Er EWOULDBLOCK
177 Operation would block.
178 .It Bq Er EINPROGRESS
179 Operation now in progress.
180 .It Bq Er EALREADY
181 Operation already in progress.
182 .It Bq Er ENOTSOCK
183 Socket operation on non-socket.
184 .It Bq Er EDESTADDRREQ
185 Destination address required.
186 .It Bq Er EMSGSIZE
187 Message too long.
188 .It Bq Er EPROTOTYPE
189 Protocol wrong type for socket.
190 .It Bq Er ENOPROTOOPT
191 Protocol not available.
192 .It Bq Er EPROTONOSUPPORT
193 Protocol not supported.
194 .It Bq Er ESOCKTNOSUPPORT
195 Socket type not supported.
196 .It Bq Er EOPNOTSUPP
197 Operation not supported.
198 .It Bq Er EPFNOSUPPORT
199 Protocol family not supported.
200 .It Bq Er EAFNOSUPPORT
201 Address family not supported by protocol family.
202 .It Bq Er EADDRINUSE
203 Address already in use.
204 .It Bq Er EADDRNOTAVAIL
205 Cannot assign requested address.
206 .It Bq Er ENETDOWN
207 Network is down.
208 .It Bq Er ENETUNREACH
209 Network is unreachable.
210 .It Bq Er ENETRESET
211 Network dropped connection on reset.
212 .It Bq Er ECONNABORTED
213 Software causes connection abort.
214 .It Bq Er ENOBUFS
215 No buffer space available.
216 .It Bq Er EISCONN
217 Socket is already connected.
218 .It Bq Er ENOTCONN
219 Socket is not connected.
220 .It Bq Er ESHUTDOWN
221 Cannot send after socket shutdown.
222 .It Bq Er ETOOMANYREFS
223 Too many references: cannot splice.
224 .It Bq Er ETIMEDOUT
225 Operation timed out.
226 .It Bq Er ECONNREFUSED
227 Connection refused.
228 .It Bq Er ELOOP
229 Too many levels of symbolic links.
230 .It Bq Er ENAMETOOLONG
231 File name too long.
232 .It Bq Er EHOSTDOWN
233 Host is down.
234 .It Bq Er EHOSTUNREACH
235 No route to host.
236 .It Bq Er ENOTEMPTY
237 Directory not empty.
238 .It Bq Er EPROCLIM
239 Too many processes.
240 .It Bq Er EUSERS
241 Too many users.
242 .It Bq Er EDQUOT
243 Disc quota exceeded.
244 .It Bq Er ESTALE
245 Stale NFS file handle.
246 .It Bq Er EREMOTE
247 Too many levels of remote in path.
248 .It Bq Er EBADRPC
249 RPC struct is bad.
250 .It Bq Er ERPCMISMATCH
251 RPC version wrong.
252 .It Bq Er EPROGUNAVAIL
253 RPC program not available.
254 .It Bq Er EPROGMISMATCH
255 Program version wrong.
256 .It Bq Er EPROCUNAVAIL
257 Bad procedure for program.
258 .It Bq Er ENOLCK
259 No locks available.
260 .It Bq Er ENOSYS
261 Function not implemented.
262 .It Bq Er EFTYPE
263 Inappropriate file type or format.
264 .It Bq Er EAUTH
265 Authentication error.
266 .It Bq Er ENEEDAUTH
267 Need authenticator.
268 .El
269 .Sh SEE ALSO
270 .Xr example 1 ,
271 .Xr example 4 ,
272 .Xr mdoc 7
273 .Rs
274 .%A "A. B. Author"
275 .%T "Example RFC Title"
276 .%O RFC0000
277 .Re
278 .Rs
279 .%A "A. B. Author"
280 .%B "Example Book Title"
281 .%O ISBN-0-000-00000-0
282 .Re
283 .Rs
284 .%A "A. B. Author"
285 .%D "January 1997"
286 .%J "Example Journal Name"
287 .%T "Example Article Title"
288 .Re
289 .Sh STANDARDS
290 If the command conforms to some standard, such as
291 .St -p1003.2
292 or
293 .St -isoC ,
294 it should be noted here.
295 .Sh HISTORY
296 The
297 .Nm
298 manual page example first appeared in
299 .Fx 2.2 .
300 .Pp
301 Some other common
302 .Sx HISTORY
303 section examples are:
304 .Pp
305 The
306 .Nm
307 manual page example first appeared in
308 .Bx 4.4 .
309 .Pp
310 The
311 .Nm
312 manual page example first appeared in
313 .At v6 .
314 .Sh AUTHORS
315 This
316 manual page was written by
317 .An Mike Pritchard Aq Mt mpp@FreeBSD.org .
318 .Sh BUGS
319 The actual code for this function is vaporware.