.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "NAL_ADDRESS_NEW 2"
.TH NAL_ADDRESS_NEW 2 "2004.03.23" "1.4.5" "distcache"
.SH "NAME"
NAL_ADDRESS_new, NAL_ADDRESS_free, NAL_ADDRESS_create, NAL_ADDRESS_set_def_buffer_size, NAL_ADDRESS_can_connect, NAL_ADDRESS_can_listen \- libnal addressing functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <libnal/nal.h>
.Ve
.PP
.Vb 10
\& NAL_ADDRESS *NAL_ADDRESS_new(void);
\& void NAL_ADDRESS_free(NAL_ADDRESS *addr);
\& void NAL_ADDRESS_reset(NAL_ADDRESS *addr);
\& int NAL_ADDRESS_create(NAL_ADDRESS *addr, const char *addr_string,
\&                        unsigned int def_buffer_size);
\& unsigned int NAL_ADDRESS_get_def_buffers_size(const NAL_ADDRESS *addr);
\& int NAL_ADDRESS_set_def_buffer_size(NAL_ADDRESS *addr,
\&                                     unsigned int def_buffer_size);
\& int NAL_ADDRESS_can_connect(const NAL_ADDRESS *addr);
\& int NAL_ADDRESS_can_listen(const NAL_ADDRESS *addr);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fINAL_ADDRESS_new()\fR allocates and initialises a new \fB\s-1NAL_ADDRESS\s0\fR object.
.PP
\&\fINAL_ADDRESS_free()\fR destroys a \fB\s-1NAL_ADDRESS\s0\fR object.
.PP
\&\fINAL_ADDRESS_reset()\fR will, if necessary, cleanup any prior state in \fBaddr\fR so that
it can be reused in \fINAL_ADDRESS_create()\fR. Internally, there are other
optimisations and benefits to using \fINAL_ADDRESS_reset()\fR instead of
\&\fINAL_ADDRESS_free()\fR and \fINAL_ADDRESS_new()\fR \- the implementation can try to avoid
repeated reallocation and reinitialisation of state, only doing full cleanup
and reinitialisation when necessary.
.PP
\&\fINAL_ADDRESS_create()\fR will attempt to parse a network address from the string
constant provided in \fBaddr_string\fR. If this succeeds, then \fBaddr\fR will
represent the given network address for use in other libnal functions. The
significance of \fBdef_buffer_size\fR is that any \fB\s-1NAL_CONNECTION\s0\fR object created
with \fBaddr\fR will inherent \fBdef_buffer_size\fR as the default size for its read
and write buffers (see \fINAL_CONNECTION_set_size\fR\|(2)). If \fBaddr\fR is used to
create a \fB\s-1NAL_LISTENER\s0\fR object, then any \fB\s-1NAL_CONNECTION\s0\fR objects that are
assigned connections from the listener will likewise have the given default
size for its buffers. See the \*(L"\s-1NOTES\s0\*(R" section for information on the syntax of
\&\fBaddr\fR.
.PP
\&\fINAL_ADDRESS_set_def_buffer_size()\fR sets \fBdef_buffer_size\fR as the default buffer
size in \fBaddr\fR. This operation is built into \fINAL_ADDRESS_create()\fR already.
\&\fINAL_ADDRESS_get_def_buffer_size()\fR returns the current default buffer size of
\&\fBaddr\fR.
.PP
\&\fINAL_ADDRESS_can_connect()\fR will indicate whether the address represented by
\&\fBaddr\fR is of an appropriate form for creating a \fB\s-1NAL_CONNECTION\s0\fR object.
\&\fINAL_ADDRESS_can_listen()\fR likewise indicates if \fBaddr\fR is appopriate for
creating a \fB\s-1NAL_LISTENER\s0\fR object. In other words, these functions determine
whether the address can be ``connected to'' or ``listened on''. Depending on
the type of transport and the string from which \fBaddr\fR was parsed, some
addresses are only good for connecting or listening whereas others can be good
for both. See \*(L"\s-1NOTES\s0\*(R".
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fINAL_ADDRESS_new()\fR returns a valid \fB\s-1NAL_ADDRESS\s0\fR object on success, \s-1NULL\s0
otherwise.
.PP
\&\fINAL_ADDRESS_free()\fR and \fINAL_ADDRESS_reset()\fR have no return value.
.PP
\&\fINAL_ADDRESS_get_def_buffer_size()\fR returns the size of the current default buffer
size in a \fB\s-1NAL_ADDRESS\s0\fR object.
.PP
All other \fB\s-1NAL_ADDRESS\s0\fR functions return zero for failure or false, and
non-zero for success or true.
.SH "NOTES"
.IX Header "NOTES"
The string syntax implemented by \fIlibnal\fR is used by all the \fIdistcache\fR
libraries and tools. At the time of writing, only TCP/IPv4 and unix domain
sockets were supported as underlying transports and so likewise the implemented
syntax handling only supported these two forms.
.IP "TCP/IPv4 addresses" 4
.IX Item "TCP/IPv4 addresses"
The syntax for TCP/IPv4 addresses has two forms, depending on whether you
specify a hostname (or alternatively a dotted-numeric \s-1IP\s0 address) with the port
number or just the port number on its own. Eg. to represent port 9001, one uses;
.Sp
.Vb 1
\&    IP:9001
.Ve
.Sp
whereas to specify a hostname or \s-1IP\s0 address with it, the syntax is;
.Sp
.Vb 2
\&    IP:machinename.domain:9001
\&    IP:192.168.0.1:9001
.Ve
.Sp
Either form of TCP/IPv4 address is generally valid for creating a
\&\fB\s-1NAL_LISTENER\s0\fR object, although it will depend at run-time on the situation in
the system \- ie. whether privileges exist to listen on the port, whether the
port is already in use, whether the specified hostname or \s-1IP\s0 address is bound
to a running network interface that can be listened on, etc. For creating a
\&\fB\s-1NAL_CONNECTION\s0\fR object, an address must be specified.  This is why the
\&\fINAL_CONNECTION_can_connect()\fR and \fINAL_CONNECTION_can_listen()\fR helper functions
exist \- to detect whether the syntax used is logical for the intended use.
Failures to set up network resources afterwards will in turn say whether the
given address data is possible within the host system.
.IP "unix domain addresses" 4
.IX Item "unix domain addresses"
There is only one syntax for unix domain addresses, and so any correctly parsed
address string is in theory valid for connecting to or listening on. The form is;
.Sp
.Vb 1
\&    UNIX:/path/to/socket
.Ve
.Sp
This represents the path to the socket in the file system.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fINAL_CONNECTION_new\fR\|(2) \- Functions for the \s-1NAL_CONNECTION\s0 type.
.PP
\&\fINAL_LISTENER_new\fR\|(2) \- Functions for the \s-1NAL_LISTENER\s0 type.
.PP
\&\fINAL_SELECTOR_new\fR\|(2) \- Functions for the \s-1NAL_SELECTOR\s0 type.
.PP
\&\fINAL_BUFFER_new\fR\|(2) \- Functions for the \s-1NAL_BUFFER\s0 type.
.PP
\&\fIdistcache\fR\|(8) \- Overview of the distcache architecture.
.PP
\&\fIhttp://www.distcache.org/\fR \- Distcache home page.
.SH "AUTHOR"
.IX Header "AUTHOR"
This toolkit was designed and implemented by Geoff Thorpe for Cryptographic
Appliances Incorporated. Since the project was released into open source, it
has a home page and a project environment where development, mailing lists, and
releases are organised. For problems with the software or this man page please
check for new releases at the project web-site below, mail the users mailing
list described there, or contact the author at \fIgeoff@geoffthorpe.net\fR.
.PP
Home Page: \fIhttp://www.distcache.org\fR