1NAL_ADDRESS_NEW(2) distcache NAL_ADDRESS_NEW(2)
2
6 NAL_ADDRESS_new, NAL_ADDRESS_free, NAL_ADDRESS_create,
7 NAL_ADDRESS_set_def_buffer_size, NAL_ADDRESS_can_connect,
8 NAL_ADDRESS_can_listen - libnal addressing functions
9
11 #include <libnal/nal.h>
12 NAL_ADDRESS *NAL_ADDRESS_new(void);
14 void NAL_ADDRESS_free(NAL_ADDRESS *addr);
15 void NAL_ADDRESS_reset(NAL_ADDRESS *addr);
16 int NAL_ADDRESS_create(NAL_ADDRESS *addr, const char *addr_string,
17 unsigned int def_buffer_size);
18 unsigned int NAL_ADDRESS_get_def_buffers_size(const NAL_ADDRESS *addr);
19 int NAL_ADDRESS_set_def_buffer_size(NAL_ADDRESS *addr,
20 unsigned int def_buffer_size);
21 int NAL_ADDRESS_can_connect(const NAL_ADDRESS *addr);
22 int NAL_ADDRESS_can_listen(const NAL_ADDRESS *addr);
23
25 NAL_ADDRESS_new() allocates and initialises a new NAL_ADDRESS object.
26 NAL_ADDRESS_free() destroys a NAL_ADDRESS object.
28 NAL_ADDRESS_reset() will, if necessary, cleanup any prior state in addr
30 so that it can be reused in NAL_ADDRESS_create(). Internally, there are
31 other optimisations and benefits to using NAL_ADDRESS_reset() instead
32 of NAL_ADDRESS_free() and NAL_ADDRESS_new() - the implementation can
33 try to avoid repeated reallocation and reinitialisation of state, only
34 doing full cleanup and reinitialisation when necessary.
35 NAL_ADDRESS_create() will attempt to parse a network address from the
37 string constant provided in addr_string. If this succeeds, then addr
38 will represent the given network address for use in other libnal func‐
39 tions. The significance of def_buffer_size is that any NAL_CONNECTION
40 object created with addr will inherent def_buffer_size as the default
41 size for its read and write buffers (see NAL_CONNECTION_set_size(2)).
42 If addr is used to create a NAL_LISTENER object, then any NAL_CONNEC‐
43 TION objects that are assigned connections from the listener will like‐
44 wise have the given default size for its buffers. See the "NOTES" sec‐
45 tion for information on the syntax of addr.
46 NAL_ADDRESS_set_def_buffer_size() sets def_buffer_size as the default
48 buffer size in addr. This operation is built into NAL_ADDRESS_create()
49 already. NAL_ADDRESS_get_def_buffer_size() returns the current default
50 buffer size of addr.
51 NAL_ADDRESS_can_connect() will indicate whether the address represented
53 by addr is of an appropriate form for creating a NAL_CONNECTION object.
54 NAL_ADDRESS_can_listen() likewise indicates if addr is appopriate for
55 creating a NAL_LISTENER object. In other words, these functions deter‐
56 mine whether the address can be ``connected to'' or ``listened on''.
57 Depending on the type of transport and the string from which addr was
58 parsed, some addresses are only good for connecting or listening
59 whereas others can be good for both. See "NOTES".
60
62 NAL_ADDRESS_new() returns a valid NAL_ADDRESS object on success, NULL
63 otherwise.
64 NAL_ADDRESS_free() and NAL_ADDRESS_reset() have no return value.
66 NAL_ADDRESS_get_def_buffer_size() returns the size of the current
68 default buffer size in a NAL_ADDRESS object.
69 All other NAL_ADDRESS functions return zero for failure or false, and
71 non-zero for success or true.
72
74 The string syntax implemented by libnal is used by all the distcache
75 libraries and tools. At the time of writing, only TCP/IPv4 and unix
76 domain sockets were supported as underlying transports and so likewise
77 the implemented syntax handling only supported these two forms.
78 TCP/IPv4 addresses
80 The syntax for TCP/IPv4 addresses has two forms, depending on
81 whether you specify a hostname (or alternatively a dotted-numeric
82 IP address) with the port number or just the port number on its
83 own. Eg. to represent port 9001, one uses;
84 IP:9001
86 whereas to specify a hostname or IP address with it, the syntax is;
88 IP:machinename.domain:9001
90 IP:192.168.0.1:9001
91 Either form of TCP/IPv4 address is generally valid for creating a
93 NAL_LISTENER object, although it will depend at run-time on the
94 situation in the system - ie. whether privileges exist to listen on
95 the port, whether the port is already in use, whether the specified
96 hostname or IP address is bound to a running network interface that
97 can be listened on, etc. For creating a NAL_CONNECTION object, an
98 address must be specified. This is why the NAL_CONNECTION_can_con‐
99 nect() and NAL_CONNECTION_can_listen() helper functions exist - to
100 detect whether the syntax used is logical for the intended use.
101 Failures to set up network resources afterwards will in turn say
102 whether the given address data is possible within the host system.
103 unix domain addresses
105 There is only one syntax for unix domain addresses, and so any cor‐
106 rectly parsed address string is in theory valid for connecting to
107 or listening on. The form is;
108 UNIX:/path/to/socket
110 This represents the path to the socket in the file system.
112
114 NAL_CONNECTION_new(2) - Functions for the NAL_CONNECTION type.
115 NAL_LISTENER_new(2) - Functions for the NAL_LISTENER type.
117 NAL_SELECTOR_new(2) - Functions for the NAL_SELECTOR type.
119 NAL_BUFFER_new(2) - Functions for the NAL_BUFFER type.
121 distcache(8) - Overview of the distcache architecture.
123 http://www.distcache.org/ - Distcache home page.
125
127 This toolkit was designed and implemented by Geoff Thorpe for Crypto‐
128 graphic Appliances Incorporated. Since the project was released into
129 open source, it has a home page and a project environment where devel‐
130 opment, mailing lists, and releases are organised. For problems with
131 the software or this man page please check for new releases at the
132 project web-site below, mail the users mailing list described there, or
133 contact the author at geoff@geoffthorpe.net.
134 Home Page: http://www.distcache.org
1361.4.5 2004.03.23 NAL_ADDRESS_NEW(2)