share/examples/mdoc/example.3

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