gai.conf.5: New page documenting gai.conf

Taken from Red Hat downstream pages

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man5/gai.conf.5 b/man5/gai.conf.5
new file mode 100644 (file)
index 0000000..bd7902e
--- /dev/null
+++ b/man5/gai.conf.5
@@ -0,0 +1,98 @@
+.\" A man page for gai.conf. -*- nroff -*-
+.\"
+.\" Copyright (C) 2006 Red Hat, Inc. All rights reserved.
+.\"
+.\" This copyrighted material is made available to anyone wishing to use,
+.\" modify, copy, or redistribute it subject to the terms and conditions of the
+.\" GNU General Public License v.2.
+.\"
+.\" This program is distributed in the hope that it will be useful, but WITHOUT
+.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+.\" FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for
+.\" more details.
+.\"
+.\" You should have received a copy of the GNU General Public License along
+.\" with this program; if not, write to the Free Software Foundation, Inc.,
+.\" 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+.\"
+.\" Author: Ulrich Drepper <drepper@redhat.com>
+.TH gai.conf 5 "May 2006" gai.conf
+
+.SH NAME
+gai.conf \- getaddrinfo(3) configuration file
+
+.SH DESCRIPTION
+A call to
+.BR getaddrinfo (3)
+might return multiple answers.  According to RFC 3484 these answers must
+be sorted so that the answer with the highest success rate is first in
+the list.  The RFC provides and algorithm for the sorting.  The static
+rules are not always adequate, though.  For this reason the RFC also
+requires that system administrators get the chance to dynamically change
+the sorting.  For the glibc implementation this can be achieved with
+the
+.BR /etc/gai.conf
+file.
+.PP
+Each line in the configuration file consists of a keyword and its
+parameters.  White spaces in any place are ignored.  Lines starting
+with `#' are comments and are ignored.
+.PP
+The keywords currently recognized are:
+.TP
+\fBlabel\fR \fInetmask\fR \fIprecedence\fR
+The value is added to the label table used in the RFC 3484 sorting.
+If any \fBlabel\fR definition is present in the configuration file
+is present the default table is not used.  All the label definitions
+of the default table which are to be maintained have to be duplicated.
+Following the keyword the line has to contain a network mask and a label
+value.
+
+.TP
+\fBprecedence\fR \fInetmask\fR \fIprecedence\fR
+This  keyword is similar to \fBlabel\fR but instead the value is added
+to the precedence table as specified in RFC 3484.  Once again, the
+presence of a single \fBprecedence\fR line in the configuration file
+causes the default table to not be used.
+
+.TP
+\fBreload\fR <\fByes\fR|\fBno\fR>
+This keyword control whether a process checks whether the configuration
+file has been changes since the last time it was read.  If the value is
+`\fByes\fR' the file is re-read.  This might cause problems in multi-threaded
+applications and is generally a bad idea.  The default is `\fBno\fR'.
+
+.TP
+\fBscopev4\fR \fImask\fR \fIvalue\fR
+Add another rule to the RFC 3484 scope table for IPv4 address.
+By default the scope IDs described in section 3.2 in 
+RFC 3438 are used.
+Changing these defaults should hardly ever be necessary.
+
+.SH EXAMPLE
+
+The default table according to RFC 3484 would be specified with the
+following configuration file:
+
+.nf
+label  ::1/128       0
+label  ::/0          1
+label  2002::/16     2
+label ::/96          3
+label ::ffff:0:0/96  4
+precedence  ::1/128       50
+precedence  ::/0          40
+precedence  2002::/16     30
+precedence ::/96          20
+precedence ::ffff:0:0/96  10
+
+
+.SH FILES
+\fI/etc/gai.conf\fR
+
+.SH AUTHOR
+Ulrich Drepper <drepper@redhat.com>
+
+.SH SEE ALSO
+.BR getaddrinfo(3),
+RFC 3484