mdoc(7) police: tidy up the formatting.

1 files changed, 115 insertions, 81 deletions

diff --git a/lib/libradius/libradius.3 b/lib/libradius/libradius.3
index 9291c38..2e675bc 100644
--- a/lib/libradius/libradius.3
+++ b/lib/libradius/libradius.3
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd October 30, 1999
+.Dd June 12, 2002
 .Dt LIBRADIUS 3
 .Os
 .Sh NAME
@@ -32,11 +32,11 @@
 .Nd RADIUS client library
 .Sh SYNOPSIS
 .In radlib.h
-.Ft struct rad_handle *
+.Ft "struct rad_handle *"
 .Fn rad_acct_open "void"
 .Ft int
 .Fn rad_add_server "struct rad_handle *h" "const char *host" "int port" "const char *secret" "int timeout" "int max_tries"
-.Ft struct rad_handle *
+.Ft "struct rad_handle *"
 .Fn rad_auth_open "void"
 .Ft void
 .Fn rad_close "struct rad_handle *h"
@@ -46,7 +46,7 @@
 .Fn rad_continue_send_request "struct rad_handle *h" "int selected" "int *fd" "struct timeval *tv"
 .Ft int
 .Fn rad_create_request "struct rad_handle *h" "int code"
-.Ft struct in_addr
+.Ft "struct in_addr"
 .Fn rad_cvt_addr "const void *data"
 .Ft u_int32_t
 .Fn rad_cvt_int "const void *data"
@@ -78,24 +78,25 @@
 .Fn rad_request_authenticator "struct rad_handle *h" "char *buf" "size_t len"
 .Ft int
 .Fn rad_send_request "struct rad_handle *h"
-.Ft const char *
+.Ft "const char *"
 .Fn rad_server_secret "struct rad_handle *h"
-.Ft const char *
+.Ft "const char *"
 .Fn rad_strerror "struct rad_handle *h"
 .Sh DESCRIPTION
 The
 .Nm
 library implements the client side of the Remote Authentication Dial
-In User Service (RADIUS).  RADIUS, defined in RFCs 2138 and 2139,
+In User Service (RADIUS).
+RADIUS, defined in RFCs 2138 and 2139,
 allows clients to perform authentication and accounting by means of
 network requests to remote servers.
-.Sh INITIALIZATION
+.Ss Initialization
 To use the library, an application must first call
 .Fn rad_auth_open
 or
 .Fn rad_acct_open
 to obtain a
-.Va struct rad_handle * ,
+.Vt "struct rad_handle *" ,
 which provides the context for subsequent operations.
 The former function is used for RADIUS authentication and the
 latter is used for RADIUS accounting.
@@ -103,7 +104,8 @@ Calls to
 .Fn rad_auth_open
 and
 .Fn rad_acct_open
-always succeed unless insufficient virtual memory is available.  If
+always succeed unless insufficient virtual memory is available.
+If
 the necessary memory cannot be allocated, the functions return
 .Dv NULL .
 For compatibility with earlier versions of this library,
@@ -112,7 +114,8 @@ is provided as a synonym for
 .Fn rad_auth_open .
 .Pp
 Before issuing any RADIUS requests, the library must be made aware
-of the servers it can contact.  The easiest way to configure the
+of the servers it can contact.
+The easiest way to configure the
 library is to call
 .Fn rad_config .
 .Fn rad_config
@@ -120,7 +123,7 @@ causes the library to read a configuration file whose format is
 described in
 .Xr radius.conf 5 .
 The pathname of the configuration file is passed as the
-.Va file
+.Fa file
 argument to
 .Fn rad_config .
 This argument may also be given as
@@ -129,38 +132,46 @@ in which case the standard configuration file
 .Pa /etc/radius.conf
 is used.
 .Fn rad_config
-returns 0 on success, or -1 if an error occurs.
+returns 0 on success, or \-1 if an error occurs.
 .Pp
 The library can also be configured programmatically by calls to
 .Fn rad_add_server .
 The
-.Va host
+.Fa host
 parameter specifies the server host, either as a fully qualified
 domain name or as a dotted-quad IP address in text form.
 The
-.Va port
-parameter specifies the UDP port to contact on the server.  If
-.Va port
+.Fa port
+parameter specifies the UDP port to contact on the server.
+If
+.Fa port
 is given as 0, the library looks up the
 .Ql radius/udp
 or
 .Ql radacct/udp
-service in the network services database, and uses the port found
-there.  If no entry is found, the library uses the standard RADIUS
+service in the network
+.Xr services 5
+database, and uses the port found
+there.
+If no entry is found, the library uses the standard RADIUS
 ports, 1812 for authentication and 1813 for accounting.
 The shared secret for the server host is passed to the
-.Va secret
+.Fa secret
 parameter.
-It may be any NUL-terminated string of bytes.  The RADIUS protocol
+It may be any
+.Dv NUL Ns -terminated
+string of bytes.
+The RADIUS protocol
 ignores all but the leading 128 bytes of the shared secret.
 The timeout for receiving replies from the server is passed to the
-.Va timeout
-parameter, in units of seconds.  The maximum number of repeated
+.Fa timeout
+parameter, in units of seconds.
+The maximum number of repeated
 requests to make before giving up is passed into the
-.Va max_tries
+.Fa max_tries
 parameter.
 .Fn rad_add_server
-returns 0 on success, or -1 if an error occurs.
+returns 0 on success, or \-1 if an error occurs.
 .Pp
 .Fn rad_add_server
 may be called multiple times, and it may be used together with
@@ -168,56 +179,63 @@ may be called multiple times, and it may be used together with
 At most 10 servers may be specified.
 When multiple servers are given, they are tried in round-robin
 fashion until a valid response is received, or until each server's
-.Va max_tries
+.Fa max_tries
 limit has been reached.
-.Sh CREATING A RADIUS REQUEST
+.Ss Creating a RADIUS Request
 A RADIUS request consists of a code specifying the kind of request,
-and zero or more attributes which provide additional information.  To
+and zero or more attributes which provide additional information.
+To
 begin constructing a new request, call
 .Fn rad_create_request .
 In addition to the usual
-.Va struct rad_handle * ,
+.Vt "struct rad_handle *" ,
 this function takes a
-.Va code
-parameter which specifies the type of the request.  Most often this
+.Fa code
+parameter which specifies the type of the request.
+Most often this
 will be
 .Dv RAD_ACCESS_REQUEST .
 .Fn rad_create_request
-returns 0 on success, or -1 on if an error occurs.
+returns 0 on success, or \-1 on if an error occurs.
 .Pp
 After the request has been created with
 .Fn rad_create_request ,
-attributes can be attached to it.  This is done through calls to
+attributes can be attached to it.
+This is done through calls to
 .Fn rad_put_addr ,
 .Fn rad_put_int ,
 and
 .Fn rad_put_string .
 Each accepts a
-.Va type
+.Fa type
 parameter identifying the attribute, and a value which may be
-an Internet address, an integer, or a NUL-terminated string,
+an Internet address, an integer, or a
+.Dv NUL Ns -terminated
+string,
 respectively.
 Alternatively,
 .Fn rad_put_vendor_addr ,
 .Fn rad_put_vendor_int
 or
 .Fn rad_put_vendor_string
-may be used to specify vendor specific attributes.  Vendor specific
+may be used to specify vendor specific attributes.
+Vendor specific
 definitions may be found in
-.In radlib_vs.h
+.Aq Pa radlib_vs.h
 .Pp
 The library also provides a function
 .Fn rad_put_attr
-which can be used to supply a raw, uninterpreted attribute.  The
-.Va data
+which can be used to supply a raw, uninterpreted attribute.
+The
+.Fa data
 argument points to an array of bytes, and the
-.Va len
+.Fa len
 argument specifies its length.
 .Pp
 The
 .Fn rad_put_X
-functions return 0 on success, or -1 if an error occurs.
-.Sh SENDING THE REQUEST AND RECEIVING THE RESPONSE
+functions return 0 on success, or \-1 if an error occurs.
+.Ss Sending the Request and Receiving the Response
 After the RADIUS request has been constructed, it is sent either by means of
 .Fn rad_send_request
 or by a combination of calls to
@@ -239,19 +257,20 @@ or
 .Dv RAD_ACCESS_CHALLENGE .
 If no valid response is received,
 .Fn rad_send_request
-returns -1.
+returns \-1.
 .Pp
 As an alternative, if you do not wish to block waiting for a response,
 .Fn rad_init_send_request
 and
 .Fn rad_continue_send_request
-may be used instead.  If a reply is received from the RADIUS server or a
+may be used instead.
+If a reply is received from the RADIUS server or a
 timeout occurs, these functions return a value as described for
 .Fn rad_send_request .
 Otherwise, a value of zero is returned and the values pointed to by
-.Ar fd
+.Fa fd
 and
-.Ar tv
+.Fa tv
 are set to the descriptor and timeout that should be passed to
 .Xr select 2 .
 .Pp
@@ -262,19 +281,22 @@ as long as a return value of zero is given.
 Between each call, the application should call
 .Xr select 2 ,
 passing
-.Ar *fd
+.Fa *fd
 as a read descriptor and timing out after the interval specified by
-.Ar tv .
-When select returns,
+.Fa tv .
+When
+.Xr select 2
+returns,
 .Fn rad_continue_send_request
 should be called with
-.Ar selected
+.Fa selected
 set to a non-zero value if
 .Xr select 2
 indicated that the descriptor is readable.
 .Pp
 Like RADIUS requests, each response may contain zero or more
-attributes.  After a response has been received successfully by
+attributes.
+After a response has been received successfully by
 .Fn rad_send_request
 or
 .Fn rad_continue_send_request ,
@@ -285,10 +307,11 @@ Each time
 is called, it gets the next attribute from the current response, and
 stores a pointer to the data and the length of the data via the
 reference parameters
-.Va data
+.Fa data
 and
-.Va len ,
-respectively.  Note that the data resides in the response itself,
+.Fa len ,
+respectively.
+Note that the data resides in the response itself,
 and must not be modified.
 A successful call to
 .Fn rad_get_attr
@@ -296,7 +319,7 @@ returns the RADIUS attribute type.
 If no more attributes remain in the current response,
 .Fn rad_get_attr
 returns 0.
-If an error such as a malformed attribute is detected, -1 is
+If an error such as a malformed attribute is detected, \-1 is
 returned.
 .Pp
 If
@@ -307,9 +330,9 @@ returns
 may be called to determine the vendor.
 The vendor specific RADIUS attribute type is returned.
 The reference parameters
-.Va data
+.Fa data
 and
-.Va len
+.Fa len
 (as returned from
 .Fn rad_get_attr )
 are passed to
@@ -329,13 +352,17 @@ and optionally
 In the case of
 .Fn rad_cvt_string ,
 the length
-.Va len
-must also be given.  These functions interpret the attribute as an
+.Fa len
+must also be given.
+These functions interpret the attribute as an
 Internet address, an integer, or a string, respectively, and return
 its value.
 .Fn rad_cvt_string
-returns its value as a NUL-terminated string in dynamically
-allocated memory.  The application should free the string using
+returns its value as a
+.Dv NUL Ns -terminated
+string in dynamically
+allocated memory.
+The application should free the string using
 .Xr free 3
 when it is no longer needed.
 .Pp
@@ -354,36 +381,38 @@ function may be used to obtain the Request-Authenticator attribute value
 associated with the current RADIUS server according to the supplied
 rad_handle.
 The target buffer
-.Ar buf
+.Fa buf
 of length
-.Ar len
+.Fa len
 must be supplied and should be at least 16 bytes.
 The return value is the number of bytes written to
-.Ar buf
-or -1 to indicate that
-.Ar len
+.Fa buf
+or \-1 to indicate that
+.Fa len
 was not large enough.
 .Pp
 The
 .Fn rad_server_secret
 returns the secret shared with the current RADIUS server according to the
 supplied rad_handle.
-.Sh OBTAINING ERROR MESSAGES
+.Ss Obtaining Error Messages
 Those functions which accept a
-.Va struct rad_handle *
-argument record an error message if they fail.  The error message
+.Vt "struct rad_handle *"
+argument record an error message if they fail.
+The error message
 can be retrieved by calling
 .Fn rad_strerror .
 The message text is overwritten on each new error for the given
-.Va struct rad_handle * .
+.Vt "struct rad_handle *" .
 Thus the message must be copied if it is to be preserved through
 subsequent library calls using the same handle.
-.Sh CLEANUP
+.Ss Cleanup
 To free the resources used by the RADIUS library, call
 .Fn rad_close .
 .Sh RETURN VALUES
-The following functions return a non-negative value on success.  If
-they detect an error, they return -1 and record an error message
+The following functions return a non-negative value on success.
+If
+they detect an error, they return \-1 and record an error message
 which can be retrieved using
 .Fn rad_strerror .
 .Pp
@@ -414,7 +443,8 @@ which can be retrieved using
 .Pp
 The following functions return a
 .No non- Ns Dv NULL
-pointer on success.  If they are unable to allocate sufficient
+pointer on success.
+If they are unable to allocate sufficient
 virtual memory, they return
 .Dv NULL ,
 without recording an error message.
@@ -428,24 +458,28 @@ without recording an error message.
 .Fn rad_cvt_string
 .El
 .Sh FILES
-.Pa /etc/radius.conf
+.Bl -tag -width indent
+.It Pa /etc/radius.conf
+.El
 .Sh SEE ALSO
 .Xr radius.conf 5
 .Rs
-.%A C. Rigney, et al
+.%A "C. Rigney, et al"
 .%T "Remote Authentication Dial In User Service (RADIUS)"
-.%O RFC 2138
+.%O "RFC 2138"
 .Re
 .Rs
-.%A C. Rigney
-.%T RADIUS Accounting
-.%O RFC 2139
+.%A "C. Rigney"
+.%T "RADIUS Accounting"
+.%O "RFC 2139"
 .Re
 .Sh AUTHORS
+.An -nosplit
 This software was originally written by
 .An John Polstra ,
 and donated to the
 .Fx
 project by Juniper Networks, Inc.
-Oleg Semyonov subsequently added the ability to perform RADIUS
+.An Oleg Semyonov
+subsequently added the ability to perform RADIUS
 accounting.