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 .Aq Pa 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 mpp@FreeBSD.org .
 318 .Sh BUGS
 319 The actual code for this function is vaporware.