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$
  26 .\"
  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
  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 The
 104 .Fn example
 105 function will fail if:
 106 .Bl -tag -width Er
 107 .It Bq Er EPERM
 108 Operation not permitted.
 109 .It Bq Er ENOENT
 110 No such file or directory.
 111 .It Bq Er ESRCH
 112 No such process.
 113 .It Bq Er EINTR
 114 Interrupted system call.
 115 .It Bq Er EIO
 116 Input/output error.
 117 .It Bq Er ENXIO
 118 Device not configured.
 119 .It Bq Er E2BIG
 120 Argument list too long.
 121 .It Bq Er ENOEXEC
 122 Exec format error.
 123 .It Bq Er EBADF
 124 Bad file descriptor.
 125 .It Bq Er ECHILD
 126 No child processes.
 127 .It Bq Er EDEADLK
 128 Resource deadlock avoided.
 129 .It Bq Er ENOMEM
 130 Cannot allocate memory.
 131 .It Bq Er EACCES
 132 Permission denied.
 133 .It Bq Er EFAULT
 134 Bad address.
 135 .It Bq Er ENOTBLK
 136 Block device required.
 137 .It Bq Er EBUSY
 138 Device busy.
 139 .It Bq Er EEXIST
 140 File exists.
 141 .It Bq Er EXDEV
 142 Cross-device link.
 143 .It Bq Er ENODEV
 144 Operation not supported by device.
 145 .It Bq Er ENOTDIR
 146 Not a directory.
 147 .It Bq Er EISDIR
 148 Is a directory.
 149 .It Bq Er EINVAL
 150 Invalid argument.
 151 .It Bq Er ENFILE
 152 Too many open files in system.
 153 .It Bq Er EMFILE
 154 Too many open files.
 155 .It Bq Er ENOTTY
 156 Inappropriate ioctl for device.
 157 .It Bq Er ETXTBSY
 158 Text file busy.
 159 .It Bq Er EFBIG
 160 File too large.
 161 .It Bq Er ENOSPC
 162 No space left on device.
 163 .It Bq Er ESPIPE
 164 Illegal seek.
 165 .It Bq Er EROFS
 166 Read-only file system.
 167 .It Bq Er EMLINK
 168 Too many links.
 169 .It Bq Er EPIPE
 170 Broken pipe.
 171 .It Bq Er EDOM
 172 Numerical argument out of domain.
 173 .It Bq Er ERANGE
 174 Result too large.
 175 .It Bq Er EAGAIN
 176 Resource temporarily unavailable.
 177 .It Bq Er EWOULDBLOCK
 178 Operation would block.
 179 .It Bq Er EINPROGRESS
 180 Operation now in progress.
 181 .It Bq Er EALREADY
 182 Operation already in progress.
 183 .It Bq Er ENOTSOCK
 184 Socket operation on non-socket.
 185 .It Bq Er EDESTADDRREQ
 186 Destination address required.
 187 .It Bq Er EMSGSIZE
 188 Message too long.
 189 .It Bq Er EPROTOTYPE
 190 Protocol wrong type for socket.
 191 .It Bq Er ENOPROTOOPT
 192 Protocol not available.
 193 .It Bq Er EPROTONOSUPPORT
 194 Protocol not supported.
 195 .It Bq Er ESOCKTNOSUPPORT
 196 Socket type not supported.
 197 .It Bq Er EOPNOTSUPP
 198 Operation not supported.
 199 .It Bq Er EPFNOSUPPORT
 200 Protocol family not supported.
 201 .It Bq Er EAFNOSUPPORT
 202 Address family not supported by protocol family.
 203 .It Bq Er EADDRINUSE
 204 Address already in use.
 205 .It Bq Er EADDRNOTAVAIL
 206 Cannot assign requested address.
 207 .It Bq Er ENETDOWN
 208 Network is down.
 209 .It Bq Er ENETUNREACH
 210 Network is unreachable.
 211 .It Bq Er ENETRESET
 212 Network dropped connection on reset.
 213 .It Bq Er ECONNABORTED
 214 Software causes connection abort.
 215 .It Bq Er ENOBUFS
 216 No buffer space available.
 217 .It Bq Er EISCONN
 218 Socket is already connected.
 219 .It Bq Er ENOTCONN
 220 Socket is not connected.
 221 .It Bq Er ESHUTDOWN
 222 Cannot send after socket shutdown.
 223 .It Bq Er ETOOMANYREFS
 224 Too many references: cannot splice.
 225 .It Bq Er ETIMEDOUT
 226 Operation timed out.
 227 .It Bq Er ECONNREFUSED
 228 Connection refused.
 229 .It Bq Er ELOOP
 230 Too many levels of symbolic links.
 231 .It Bq Er ENAMETOOLONG
 232 File name too long.
 233 .It Bq Er EHOSTDOWN
 234 Host is down.
 235 .It Bq Er EHOSTUNREACH
 236 No route to host.
 237 .It Bq Er ENOTEMPTY
 238 Directory not empty.
 239 .It Bq Er EPROCLIM
 240 Too many processes.
 241 .It Bq Er EUSERS
 242 Too many users.
 243 .It Bq Er EDQUOT
 244 Disc quota exceeded.
 245 .It Bq Er ESTALE
 246 Stale NFS file handle.
 247 .It Bq Er EREMOTE
 248 Too many levels of remote in path.
 249 .It Bq Er EBADRPC
 250 RPC struct is bad.
 251 .It Bq Er ERPCMISMATCH
 252 RPC version wrong.
 253 .It Bq Er EPROGUNAVAIL
 254 RPC program not available.
 255 .It Bq Er EPROGMISMATCH
 256 Program version wrong.
 257 .It Bq Er EPROCUNAVAIL
 258 Bad procedure for program.
 259 .It Bq Er ENOLCK
 260 No locks available.
 261 .It Bq Er ENOSYS
 262 Function not implemented.
 263 .It Bq Er EFTYPE
 264 Inappropriate file type or format.
 265 .It Bq Er EAUTH
 266 Authentication error.
 267 .It Bq Er ENEEDAUTH
 268 Need authenticator.
 269 .It Bq Er EIDRM
 270 Identifier removed.
 271 .It Bq Er ENOMSG
 272 No message of desired type.
 273 .It Bq Er EOVERFLOW
 274 Value too large to be stored in data type.
 275 .It Bq Er ECANCELED
 276 Operation canceled.
 277 .It Bq Er EILSEQ
 278 Illegal byte sequence.
 279 .It Bq Er ENOATTR
 280 Attribute not found.
 281 .It Bq Er EDOOFUS
 282 Programming error.
 283 .El
 284 .Sh SEE ALSO
 285 .Xr example 1 ,
 286 .Xr example 4 ,
 287 .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
 305 .Sh STANDARDS
 306 If the function conforms to some standard, such as
 307 .St -p1003.1-2004
 308 or
 309 .St -isoC-99 ,
 310 it should be noted here.
 311 .Sh HISTORY
 312 The
 313 .Nm
 314 manual page example first appeared in
 315 .Fx 2.2 .
 316 .Pp
 317 Some other common
 318 .Sx HISTORY
 319 section examples are:
 320 .Pp
 321 The
 322 .Nm
 323 manual page example first appeared in
 324 .Bx 4.4 .
 325 .Pp
 326 The
 327 .Nm
 328 manual page example first appeared in
 329 .At v6 .
 330 .Sh AUTHORS
 331 This
 332 manual page was written by
 333 .An Mike Pritchard Aq mpp@FreeBSD.org .
 334 .Sh BUGS
 335 The actual code for this function is vaporware.