share/examples/mdoc/example.3

   1 .\" Copyright (c) [year] [your name]
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  13 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  14 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  15 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  16 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  17 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  18 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  19 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  20 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  21 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  22 .\" SUCH DAMAGE.
  23 .\"
  24 .\" $FreeBSD$
  25 .\"
  26 .\" Note: The date here should be updated whenever a non-trivial
  27 .\" change is made to the manual page.
  28 .Dd July 30, 2004
  29 .Dt EXAMPLE 3
  30 .Os
  31 .Sh NAME
  32 .Nm example
  33 .Nd "example library function manual page"
  34 .Sh LIBRARY
  35 .\" Note: list of available libraries is available in mdoc(7)
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In example.h
  39 .Ft int
  40 .Fn example "char *ptr" "int mode"
  41 .Sh DESCRIPTION
  42 This is an example library function manual page for the
  43 .Fn example
  44 function.
  45 It is intended that this example can be used as a template
  46 when writing a new manual page.
  47 .Pp
  48 The
  49 .Fn example
  50 function takes two arguments:
  51 .Fa ptr
  52 and
  53 .Fa mode .
  54 The argument
  55 .Fa mode
  56 may have one of the following values:
  57 .Bl -tag -width ".Dv EXAMPLE_ONE"
  58 .It Dv EXAMPLE_ONE
  59 First example of a defined variable.
  60 .Dv EXAMPLE_ONE
  61 is described below.
  62 .It Dv EXAMPLE_TWO
  63 Second example.
  64 .El
  65 .Pp
  66 The above values are defined in
  67 .In example.h
  68 as follows:
  69 .Bd -literal
  70 #define EXAMPLE_ONE  1
  71 #define EXAMPLE_TWO  2
  72 .Ed
  73 .Sh IMPLEMENTATION NOTES
  74 The
  75 .Fn example
  76 function is not actually implemented.
  77 .Sh RETURN VALUES
  78 .Rv -std example
  79 .Sh ENVIRONMENT
  80 The
  81 .Fn example
  82 library function ignores the
  83 .Ev EXAMPLE
  84 environment variable.
  85 .Sh FILES
  86 .Bl -tag -width ".Pa /dev/null" -compact
  87 .It Pa /dev/null
  88 Example of a file in the
  89 .Sx FILES
  90 section.
  91 .El
  92 .Sh DIAGNOSTICS
  93 None.
  94 .Sh COMPATIBILITY
  95 The
  96 .Fn example
  97 function has no known compatibility issues.
  98 .Sh ERRORS
  99 .\" Delete any errno's that are not returned by your
 100 .\" function or system call and then tailor the
 101 .\" remaining text as needed.
 102 The
 103 .Fn example
 104 function 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 .It Bq Er EIDRM
 269 Identifier removed.
 270 .It Bq Er ENOMSG
 271 No message of desired type.
 272 .It Bq Er EOVERFLOW
 273 Value too large to be stored in data type.
 274 .It Bq Er ECANCELED
 275 Operation canceled.
 276 .It Bq Er EILSEQ
 277 Illegal byte sequence.
 278 .It Bq Er ENOATTR
 279 Attribute not found.
 280 .It Bq Er EDOOFUS
 281 Programming error.
 282 .El
 283 .Sh SEE ALSO
 284 .Xr example 1 ,
 285 .Xr example 4 ,
 286 .Xr mdoc 7 ,
 287 .Xr example 9
 288 .Rs
 289 .%A "A. B. Author"
 290 .%T "Example RFC Title"
 291 .%O RFC0000
 292 .Re
 293 .Rs
 294 .%A "A. B. Author"
 295 .%B "Example Book Title"
 296 .%O ISBN-0-000-00000-0
 297 .Re
 298 .Rs
 299 .%A "A. B. Author"
 300 .%D "January 1997"
 301 .%J "Example Journal Name"
 302 .%T "Example Article Title"
 303 .Re
 304 .Sh STANDARDS
 305 If the function conforms to some standard, such as
 306 .St -p1003.1-2004
 307 or
 308 .St -isoC-99 ,
 309 it should be noted here.
 310 .Sh HISTORY
 311 The
 312 .Nm
 313 manual page example first appeared in
 314 .Fx 2.2 .
 315 .Pp
 316 Some other common
 317 .Sx HISTORY
 318 section examples are:
 319 .Pp
 320 The
 321 .Nm
 322 manual page example first appeared in
 323 .Bx 4.4 .
 324 .Pp
 325 The
 326 .Nm
 327 manual page example first appeared in
 328 .At v6 .
 329 .Sh AUTHORS
 330 This
 331 manual page was written by
 332 .An Mike Pritchard Aq Mt mpp@FreeBSD.org .
 333 .Sh BUGS
 334 The actual code for this function is vaporware.