Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NAL_ADDRESS_NEW(2)		   distcache		    NAL_ADDRESS_NEW(2)

NAME
       NAL_ADDRESS_new,	NAL_ADDRESS_free, NAL_ADDRESS_create, NAL_AD-
       DRESS_set_def_buffer_size, NAL_ADDRESS_can_connect, NAL_AD-
       DRESS_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	func-
       tions. 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_CONNEC-
       TION objects that are assigned connections from the listener will like-
       wise have the given default size	for its	buffers. See the "NOTES" sec-
       tion 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 deter-
       mine 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 de-
       fault 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 do-
       main 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_con-
	   nect() 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 cor-
	   rectly 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 Crypto-
       graphic Appliances Incorporated.	Since the project was released into
       open source, it has a home page and a project environment where devel-
       opment, 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)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | NOTES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=NAL_ADDRESS_new&sektion=2&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help