NAL_ADDRESS_new

NAL_ADDRESS_NEW(2)                 distcache                NAL_ADDRESS_NEW(2)



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

SYNOPSIS
        #include <libnal/nal.h>

        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);

DESCRIPTION
       NAL_ADDRESS_new() allocates and initialises a new NAL_ADDRESS object.

       NAL_ADDRESS_free() destroys a NAL_ADDRESS object.

       NAL_ADDRESS_reset() will, if necessary, cleanup any prior state in addr
       so that it can be reused in NAL_ADDRESS_create(). Internally, there are
       other optimisations and benefits to using NAL_ADDRESS_reset() instead
       of NAL_ADDRESS_free() and NAL_ADDRESS_new() - the implementation can
       try to avoid repeated reallocation and reinitialisation of state, only
       doing full cleanup and reinitialisation when necessary.

       NAL_ADDRESS_create() will attempt to parse a network address from the
       string constant provided in addr_string. If this succeeds, then addr
       will represent the given network address for use in other libnal
       functions. The significance of def_buffer_size is that any
       NAL_CONNECTION object created with addr will inherent def_buffer_size
       as the default size for its read and write buffers (see
       NAL_CONNECTION_set_size(2)). If addr is used to create a NAL_LISTENER
       object, then any NAL_CONNECTION objects that are assigned connections
       from the listener will likewise have the given default size for its
       buffers. See the "NOTES" section for information on the syntax of addr.

       NAL_ADDRESS_set_def_buffer_size() sets def_buffer_size as the default
       buffer size in addr. This operation is built into NAL_ADDRESS_create()
       already.  NAL_ADDRESS_get_def_buffer_size() returns the current default
       buffer size of addr.

       NAL_ADDRESS_can_connect() will indicate whether the address represented
       by addr is of an appropriate form for creating a NAL_CONNECTION object.
       NAL_ADDRESS_can_listen() likewise indicates if addr is appopriate for
       creating a NAL_LISTENER 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 addr
       was parsed, some addresses are only good for connecting or listening
       whereas others can be good for both. See "NOTES".

RETURN VALUES
       NAL_ADDRESS_new() returns a valid NAL_ADDRESS object on success, NULL
       otherwise.

       NAL_ADDRESS_free() and NAL_ADDRESS_reset() have no return value.

       NAL_ADDRESS_get_def_buffer_size() returns the size of the current
       default buffer size in a NAL_ADDRESS object.

       All other NAL_ADDRESS functions return zero for failure or false, and
       non-zero for success or true.

NOTES
       The string syntax implemented by libnal is used by all the distcache
       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.

       TCP/IPv4 addresses
           The syntax for TCP/IPv4 addresses has two forms, depending on
           whether you specify a hostname (or alternatively a dotted-numeric
           IP address) with the port number or just the port number on its
           own. Eg. to represent port 9001, one uses;

               IP:9001

           whereas to specify a hostname or IP address with it, the syntax is;

               IP:machinename.domain:9001
               IP:192.168.0.1:9001

           Either form of TCP/IPv4 address is generally valid for creating a
           NAL_LISTENER 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 IP address is bound to a running network interface that
           can be listened on, etc. For creating a NAL_CONNECTION object, an
           address must be specified.  This is why the
           NAL_CONNECTION_can_connect() and NAL_CONNECTION_can_listen() 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.

       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;

               UNIX:/path/to/socket

           This represents the path to the socket in the file system.

SEE ALSO
       NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.

       NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.

       NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.

       NAL_BUFFER_new(2) - Functions for the NAL_BUFFER type.

       distcache(8) - Overview of the distcache architecture.

       http://www.distcache.org/ - Distcache home page.

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 geoff@geoffthorpe.net.

       Home Page: http://www.distcache.org



1.4.5                             2004.03.23                NAL_ADDRESS_NEW(2)