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