23.1. Programming using C-API
Related RFCs:
*
RFC 3493 / Basic Socket Interface Extensions for IPv6
*
RFC 3542 / Advanced Sockets Application Program Interface (API) for IPv6
Following contents of this section is contributed by John Wenker, Sr. Software Engineer Performance Technologies San Diego, CA USA http://www.pt.com/.
This section describes how to write IPv6 client-server applications under the Linux operating system. First thing's first, and credit must be given where it is due. The information contained in this section is derived from Chapters 2 through 4 of IPv6 Network
Programming by Jun-ichiro itojun Hagino (ISBN 1-55558-318-0). The reader is encouraged to consult that book for more detailed information. It describes how to convert IPv4 applications to be IPv6 compatible in a protocol-independent way, and describes some
of the common problems encountered during the conversion along with suggested solutions. At the time of this writing, this is the only book of which the author is aware that specifically addresses how to program IPv6 applications [since writing this section,
the author has also become aware of the Porting applications to IPv6 HowTo by Eva M. Castro at http://jungla.dit.upm.es/~ecastro/IPv6-web/ipv6.html]. Unfortunately, of the almost 360 pages in the book, maybe 60 are actually useful (the chapters mentioned).
Nevertheless, without the guidance of that book, the author would have been unable to perform his job duties or compose this HowTo. While most (but certainly not all) of the information in the Hagino book is available via the Linux 'man' pages, application
programmers will save a significant amount of time and frustration by reading the indicated chapters of the book rather than searching through the 'man' pages and online documentation.
Other than the Hagino book, any other information presented in this HowTo was obtained through trial and error. Some items or explanations may not be entirely “correct” in the grand IPv6 scheme, but seem to work in practical application.
The discussion that follows assumes the reader is already experienced with the traditional TCP/IP socket API. For more information on traditional socket programming, the Internetworking with TCP/IP series of textbooks by Comer & Stevens is hard to beat, specifically
Volume III: Client-Server Programming and Applications, Linux/POSIX Sockets Version (ISBN 0-13-032071-4). This HowTo also assumes that the reader has had at least a bare basic introduction to IPv6 and in particular the addressing scheme for network addresses
(see Section 2.3).
23.1.1. Address Structures
This section provides a brief overview of the structures provided in the socket API to represent network addresses (or more specifically transport endpoints) when using the Internet protocols in a client-server application.
23.1.1.1. IPv4 sockaddr_in
In IPv4, network addresses are 32 bits long and define a network node. Addresses are written in dotted decimal notation, such as 192.0.2.1, where each number represents eight bits of the address. Such an IPv4 address is represented by the struct sockaddr_in
data type, which is defined in <netinet/in.h>.
struct sockaddr_in
{
sa_family_t sin_family;
in_port_t sin_port;
struct in_addr sin_addr;
/* Plus some padding for alignment */
};
The sin_family component indicates the address family. For IPv4 addresses, this is always set to AF_INET. The sin_addr field contains the 32-bit network address (in network byte order). Finally, the sin_port component represents the transport layer port number
(in network byte order). Readers should already be familiar with this structure, as this is the standard IPv4 address structure.
23.1.1.2. IPv6 sockaddr_in6
The biggest feature of IPv6 is its increased address space. Instead of 32-bit network addresses, IPv6 allots 128 bits to an address. Addresses are written in colon-hex notation of the form fe80::2c0:8cff:fe01:2345, where each hex number separated by colons
represents 16 bits of the address. Two consecutive colons indicate a string of consecutive zeros for brevity, and at most only one double-colon may appear in the address. IPv6 addresses are represented by the struct sockaddr_in6 data type, also defined in
<netinet/in.h>.
struct sockaddr_in6
{
sa_family_t sin6_family;
in_port_t sin6_port;
uint32_t sin6_flowinfo;
struct in6_addr sin6_addr;
uint32_t sin6_scope_id;
};
The sin6_family, sin6_port, and sin6_addr components of the structure have the same meaning as the corresponding fields in the sockaddr_in structure. However, the sin6_family member is set to AF_INET6 for IPv6 addresses, and the sin6_addr field holds a 128-bit
address instead of only 32 bits.
The sin6_flowinfo field is used for flow control, but is not yet standardized and can be ignored.
The sin6_scope_id field has an odd use, and it seems (at least to this naïve author) that the IPv6 designers took a huge step backwards when devising this. Apparently, 128-bit IPv6 network addresses are not unique. For example, it is possible to have two hosts,
on separate networks, with the same link-local address (see Figure 1). In order to pass information to a specific host, more than just the network address is required; the scope identifier must also be specified. In Linux, the network interface name is used
for the scope identifier (e.g. “eth0”) [be warned that the scope identifier is implementation dependent!]. Use the ifconfig(1M) command to display a list of active network interfaces.
A colon-hex network address can be augmented with the scope identifier to produce a "scoped address”. The percent sign ('%') is used to delimit the network address from the scope identifier. For example, fe80::1%eth0 is a scoped IPv6 address where fe80::1 represents
the 128-bit network address and eth0 is the network interface (i.e. the scope identifier). Thus, if a host resides on two networks, such as Host B in example below, the user now has to know which path to take in order to get to a particular host. In Figure
1, Host B addresses Host A using the scoped address fe80::1%eth0, while Host C is addressed with fe80::1%eth1.
Host A (fe80::1) ---- eth0 ---- Host B ---- eth1 ---- Host C (fe80::1)
Getting back to the sockaddr_in6 structure, its sin6_scope_id field contains the index of the network interface on which a host may be found. Server applications will have this field set automatically by the socket API when they accept a connection or receive
a datagram. For client applications, if a scoped address is passed as the node parameter to getaddrinfo(3) (described later in this HowTo), then the sin6_scope_id field will be filled in correctly by the system upon return from the function; if a scoped address
is not supplied, then the sin6_scope_id field must be explicitly set by the client software prior to attempting to communicate with the remote server. The if_nametoindex(3) function is used to translate a network interface name into its corresponding index.
It is declared in <net/if.h>.
23.1.1.3. Generic Addresses
As any programmer familiar with the traditional TCP/IP socket API knows, several socket functions deal with "generic" pointers. For example, a pointer to a generic struct sockaddr data type is passed as a parameter to some socket functions (such as connect(2)
or bind(2)) rather than a pointer to a specific address type. Be careful... the sockaddr_in6 structure is larger than the generic sockaddr structure! Thus, if your program receives a generic address whose actual type is unknown (e.g. it could be an IPv4 address
structure or an IPv6 address structure), you must supply sufficient storage to hold the entire address. The struct sockaddr_storage data type is defined in <bits/socket.h> for this purpose [do not #include this file directly within an application; use <sys/socket.h>
as usual, and <bits/socket.h> will be implicitly included].
For example, consider the recvfrom(2) system call, which is used to receive a message from a remote peer. Its function prototype is:
ssize_t recvfrom( int s,
void *buf,
size_t len,
int flags,
struct sockaddr *from,
socklen_t *fromlen );
The from parameter points to a generic sockaddr structure. If data can be received from an IPv6 peer on the socket referenced by s, then from should point to a data type of struct sockaddr_storage, as in the following dummy example:
/*
** Read a message from a remote peer, and return a buffer pointer to
** the caller.
**
** 's' is the file descriptor for the socket.
*/
char *rcvMsg( int s )
{
static char bfr[ 1025 ]; /* Where the msg is stored. */
ssize_t count;
struct sockaddr_storage ss; /* Where the peer adr goes. */
socklen_t sslen;
sslen = sizeof( ss );
count = recvfrom( s,
bfr,
sizeof( bfr ) - 1,
0,
(struct sockaddr*) &ss,
&sslen );
bfr[ count ] = '\0'; /* Null-terminates the message. */
return bfr;
} /* End rcvMsg() */
As seen in the above example, ss (a struct sockaddr_storage data object) is used to receive the peer address information, but it's address is typecast to a generic struct sockaddr* pointer in the call to recvfrom(2).
23.1.2. Lookup Functions
Traditionally, hostname and service name resolution were performed by functions such as gethostbyname(3) and getservbyname(3). These traditional lookup functions are still available, but they are not forward compatible to IPv6. Instead, the IPv6 socket API
provides new lookup functions that consolidate the functionality of several traditional functions. These new lookup functions are also backward compatible with IPv4, so a programmer can use the same translation algorithm in an application for both the IPv4
and IPv6 protocols. This is an important feature, because obviously a global IPv6 infrastructure isn't going to be put in place overnight. Thus, during the transition period from IPv4 to IPv6, client-server applications should be designed with the flexibility
to handle both protocols simultaneously. The example programs at the end of this chapter do just that.
The primary lookup function in the new socket API is getaddrinfo(3). Its prototype is as follows.
int getaddrinfo( const char *node,
const char *service,
const struct addrinfo *hints,
struct addrinfo **res );
The node parameter is a pointer to the hostname or IP address being translated. The referenced string can be a hostname, IPv4 dotted decimal address, or IPv6 colon-hex address (possibly scoped). The service parameter is a pointer to the transport layer's service
name or port number. It can be specified as a name found in /etc/services or a decimal number. getaddrinfo(3) resolves the host/service combination and returns a list of address records; a pointer to the list is placed in the location pointed at by res. For
example, suppose a host can be identified by both an IPv4 and IPv6 address, and that the indicated service has both a TCP entry and UDP entry in /etc/services. In such a scenario, it is not inconceivable that four address records are returned; one for TCP/IPv6,
one for UDP/IPv6, one for TCP/IPv4, and one for UDP/IPv4.
The definition for struct addrinfo is found in <netdb.h> (as is the declaration for getaddrinfo(3) and the other functions described in this section). The structure has the following format:
struct addrinfo
{
int ai_flags;
int ai_family;
int ai_socktype;
int ai_protocol;
socklen_t ai_addrlen;
struct sockaddr *ai_addr;
char *ai_canonname;
struct addrinfo *ai_next;
};
Consult the 'man' page for getaddrinfo(3) for detailed information about the various fields; this HowTo only describes a subset of them, and only to the extent necessary for normal IPv6 programming.
The ai_family, ai_socktype, and ai_protocol fields have the exact same meaning as the parameters to the socket(2) system call. The ai_family field indicates the protocol family (not the address family) associated with the record, and will be PF_INET6 for IPv6
or PF_INET for IPv4. The ai_socktype parameter indicates the type of socket to which the record corresponds; SOCK_STREAM for a reliable connection-oriented byte-stream or SOCK_DGRAM for connectionless communication. The ai_protocol field specifies the underlying
transport protocol for the record.
The ai_addr field points to a generic struct sockaddr object. Depending on the value in the ai_family field, it will point to either a struct sockaddr_in (PF_INET) or a struct sockaddr_in6 (PF_INET6). The ai_addrlen field contains the size of the object pointed
at by the ai_addr field.
As mentioned, getaddrinfo(3) returns a list of address records. The ai_next field points to the next record in the list.
The hints parameter to getaddrinfo(3) is also of type struct addrinfo and acts as a filter for the address records returned in res. If hints is NULL, all matching records are returned; but if hints is non-NULL, the referenced structure gives "hints" to getaddrinfo(3)
about which records to return. Only the ai_flags, ai_family, ai_socktype, and ai_protocol fields are significant in the hints structure, and all other fields should be set to zero.
Programs can use hints->ai_family to specify the protocol family. For example, if it is set to PF_INET6, then only IPv6 address records are returned. Likewise, setting hints->ai_family to PF_INET results in only IPv4 address records being returned. If an application
wants both IPv4 and IPv6 records, the field should be set to PF_UNSPEC.
The hints->socktype field can be set to SOCK_STREAM to return only records that correspond to connection-oriented byte streams, SOCK_DGRAM to return only records corresponding to connectionless communication, or 0 to return both.
For the Internet protocols, there is only one protocol associated with connection-oriented sockets (TCP) and one protocol associated with connectionless sockets (UDP), so setting hints->ai_socktype to SOCK_STREAM or SOCK_DGRAM is the same as saying, "Give me
only TCP records," or "Give me only UDP records," respectively. With that in mind, the hints->ai_protocol field isn't really that important with the Internet protocols, and pretty much mirrors the hints->ai_socktype field. Nevertheless, hints->ai_protocol
can be set to IPPROTO_TCP to return only TCP records, IPPROTO_UDP to return only UDP records, or 0 for both.
The node or service parameter to gethostbyname(3) can be NULL, but not both. If node is NULL, then the ai_flags field of the hints parameter specifies how the network address in a returned record is set (i.e. the sin_addr or sin6_addr field of the object pointed
at by the ai_addr component in a returned record). If the AI_PASSIVE flag is set in hints, then the returned network addresses are left unresolved (all zeros). This is how server applications would use getaddrinfo(3). If the flag is not set, then the address
is set to the local loopback address (::1 for IPv6 or 127.0.0.1 for IPv4). This is one way a client application can specify that the target server is running on the same machine as the client. If the service parameter is NULL, the port number in the returned
address records remains unresolved.
The getaddrinfo(3) function returns zero on success, or an error code. In the case of an error, the gai_strerror(3) function is used to obtain a character pointer to an error message corresponding to the error code, just like strerror(3) does in the standard
'C' library.
Once the address list is no longer needed, it must be freed by the application. This is done with the freeaddrinfo(3) function.
The last function that will be mentioned in this section is getnameinfo(3). This function is the inverse of getaddrinfo(3); it is used to create a string representation of the hostname and service from a generic struct sockaddr data object. It has the following
prototype.
int getnameinfo( const struct sockaddr *sa,
socklen_t salen,
char *host,
size_t hostlen,
char *serv,
size_t servlen,
int flags );
The sa parameter points to the address structure in question, and salen contains its size. The host parameter points to a buffer where the null-terminated hostname string is placed, and the hostlen parameter is the size of that buffer. If there is no hostname
that corresponds to the address, then the network address (dotted decimal or colon-hex) is placed in host. Likewise, the serv parameter points to a buffer where the null-terminated service name string (or port number) is placed, and the servlen parameter is
the size of that buffer. The flags parameter modifies the function's behavior; in particular, the NI_NUMERICHOST flag indicates that the converted hostname should always be formatted in numeric form (i.e. dotted decimal or colon-hex), and the NI_NUMERICSERV
flag indicates that the converted service should always be in numeric form (i.e. the port number).
The symbols NI_MAXHOST and NI_MAXSERV are available to applications and represent the maximum size of any converted hostname or service name, respectively. Use these when declaring output buffers for getnameinfo(3).
23.1.3. Quirks Encountered
Before jumping into the programming examples, there are several quirks in IPv6 of which the reader should be aware. The more significant ones (in addition to the non-uniqueness of IPv6 network addresses already discussed) are described in the paragraphs below.
23.1.3.1. IPv4 Mapped Addresses
For security reasons that this author won't pretend to understand, "IPv4 mapped addresses" should not be allowed in IPv6-capable server applications. To put it in terms that everyone can understand, this simply means that a server should not accept IPv4 traffic
on an IPv6 socket (an otherwise legal operation). An IPv4 mapped address is a mixed-format address of the form:
::ffff:192.0.2.1
where the first portion is in IPv6 colon-hex format and the last portion is in IPv4 dotted decimal notation. The dotted decimal IPv4 address is the actual network address, but it is being mapped into an IPv6 compatible format.
To prevent IPv4 mapped addresses from being accepted on an IPv6 socket, server applications must explicitly set the IPV6_V6ONLY socket option on all IPv6 sockets created [the Hagino book implies that this is only a concern with server applications. However,
it has been observed during testing that if a client application uses an IPv4 mapped address to specify the target server, and the target server has IPv4 mapped addresses disabled, the connection still completes regardless. On the server side, the connection
endpoint is an IPv4 socket as desired; but on the client side, the connection endpoint is an IPv6 socket. Setting the IPV6_V6ONLY socket option on the client side as well as the server side prevents any connection from being established at all.]. There's only
one problem. Apparently, IPV6_V6ONLY isn't defined on all systems [or at least it wasn't in 2005 when the Hagino book was written]. The server example at the end of this chapter provides a method for handling this problem.
If IPv4 traffic cannot be handled on IPv6 sockets, then that implies that server applications must open both an IPv4 and IPv6 socket for a particular network service if it wants to handle requests from either protocol. This goes back to the flexibility issue
mentioned earlier. If getaddrinfo(3) returns multiple address records, then server applications should traverse the list and open a passive socket for each address provided.
23.1.3.2. Cannot Specify the Scope Identifier in /etc/hosts
It is possible to assign a hostname to an IPv6 network address in /etc/hosts. For example, the following is an excerpt from the /etc/hosts file on the author's development system.
::1 localhost
127.0.0.1 localhost
fe80::2c0:8cff:fe01:2345 pt141
192.0.2.1 pt141
The "localhost" and "pt141" hostnames can be translated to either an IPv4 or IPv6 network address. So, for example, if "pt141" is passed as the node parameter to getaddrinfo(3), the function returns both an IPv4 and IPv6 address record for the host (assuming
the behavior hasn't been modified by the hints parameter). Unfortunately, a scoped address cannot be used in /etc/hosts. Doing so results in getaddrinfo(3) returning only the IPv4 record.
23.1.3.3. Client & Server Residing on the Same Machine
Suppose a machine has the IPv4 address 192.0.2.1. A client application running on that machine can connect to a server application on the same machine by using either the local loopback address (127.0.0.1) or the network address (192.0.2.1) as the target server.
Much to this author's surprise (and dismay), it turns out that an IPv6 client application cannot connect to a server application on the same machine if it uses the network address of that machine as the target; it must use the local loopback address (::1).
23.1.4. Putting It All Together (A Client-Server Programming Example)
Now it's time to put everything discussed thus far together into a sample client-server application. The remainder of this section is devoted to a remote time-of-day application (the 'daytime' Internet service) [I noticed that Ms. Castro used a 'daytime' example
in her Porting applications to IPv6 HowTo. For the record, the source code presented here is original, developed from scratch, and any similarity between it and any other publicly available 'daytime' example is purely coincidental.]. The source code presented
in this section was developed and tested on a RedHat Linux release using the 2.6 kernel (2.6.9 to be specific). Readers may use the source code freely, so long as proper credit is attributed; but of course the standard disclaimer must be given first:
Although the sample source code is believed to be free of errors, the author makes no guarantees as to its reliability, especially considering that some error paths were intentionally omitted for brevity. Use it at your own risk!
When you get right down to it, there really aren't that many differences between IPv4 and IPv6 applications. The trick is to code IPv6 applications in a protocol-independent manner, such that they can handle both IPv4 and IPv6 simultaneously and transparently.
This sample application does just that. The only protocol-dependent code in the example occurs when printing network addresses in verbose mode; but only after the ai_family field in the addrinfo structure has been checked, so the programs know exactly what
type of address they're handling at the time.
23.1.4.1. 'Daytime' Server Code
The server code is found in file tod6d.c (time-of-day IPv6 daemon). Once built, the server may be started using the following command syntax (assuming tod6d is the executable file):
tod6d [-v] [service]
ARGUMENTS:
service
The service (or well-known port) on which to listen. Default is "daytime".
OPTIONS:
-v
Turn on verbose mode.
The server handles both TCP and UDP requests on the network. The server source code contained in tod6d.c follows:
/******************************************************************************
* File: tod6d.c
* Description: Contains source code for an IPv6-capable 'daytime' server.
* Author: John Wenker, Sr. Software Engineer,
* Performance Technologies, San Diego, USA
******************************************************************************/
/*
** System header files.
*/
#include <errno.h> /* errno declaration & error codes. */
#include <netdb.h> /* getaddrinfo(3) et al. */
#include <netinet/in.h> /* sockaddr_in & sockaddr_in6 definition. */
#include <stdio.h> /* printf(3) et al. */
#include <stdlib.h> /* exit(2). */
#include <string.h> /* String manipulation & memory functions. */
#include <sys/poll.h> /* poll(2) and related definitions. */
#include <sys/socket.h> /* Socket functions (socket(2), bind(2), etc). */
#include <time.h> /* time(2) & ctime(3). */
#include <unistd.h> /* getopt(3), read(2), etc. */
/*
** Constants.
*/
#define DFLT_SERVICE "daytime" /* Default service name. */
#define INVALID_DESC -1 /* Invalid file descriptor. */
#define MAXCONNQLEN 3 /* Max nbr of connection requests to queue. */
#define MAXTCPSCKTS 2 /* One TCP socket for IPv4 & one for IPv6. */
#define MAXUDPSCKTS 2 /* One UDP socket for IPv4 & one for IPv6. */
#define VALIDOPTS "v" /* Valid command options. */
/*
** Simple boolean type definition.
*/
typedef enum { false = 0, true } boolean;
/*
** Prototypes for internal helper functions.
*/
static int openSckt( const char *service,
const char *protocol,
int desc[ ],
size_t *descSize );
static void tod( int tSckt[ ],
size_t tScktSize,
int uSckt[ ],
size_t uScktSize );
/*
** Global (within this file only) data objects.
*/
static char hostBfr[ NI_MAXHOST ]; /* For use w/getnameinfo(3). */
static const char *pgmName; /* Program name w/o dir prefix. */
static char servBfr[ NI_MAXSERV ]; /* For use w/getnameinfo(3). */
static boolean verbose = false; /* Verbose mode indication. */
/*
** Usage macro for command syntax violations.
*/
#define USAGE \
{ \
fprintf( stderr, \
"Usage: %s [-v] [service]\n", \
pgmName ); \
exit( 127 ); \
} /* End USAGE macro. */
/*
** Macro to terminate the program if a system call error occurs. The system
** call must be one of the usual type that returns -1 on error. This macro is
** a modified version of a macro authored by Dr. V. Vinge, SDSU Dept. of
** Computer Science (retired)... best professor I ever had. I hear he writes
** great science fiction in addition to robust code, too.
*/
#define CHK(expr) \
do \
{ \
if ( (expr) == -1 ) \
{ \
fprintf( stderr, \
"%s (line %d): System call ERROR - %s.\n", \
pgmName, \
__LINE__, \
strerror( errno ) ); \
exit( 1 ); \
} /* End IF system call failed. */ \
} while ( false )
/******************************************************************************
* Function: main
*
* Description:
* Set up a time-of-day server and handle network requests. This server
* handles both TCP and UDP requests.
*
* Parameters:
* The usual argc and argv parameters to a main() function.
*
* Return Value:
* This is a daemon program and never returns. However, in the degenerate
* case where no sockets are created, the function returns zero.
******************************************************************************/
int main( int argc,
char *argv[ ] )
{
int opt;
const char *service = DFLT_SERVICE;
int tSckt[ MAXTCPSCKTS ]; /* Array of TCP socket descriptors. */
size_t tScktSize = MAXTCPSCKTS; /* Size of uSckt (# of elements). */
int uSckt[ MAXUDPSCKTS ]; /* Array of UDP socket descriptors. */
size_t uScktSize = MAXUDPSCKTS; /* Size of uSckt (# of elements). */
/*
** Set the program name (w/o directory prefix).
*/
pgmName = strrchr( argv[ 0 ], '/' );
pgmName = pgmName == NULL ? argv[ 0 ] : pgmName + 1;
/*
** Process command options.
*/
opterr = 0; /* Turns off "invalid option" error messages. */
while ( ( opt = getopt( argc, argv, VALIDOPTS ) ) >= 0 )
{
switch ( opt )
{
case 'v': /* Verbose mode. */
{
verbose = true;
break;
}
default:
{
USAGE;
}
} /* End SWITCH on command option. */
} /* End WHILE processing options. */
/*
** Process command line arguments.
*/
switch ( argc - optind )
{
case 0: break;
case 1: service = argv[ optind ]; break;
default: USAGE;
} /* End SWITCH on number of command line arguments. */
/*
** Open both a TCP and UDP socket, for both IPv4 & IPv6, on which to receive
** service requests.
*/
if ( ( openSckt( service, "tcp", tSckt, &tScktSize ) < 0 ) ||
( openSckt( service, "udp", uSckt, &uScktSize ) < 0 ) )
{
exit( 1 );
}
/*
** Run the time-of-day server.
*/
if ( ( tScktSize > 0 ) || ( uScktSize > 0 ) )
{
tod( tSckt, /* tod() never returns. */
tScktSize,
uSckt,
uScktSize );
}
/*
** Since tod() never returns, execution only gets here if no sockets were
** created.
*/
if ( verbose )
{
fprintf( stderr,
"%s: No sockets opened... terminating.\n",
pgmName );
}
return 0;
} /* End main() */
/******************************************************************************
* Function: openSckt
*
* Description:
* Open passive (server) sockets for the indicated inet service & protocol.
* Notice in the last sentence that "sockets" is plural. During the interim
* transition period while everyone is switching over to IPv6, the server
* application has to open two sockets on which to listen for connections...
* one for IPv4 traffic and one for IPv6 traffic.
*
* Parameters:
* service - Pointer to a character string representing the well-known port
* on which to listen (can be a service name or a decimal number).
* protocol - Pointer to a character string representing the transport layer
* protocol (only "tcp" or "udp" are valid).
* desc - Pointer to an array into which the socket descriptors are
* placed when opened.
* descSize - This is a value-result parameter. On input, it contains the
* max number of descriptors that can be put into 'desc' (i.e. the
* number of elements in the array). Upon return, it will contain
* the number of descriptors actually opened. Any unused slots in
* 'desc' are set to INVALID_DESC.
*
* Return Value:
* 0 on success, -1 on error.
******************************************************************************/
static int openSckt( const char *service,
const char *protocol,
int desc[ ],
size_t *descSize )
{
struct addrinfo *ai;
int aiErr;
struct addrinfo *aiHead;
struct addrinfo hints = { .ai_flags = AI_PASSIVE, /* Server mode.
¬ */
.ai_family = PF_UNSPEC }; /* IPv4 or IPv6.
¬ */
size_t maxDescs = *descSize;
/*
** Initialize output parameters. When the loop completes, *descSize is 0.
*/
while ( *descSize > 0 )
{
desc[ --( *descSize ) ] = INVALID_DESC;
}
/*
** Check which protocol is selected (only TCP and UDP are valid).
*/
if ( strcmp( protocol, "tcp" ) == 0 ) /* TCP protocol. */
{
hints.ai_socktype = SOCK_STREAM;
hints.ai_protocol = IPPROTO_TCP;
}
else if ( strcmp( protocol, "udp" ) == 0 ) /* UDP protocol. */
{
hints.ai_socktype = SOCK_DGRAM;
hints.ai_protocol = IPPROTO_UDP;
}
else /* Invalid protocol. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown transport "
"layer protocol \"%s\".\n",
pgmName,
__LINE__,
protocol );
return -1;
}
/*
** Look up the service's well-known port number. Notice that NULL is being
** passed for the 'node' parameter, and that the AI_PASSIVE flag is set in
** 'hints'. Thus, the program is requesting passive address information.
** The network address is initialized to :: (all zeros) for IPv6 records, or
** 0.0.0.0 for IPv4 records.
*/
if ( ( aiErr = getaddrinfo( NULL,
service,
&hints,
&aiHead ) ) != 0 )
{
fprintf( stderr,
"%s (line %d): ERROR - %s.\n",
pgmName,
__LINE__,
gai_strerror( aiErr ) );
return -1;
}
/*
** For each of the address records returned, attempt to set up a passive
** socket.
*/
for ( ai = aiHead;
( ai != NULL ) && ( *descSize < maxDescs );
ai = ai->ai_next )
{
if ( verbose )
{
/*
** Display the current address info. Start with the protocol-
** independent fields first.
*/
fprintf( stderr,
"Setting up a passive socket based on the "
"following address info:\n"
" ai_flags = 0x%02X\n"
" ai_family = %d (PF_INET = %d, PF_INET6 = %d)\n"
" ai_socktype = %d (SOCK_STREAM = %d, SOCK_DGRAM = %d)\n"
" ai_protocol = %d (IPPROTO_TCP = %d, IPPROTO_UDP = %d)\n"
" ai_addrlen = %d (sockaddr_in = %d, "
"sockaddr_in6 = %d)\n",
ai->ai_flags,
ai->ai_family,
PF_INET,
PF_INET6,
ai->ai_socktype,
SOCK_STREAM,
SOCK_DGRAM,
ai->ai_protocol,
IPPROTO_TCP,
IPPROTO_UDP,
ai->ai_addrlen,
sizeof( struct sockaddr_in ),
sizeof( struct sockaddr_in6 ) );
/*
** Now display the protocol-specific formatted socket address. Note
** that the program is requesting that getnameinfo(3) convert the
** host & service into numeric strings.
*/
getnameinfo( ai->ai_addr,
ai->ai_addrlen,
hostBfr,
sizeof( hostBfr ),
servBfr,
sizeof( servBfr ),
NI_NUMERICHOST | NI_NUMERICSERV );
switch ( ai->ai_family )
{
case PF_INET: /* IPv4 address record. */
{
struct sockaddr_in *p = (struct sockaddr_in*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin_addr: %s\n"
" sin_port: %s\n",
p->sin_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr );
break;
} /* End CASE of IPv4. */
case PF_INET6: /* IPv6 address record. */
{
struct sockaddr_in6 *p = (struct sockaddr_in6*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin6_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin6_addr: %s\n"
" sin6_port: %s\n"
" sin6_flowinfo: %d\n"
" sin6_scope_id: %d\n",
p->sin6_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr,
p->sin6_flowinfo,
p->sin6_scope_id );
break;
} /* End CASE of IPv6. */
default: /* Can never get here, but just for completeness. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown protocol family (%d).\n",
pgmName,
__LINE__,
ai->ai_family );
freeaddrinfo( aiHead );
return -1;
} /* End DEFAULT case (unknown protocol family). */
} /* End SWITCH on protocol family. */
} /* End IF verbose mode. */
/*
** Create a socket using the info in the addrinfo structure.
*/
CHK( desc[ *descSize ] = socket( ai->ai_family,
ai->ai_socktype,
ai->ai_protocol ) );
/*
** Here is the code that prevents "IPv4 mapped addresses", as discussed
** in Section 22.1.3.1. If an IPv6 socket was just created, then set the
** IPV6_V6ONLY socket option.
*/
if ( ai->ai_family == PF_INET6 )
{
#if defined( IPV6_V6ONLY )
/*
** Disable IPv4 mapped addresses.
*/
int v6Only = 1;
CHK( setsockopt( desc[ *descSize ],
IPPROTO_IPV6,
IPV6_V6ONLY,
&v6Only,
sizeof( v6Only ) ) );
#else
/*
** IPV6_V6ONLY is not defined, so the socket option can't be set and
** thus IPv4 mapped addresses can't be disabled. Print a warning
** message and close the socket. Design note: If the
** #if...#else...#endif construct were removed, then this program
** would not compile (because IPV6_V6ONLY isn't defined). That's an
** acceptable approach; IPv4 mapped addresses are certainly disabled
** if the program can't build! However, since this program is also
** designed to work for IPv4 sockets as well as IPv6, I decided to
** allow the program to compile when IPV6_V6ONLY is not defined, and
** turn it into a run-time warning rather than a compile-time error.
** IPv4 mapped addresses are still disabled because _all_ IPv6 traffic
** is disabled (all IPv6 sockets are closed here), but at least this
** way the server can still service IPv4 network traffic.
*/
fprintf( stderr,
"%s (line %d): WARNING - Cannot set IPV6_V6ONLY socket "
"option. Closing IPv6 %s socket.\n",
pgmName,
__LINE__,
ai->ai_protocol == IPPROTO_TCP ? "TCP" : "UDP" );
CHK( close( desc[ *descSize ] ) );
continue; /* Go to top of FOR loop w/o updating *descSize! */
#endif /* IPV6_V6ONLY */
} /* End IF this is an IPv6 socket. */
/*
** Bind the socket. Again, the info from the addrinfo structure is used.
*/
CHK( bind( desc[ *descSize ],
ai->ai_addr,
ai->ai_addrlen ) );
/*
** If this is a TCP socket, put the socket into passive listening mode
** (listen is only valid on connection-oriented sockets).
*/
if ( ai->ai_socktype == SOCK_STREAM )
{
CHK( listen( desc[ *descSize ],
MAXCONNQLEN ) );
}
/*
** Socket set up okay. Bump index to next descriptor array element.
*/
*descSize += 1;
} /* End FOR each address info structure returned. */
/*
** Dummy check for unused address records.
*/
if ( verbose && ( ai != NULL ) )
{
fprintf( stderr,
"%s (line %d): WARNING - Some address records were "
"not processed due to insufficient array space.\n",
pgmName,
__LINE__ );
} /* End IF verbose and some address records remain unprocessed. */
/*
** Clean up.
*/
freeaddrinfo( aiHead );
return 0;
} /* End openSckt() */
/******************************************************************************
* Function: tod
*
* Description:
* Listen on a set of sockets and send the current time-of-day to any
* clients. This function never returns.
*
* Parameters:
* tSckt - Array of TCP socket descriptors on which to listen.
* tScktSize - Size of the tSckt array (nbr of elements).
* uSckt - Array of UDP socket descriptors on which to listen.
* uScktSize - Size of the uSckt array (nbr of elements).
*
* Return Value: None.
******************************************************************************/
static void tod( int tSckt[ ],
size_t tScktSize,
int uSckt[ ],
size_t uScktSize )
{
char bfr[ 256 ];
ssize_t count;
struct pollfd *desc;
size_t descSize = tScktSize + uScktSize;
int idx;
int newSckt;
struct sockaddr *sadr;
socklen_t sadrLen;
struct sockaddr_storage sockStor;
int status;
size_t timeLen;
char *timeStr;
time_t timeVal;
ssize_t wBytes;
/*
** Allocate memory for the poll(2) array.
*/
desc = malloc( descSize * sizeof( struct pollfd ) );
if ( desc == NULL )
{
fprintf( stderr,
"%s (line %d): ERROR - %s.\n",
pgmName,
__LINE__,
strerror( ENOMEM ) );
exit( 1 );
}
/*
** Initialize the poll(2) array.
*/
for ( idx = 0; idx < descSize; idx++ )
{
desc[ idx ].fd = idx < tScktSize ? tSckt[ idx ]
: uSckt[ idx - tScktSize ];
desc[ idx ].events = POLLIN;
desc[ idx ].revents = 0;
}
/*
** Main time-of-day server loop. Handles both TCP & UDP requests. This is
** an interative server, and all requests are handled directly within the
** main loop.
*/
while ( true ) /* Do forever. */
{
/*
** Wait for activity on one of the sockets. The DO..WHILE construct is
** used to restart the system call in the event the process is
** interrupted by a signal.
*/
do
{
status = poll( desc,
descSize,
-1 /* Wait indefinitely for input. */ );
} while ( ( status < 0 ) && ( errno == EINTR ) );
CHK( status ); /* Check for a bona fide system call error. */
/*
** Get the current time.
*/
timeVal = time( NULL );
timeStr = ctime( &timeVal );
timeLen = strlen( timeStr );
/*
** Indicate that there is new network activity.
*/
if ( verbose )
{
char *s = malloc( timeLen+1 );
strcpy( s, timeStr );
s[ timeLen-1 ] = '\0'; /* Overwrite '\n' in date string. */
fprintf( stderr,
"%s: New network activity on %s.\n",
pgmName,
s );
free( s );
} /* End IF verbose. */
/*
** Process sockets with input available.
*/
for ( idx = 0; idx < descSize; idx++ )
{
switch ( desc[ idx ].revents )
{
case 0: /* No activity on this socket; try the next. */
continue;
case POLLIN: /* Network activity. Go process it. */
break;
default: /* Invalid poll events. */
{
fprintf( stderr,
"%s (line %d): ERROR - Invalid poll event (0x%02X).\n",
pgmName,
__LINE__,
desc[ idx ].revents );
exit( 1 );
}
} /* End SWITCH on returned poll events. */
/*
** Determine if this is a TCP request or UDP request.
*/
if ( idx < tScktSize )
{
/*
** TCP connection requested. Accept it. Notice the use of
** the sockaddr_storage data type.
*/
sadrLen = sizeof( sockStor );
sadr = (struct sockaddr*) &sockStor;
CHK( newSckt = accept( desc[ idx ].fd,
sadr,
&sadrLen ) );
CHK( shutdown( newSckt, /* Server never recv's anything. */
SHUT_RD ) );
if ( verbose )
{
/*
** Display the socket address of the remote client. Begin with
** the address-independent fields.
*/
fprintf( stderr,
"Sockaddr info for new TCP client:\n"
" sa_family = %d (AF_INET = %d, AF_INET6 = %d)\n"
" addr len = %d (sockaddr_in = %d, "
"sockaddr_in6 = %d)\n",
sadr->sa_family,
AF_INET,
AF_INET6,
sadrLen,
sizeof( struct sockaddr_in ),
sizeof( struct sockaddr_in6 ) );
/*
** Display the address-specific fields.
*/
getnameinfo( sadr,
sadrLen,
hostBfr,
sizeof( hostBfr ),
servBfr,
sizeof( servBfr ),
NI_NUMERICHOST | NI_NUMERICSERV );
/*
** Notice that we're switching on an address family now, not a
** protocol family.
*/
switch ( sadr->sa_family )
{
case AF_INET: /* IPv4 address. */
{
struct sockaddr_in *p = (struct sockaddr_in*) sadr;
fprintf( stderr,
" sin_addr = sin_family: %d\n"
" sin_addr: %s\n"
" sin_port: %s\n",
p->sin_family,
hostBfr,
servBfr );
break;
} /* End CASE of IPv4. */
case AF_INET6: /* IPv6 address. */
{
struct sockaddr_in6 *p = (struct sockaddr_in6*) sadr;
fprintf( stderr,
" sin6_addr = sin6_family: %d\n"
" sin6_addr: %s\n"
" sin6_port: %s\n"
" sin6_flowinfo: %d\n"
" sin6_scope_id: %d\n",
p->sin6_family,
hostBfr,
servBfr,
p->sin6_flowinfo,
p->sin6_scope_id );
break;
} /* End CASE of IPv6. */
default: /* Can never get here, but for completeness. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown address "
"family (%d).\n",
pgmName,
__LINE__,
sadr->sa_family );
break;
} /* End DEFAULT case (unknown address family). */
} /* End SWITCH on address family. */
} /* End IF verbose mode. */
/*
** Send the TOD to the client.
*/
wBytes = timeLen;
while ( wBytes > 0 )
{
do
{
count = write( newSckt,
timeStr,
wBytes );
} while ( ( count < 0 ) && ( errno == EINTR ) );
CHK( count ); /* Check for a bona fide error. */
wBytes -= count;
} /* End WHILE there is data to send. */
CHK( close( newSckt ) );
} /* End IF this was a TCP connection request. */
else
{
/*
** This is a UDP socket, and a datagram is available. The funny
** thing about UDP requests is that this server doesn't require any
** client input; but it can't send the TOD unless it knows a client
** wants the data, and the only way that can occur with UDP is if
** the server receives a datagram from the client. Thus, the
** server must receive _something_, but the content of the datagram
** is irrelevant. Read in the datagram. Again note the use of
** sockaddr_storage to receive the address.
*/
sadrLen = sizeof( sockStor );
sadr = (struct sockaddr*) &sockStor;
CHK( count = recvfrom( desc[ idx ].fd,
bfr,
sizeof( bfr ),
0,
sadr,
&sadrLen ) );
/*
** Display whatever was received on stdout.
*/
if ( verbose )
{
ssize_t rBytes = count;
fprintf( stderr,
"%s: UDP datagram received (%d bytes).\n",
pgmName,
count );
while ( count > 0 )
{
fputc( bfr[ rBytes - count-- ],
stdout );
}
if ( bfr[ rBytes-1 ] != '\n' )
fputc( '\n', stdout ); /* Newline also flushes stdout. */
/*
** Display the socket address of the remote client. Address-
** independent fields first.
*/
fprintf( stderr,
"Remote client's sockaddr info:\n"
" sa_family = %d (AF_INET = %d, AF_INET6 = %d)\n"
" addr len = %d (sockaddr_in = %d, "
"sockaddr_in6 = %d)\n",
sadr->sa_family,
AF_INET,
AF_INET6,
sadrLen,
sizeof( struct sockaddr_in ),
sizeof( struct sockaddr_in6 ) );
/*
** Display the address-specific information.
*/
getnameinfo( sadr,
sadrLen,
hostBfr,
sizeof( hostBfr ),
servBfr,
sizeof( servBfr ),
NI_NUMERICHOST | NI_NUMERICSERV );
switch ( sadr->sa_family )
{
case AF_INET: /* IPv4 address. */
{
struct sockaddr_in *p = (struct sockaddr_in*) sadr;
fprintf( stderr,
" sin_addr = sin_family: %d\n"
" sin_addr: %s\n"
" sin_port: %s\n",
p->sin_family,
hostBfr,
servBfr );
break;
} /* End CASE of IPv4 address. */
case AF_INET6: /* IPv6 address. */
{
struct sockaddr_in6 *p = (struct sockaddr_in6*) sadr;
fprintf( stderr,
" sin6_addr = sin6_family: %d\n"
" sin6_addr: %s\n"
" sin6_port: %s\n"
" sin6_flowinfo: %d\n"
" sin6_scope_id: %d\n",
p->sin6_family,
hostBfr,
servBfr,
p->sin6_flowinfo,
p->sin6_scope_id );
break;
} /* End CASE of IPv6 address. */
default: /* Can never get here, but for completeness. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown address "
"family (%d).\n",
pgmName,
__LINE__,
sadr->sa_family );
break;
} /* End DEFAULT case (unknown address family). */
} /* End SWITCH on address family. */
} /* End IF verbose mode. */
/*
** Send the time-of-day to the client.
*/
wBytes = timeLen;
while ( wBytes > 0 )
{
do
{
count = sendto( desc[ idx ].fd,
timeStr,
wBytes,
0,
sadr, /* Address & address length */
sadrLen ); /* received in recvfrom(). */
} while ( ( count < 0 ) && ( errno == EINTR ) );
CHK( count ); /* Check for a bona fide error. */
wBytes -= count;
} /* End WHILE there is data to send. */
} /* End ELSE a UDP datagram is available. */
desc[ idx ].revents = 0; /* Clear the returned poll events. */
} /* End FOR each socket descriptor. */
} /* End WHILE forever. */
} /* End tod() */
23.1.4.2. 'Daytime' TCP Client Code
The TCP client code is found in file tod6tc.c (time-of-day IPv6 TCP client). Once built, the TCP client may be started using the following command syntax (assuming tod6tc is the executable file):
tod6tc [-v] [-s scope_id] [host [service]]
ARGUMENTS:
host
The hostname or IP address (dotted decimal or colon-hex) of the remote host providing the service. Default is "localhost".
service
The TCP service (or well-known port number) to which a connection attempt is made. Default is "daytime".
OPTIONS:
-s
This option is only meaningful for IPv6 addresses, and is used to set the scope identifier (i.e. the network interface on which to establish the connection). Default is "eth0". If host is a scoped address, this option is ignored.
-v
Turn on verbose mode.
The TCP client source code contained in tod6tc.c follows:
/******************************************************************************
* File: tod6tc.c
* Description: Contains source code for an IPv6-capable 'daytime' TCP client.
* Author: John Wenker, Sr. Software Engineer
* Performance Technologies, San Diego, USA
******************************************************************************/
/*
** System header files.
*/
#include <errno.h> /* errno declaration and error codes. */
#include <net/if.h> /* if_nametoindex(3). */
#include <netdb.h> /* getaddrinfo(3) and associated definitions. */
#include <netinet/in.h> /* sockaddr_in and sockaddr_in6 definitions. */
#include <stdio.h> /* printf(3) et al. */
#include <stdlib.h> /* exit(2). */
#include <string.h> /* String manipulation and memory functions. */
#include <sys/socket.h> /* Socket functions (socket(2), connect(2), etc). */
#include <unistd.h> /* getopt(3), read(2), etc. */
/*
** Constants & macros.
*/
#define DFLT_HOST "localhost" /* Default server name. */
#define DFLT_SCOPE_ID "eth0" /* Default scope identifier. */
#define DFLT_SERVICE "daytime" /* Default service name. */
#define INVALID_DESC -1 /* Invalid file (socket) descriptor. */
#define MAXBFRSIZE 256 /* Max bfr sz to read remote TOD. */
#define VALIDOPTS "s:v" /* Valid command options. */
/*
** Type definitions (for convenience).
*/
typedef enum { false = 0, true } boolean;
typedef struct sockaddr_in sockaddr_in_t;
typedef struct sockaddr_in6 sockaddr_in6_t;
/*
** Prototypes for internal helper functions.
*/
static int openSckt( const char *host,
const char *service,
unsigned int scopeId );
static void tod( int sckt );
/*
** Global (within this file only) data objects.
*/
static const char *pgmName; /* Program name (w/o directory). */
static boolean verbose = false; /* Verbose mode. */
/*
** Usage macro.
*/
#define USAGE \
{ \
fprintf( stderr, \
"Usage: %s [-v] [-s scope_id] [host [service]]\n", \
pgmName ); \
exit( 127 ); \
} /* End USAGE macro. */
/*
** This "macro" (even though it's really a function) is loosely based on the
** CHK() macro by Dr. V. Vinge (see server code). The status parameter is
** a boolean expression indicating the return code from one of the usual system
** calls that returns -1 on error. If a system call error occurred, an alert
** is written to stderr. It returns a boolean value indicating success/failure
** of the system call.
**
** Example: if ( !SYSCALL( "write",
** count = write( fd, bfr, size ) ) )
** {
** // Error processing... but SYSCALL() will have already taken
** // care of dumping an error alert to stderr.
** }
*/
static __inline boolean SYSCALL( const char *syscallName,
int lineNbr,
int status )
{
if ( ( status == -1 ) && verbose )
{
fprintf( stderr,
"%s (line %d): System call failed ('%s') - %s.\n",
pgmName,
lineNbr,
syscallName,
strerror( errno ) );
}
return status != -1; /* True if the system call was successful. */
} /* End SYSCALL() */
/******************************************************************************
* Function: main
*
* Description:
* Connect to a remote time-of-day service and write the remote host's TOD to
* stdout.
*
* Parameters:
* The usual argc & argv parameters to a main() program.
*
* Return Value:
* This function always returns zero.
******************************************************************************/
int main( int argc,
char *argv[ ] )
{
const char *host = DFLT_HOST;
int opt;
int sckt;
unsigned int scopeId = if_nametoindex( DFLT_SCOPE_ID );
const char *service = DFLT_SERVICE;
/*
** Determine the program name (w/o directory prefix).
*/
pgmName = (const char*) strrchr( argv[ 0 ], '/' );
pgmName = pgmName == NULL ? argv[ 0 ] : pgmName+1;
/*
** Process command line options.
*/
opterr = 0; /* Turns off "invalid option" error messages. */
while ( ( opt = getopt( argc, argv, VALIDOPTS ) ) != -1 )
{
switch ( opt )
{
case 's': /* Scope identifier (IPv6 kluge). */
{
scopeId = if_nametoindex( optarg );
if ( scopeId == 0 )
{
fprintf( stderr,
"%s: Unknown network interface (%s).\n",
pgmName,
optarg );
USAGE;
}
break;
}
case 'v': /* Verbose mode. */
{
verbose = true;
break;
}
default:
{
USAGE;
}
} /* End SWITCH on command option. */
} /* End WHILE processing command options. */
/*
** Process command arguments. At the end of the above loop, optind is the
** index of the first NON-option argv element.
*/
switch ( argc - optind )
{
case 2: /* Both host & service are specified on the command line. */
{
service = argv[ optind + 1 ];
/***** Fall through *****/
}
case 1: /* Host is specified on the command line. */
{
host = argv[ optind ];
/***** Fall through *****/
}
case 0: /* Use default host & service. */
{
break;
}
default:
{
USAGE;
}
} /* End SWITCH on number of command arguments. */
/*
** Open a connection to the indicated host/service.
**
** Note that if all three of the following conditions are met, then the
** scope identifier remains unresolved at this point.
** 1) The default network interface is unknown for some reason.
** 2) The -s option was not used on the command line.
** 3) An IPv6 "scoped address" was not specified for the hostname on the
** command line.
** If the above three conditions are met, then only an IPv4 socket can be
** opened (connect(2) fails without the scope ID properly set for IPv6
** sockets).
*/
if ( ( sckt = openSckt( host,
service,
scopeId ) ) == INVALID_DESC )
{
fprintf( stderr,
"%s: Sorry... a connection could not be established.\n",
pgmName );
exit( 1 );
}
/*
** Get the remote time-of-day.
*/
tod( sckt );
/*
** Close the connection and terminate.
*/
(void) SYSCALL( "close",
__LINE__,
close( sckt ) );
return 0;
} /* End main() */
/******************************************************************************
* Function: openSckt
*
* Description:
* Sets up a TCP connection to a remote server. Getaddrinfo(3) is used to
* perform lookup functions and can return multiple address records (i.e. a
* list of 'struct addrinfo' records). This function traverses the list and
* tries to establish a connection to the remote server. The function ends
* when either a connection has been established or all records in the list
* have been processed.
*
* Parameters:
* host - A pointer to a character string representing the hostname or IP
* address (IPv4 or IPv6) of the remote server.
* service - A pointer to a character string representing the service name or
* well-known port number.
* scopeId - For IPv6 sockets only. This is the index corresponding to the
* network interface on which to set up the connection. This
* parameter is ignored for IPv4 sockets or when an IPv6 "scoped
* address" is specified in 'host' (i.e. where the colon-hex
* network address is augmented with the scope ID).
*
* Return Value:
* Returns the socket descriptor for the connection, or INVALID_DESC if all
* address records have been processed and a connection could not be
* established.
******************************************************************************/
static int openSckt( const char *host,
const char *service,
unsigned int scopeId )
{
struct addrinfo *ai;
int aiErr;
struct addrinfo *aiHead;
struct addrinfo hints;
sockaddr_in6_t *pSadrIn6;
int sckt;
/*
** Initialize the 'hints' structure for getaddrinfo(3).
**
** Notice that the 'ai_family' field is set to PF_UNSPEC, indicating to
** return both IPv4 and IPv6 address records for the host/service. Most of
** the time, the user isn't going to care whether an IPv4 connection or an
** IPv6 connection is established; the user simply wants to exchange data
** with the remote host and doesn't care how it's done. Sometimes, however,
** the user might want to explicitly specify the type of underlying socket.
** It is left as an exercise for the motivated reader to add a command line
** option allowing the user to specify the IP protocol, and then process the
** list of addresses accordingly (it's not that difficult).
*/
memset( &hints, 0, sizeof( hints ) );
hints.ai_family = PF_UNSPEC; /* IPv4 or IPv6 records (don't care). */
hints.ai_socktype = SOCK_STREAM; /* Connection-oriented byte stream. */
hints.ai_protocol = IPPROTO_TCP; /* TCP transport layer protocol only. */
/*
** Look up the host/service information.
*/
if ( ( aiErr = getaddrinfo( host,
service,
&hints,
&aiHead ) ) != 0 )
{
fprintf( stderr,
"%s (line %d): ERROR - %s.\n",
pgmName,
__LINE__,
gai_strerror( aiErr ) );
return INVALID_DESC;
}
/*
** Go through the list and try to open a connection. Continue until either
** a connection is established or the entire list is exhausted.
*/
for ( ai = aiHead, sckt = INVALID_DESC;
( ai != NULL ) && ( sckt == INVALID_DESC );
ai = ai->ai_next )
{
/*
** IPv6 kluge. Make sure the scope ID is set.
*/
if ( ai->ai_family == PF_INET6 )
{
pSadrIn6 = (sockaddr_in6_t*) ai->ai_addr;
if ( pSadrIn6->sin6_scope_id == 0 )
{
pSadrIn6->sin6_scope_id = scopeId;
} /* End IF the scope ID wasn't set. */
} /* End IPv6 kluge. */
/*
** Display the address info for the remote host.
*/
if ( verbose )
{
/*
** Temporary character string buffers for host & service.
*/
char hostBfr[ NI_MAXHOST ];
char servBfr[ NI_MAXSERV ];
/*
** Display the address information just fetched. Start with the
** common (protocol-independent) stuff first.
*/
fprintf( stderr,
"Address info:\n"
" ai_flags = 0x%02X\n"
" ai_family = %d (PF_INET = %d, PF_INET6 = %d)\n"
" ai_socktype = %d (SOCK_STREAM = %d, SOCK_DGRAM = %d)\n"
" ai_protocol = %d (IPPROTO_TCP = %d, IPPROTO_UDP = %d)\n"
" ai_addrlen = %d (sockaddr_in = %d, "
"sockaddr_in6 = %d)\n",
ai->ai_flags,
ai->ai_family,
PF_INET,
PF_INET6,
ai->ai_socktype,
SOCK_STREAM,
SOCK_DGRAM,
ai->ai_protocol,
IPPROTO_TCP,
IPPROTO_UDP,
ai->ai_addrlen,
sizeof( struct sockaddr_in ),
sizeof( struct sockaddr_in6 ) );
/*
** Display the protocol-specific formatted address.
*/
getnameinfo( ai->ai_addr,
ai->ai_addrlen,
hostBfr,
sizeof( hostBfr ),
servBfr,
sizeof( servBfr ),
NI_NUMERICHOST | NI_NUMERICSERV );
switch ( ai->ai_family )
{
case PF_INET: /* IPv4 address record. */
{
sockaddr_in_t *pSadrIn = (sockaddr_in_t*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin_addr: %s\n"
" sin_port: %s\n",
pSadrIn->sin_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr );
break;
} /* End CASE of IPv4 record. */
case PF_INET6: /* IPv6 address record. */
{
pSadrIn6 = (sockaddr_in6_t*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin6_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin6_addr: %s\n"
" sin6_port: %s\n"
" sin6_flowinfo: %d\n"
" sin6_scope_id: %d\n",
pSadrIn6->sin6_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr,
pSadrIn6->sin6_flowinfo,
pSadrIn6->sin6_scope_id );
break;
} /* End CASE of IPv6 record. */
default: /* Can never get here, but just for completeness. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown protocol family (%d).\n",
pgmName,
__LINE__,
ai->ai_family );
break;
} /* End DEFAULT case (unknown protocol family). */
} /* End SWITCH on protocol family. */
} /* End IF verbose mode. */
/*
** Create a socket.
*/
if ( !SYSCALL( "socket",
__LINE__,
sckt = socket( ai->ai_family,
ai->ai_socktype,
ai->ai_protocol ) ) )
{
sckt = INVALID_DESC;
continue; /* Try the next address record in the list. */
}
/*
** Connect to the remote host.
*/
if ( !SYSCALL( "connect",
__LINE__,
connect( sckt,
ai->ai_addr,
ai->ai_addrlen ) ) )
{
(void) close( sckt ); /* Could use SYSCALL() again here, but why? */
sckt = INVALID_DESC;
continue; /* Try the next address record in the list. */
}
} /* End FOR each address record returned by getaddrinfo(3). */
/*
** Clean up & return.
*/
freeaddrinfo( aiHead );
return sckt;
} /* End openSckt() */
/******************************************************************************
* Function: tod
*
* Description:
* Receive the time-of-day from the remote server and write it to stdout.
*
* Parameters:
* sckt - The socket descriptor for the connection.
*
* Return Value: None.
******************************************************************************/
static void tod( int sckt )
{
char bfr[ MAXBFRSIZE+1 ];
int inBytes;
/*
** The client never sends anything, so shut down the write side of the
** connection.
*/
if ( !SYSCALL( "shutdown",
__LINE__,
shutdown( sckt, SHUT_WR ) ) )
{
return;
}
/*
** Read the time-of-day from the remote host.
*/
do
{
if ( !SYSCALL( "read",
__LINE__,
inBytes = read( sckt,
bfr,
MAXBFRSIZE ) ) )
{
return;
}
bfr[ inBytes ] = '\0'; /* Null-terminate the received string. */
fputs( bfr, stdout ); /* Null string if EOF (inBytes == 0). */
} while ( inBytes > 0 );
fflush( stdout );
} /* End tod() */
23.1.4.3. 'Daytime' UDP Client Code
The UDP client code is found in file tod6uc.c (time-of-day IPv6 UDP client). It is almost an exact duplicate of the TCP client (and in fact was derived from it), but is included in this HowTo for completeness. Once built, the UDP client may be started using
the following command syntax (assuming tod6uc is the executable file):
tod6uc [-v] [-s scope_id] [host [service]]
ARGUMENTS:
host
The hostname or IP address (dotted decimal or colon-hex) of the remote host providing the service. Default is "localhost".
service
The UDP service (or well-known port number) to which datagrams are sent. Default is "daytime".
OPTIONS:
-s
This option is only meaningful for IPv6 addresses, and is used to set the scope identifier (i.e. the network interface on which to exchange datagrams). Default is "eth0". If host is a scoped address, this option is ignored.
-v
Turn on verbose mode.
The UDP client source code contained in tod6uc.c follows:
/******************************************************************************
* File: tod6uc.c
* Description: Contains source code for an IPv6-capable 'daytime' UDP client.
* Author: John Wenker, Sr. Software Engineer
* Performance Technologies, San Diego, USA
******************************************************************************/
/*
** System header files.
*/
#include <errno.h> /* errno declaration and error codes. */
#include <net/if.h> /* if_nametoindex(3). */
#include <netdb.h> /* getaddrinfo(3) and associated definitions. */
#include <netinet/in.h> /* sockaddr_in and sockaddr_in6 definitions. */
#include <stdio.h> /* printf(3) et al. */
#include <stdlib.h> /* exit(2). */
#include <string.h> /* String manipulation and memory functions. */
#include <sys/socket.h> /* Socket functions (socket(2), connect(2), etc). */
#include <unistd.h> /* getopt(3), recvfrom(2), sendto(2), etc. */
/*
** Constants & macros.
*/
#define DFLT_HOST "localhost" /* Default server name. */
#define DFLT_SCOPE_ID "eth0" /* Default scope identifier. */
#define DFLT_SERVICE "daytime" /* Default service name. */
#define INVALID_DESC -1 /* Invalid file (socket) descriptor. */
#define MAXBFRSIZE 256 /* Max bfr sz to read remote TOD. */
#define VALIDOPTS "s:v" /* Valid command options. */
/*
** Type definitions (for convenience).
*/
typedef enum { false = 0, true } boolean;
typedef struct sockaddr_in sockaddr_in_t;
typedef struct sockaddr_in6 sockaddr_in6_t;
/*
** Prototypes for internal helper functions.
*/
static int openSckt( const char *host,
const char *service,
unsigned int scopeId );
static void tod( int sckt );
/*
** Global (within this file only) data objects.
*/
static const char *pgmName; /* Program name (w/o directory). */
static boolean verbose = false; /* Verbose mode. */
/*
** Usage macro.
*/
#define USAGE \
{ \
fprintf( stderr, \
"Usage: %s [-v] [-s scope_id] [host [service]]\n", \
pgmName ); \
exit( 127 ); \
} /* End USAGE macro. */
/*
** This "macro" (even though it's really a function) is loosely based on the
** CHK() macro by Dr. V. Vinge (see server code). The status parameter is
** a boolean expression indicating the return code from one of the usual system
** calls that returns -1 on error. If a system call error occurred, an alert
** is written to stderr. It returns a boolean value indicating success/failure
** of the system call.
**
** Example: if ( !SYSCALL( "write",
** count = write( fd, bfr, size ) ) )
** {
** // Error processing... but SYSCALL() will have already taken
** // care of dumping an error alert to stderr.
** }
*/
static __inline boolean SYSCALL( const char *syscallName,
int lineNbr,
int status )
{
if ( ( status == -1 ) && verbose )
{
fprintf( stderr,
"%s (line %d): System call failed ('%s') - %s.\n",
pgmName,
lineNbr,
syscallName,
strerror( errno ) );
}
return status != -1; /* True if the system call was successful. */
} /* End SYSCALL() */
/******************************************************************************
* Function: main
*
* Description:
* Connect to a remote time-of-day service and write the remote host's TOD to
* stdout.
*
* Parameters:
* The usual argc & argv parameters to a main() program.
*
* Return Value:
* This function always returns zero.
******************************************************************************/
int main( int argc,
char *argv[ ] )
{
const char *host = DFLT_HOST;
int opt;
int sckt;
unsigned int scopeId = if_nametoindex( DFLT_SCOPE_ID );
const char *service = DFLT_SERVICE;
/*
** Determine the program name (w/o directory prefix).
*/
pgmName = (const char*) strrchr( argv[ 0 ], '/' );
pgmName = pgmName == NULL ? argv[ 0 ] : pgmName+1;
/*
** Process command line options.
*/
opterr = 0; /* Turns off "invalid option" error messages. */
while ( ( opt = getopt( argc, argv, VALIDOPTS ) ) != -1 )
{
switch ( opt )
{
case 's': /* Scope identifier (IPv6 kluge). */
{
scopeId = if_nametoindex( optarg );
if ( scopeId == 0 )
{
fprintf( stderr,
"%s: Unknown network interface (%s).\n",
pgmName,
optarg );
USAGE;
}
break;
}
case 'v': /* Verbose mode. */
{
verbose = true;
break;
}
default:
{
USAGE;
}
} /* End SWITCH on command option. */
} /* End WHILE processing command options. */
/*
** Process command arguments. At the end of the above loop, optind is the
** index of the first NON-option argv element.
*/
switch ( argc - optind )
{
case 2: /* Both host & service are specified on the command line. */
{
service = argv[ optind + 1 ];
/***** Fall through *****/
}
case 1: /* Host is specified on the command line. */
{
host = argv[ optind ];
/***** Fall through *****/
}
case 0: /* Use default host & service. */
{
break;
}
default:
{
USAGE;
}
} /* End SWITCH on number of command arguments. */
/*
** Open a connection to the indicated host/service.
**
** Note that if all three of the following conditions are met, then the
** scope identifier remains unresolved at this point.
** 1) The default network interface is unknown for some reason.
** 2) The -s option was not used on the command line.
** 3) An IPv6 "scoped address" was not specified for the hostname on the
** command line.
** If the above three conditions are met, then only an IPv4 socket can be
** opened (connect(2) fails without the scope ID properly set for IPv6
** sockets).
*/
if ( ( sckt = openSckt( host,
service,
scopeId ) ) == INVALID_DESC )
{
fprintf( stderr,
"%s: Sorry... a connectionless socket could "
"not be set up.\n",
pgmName );
exit( 1 );
}
/*
** Get the remote time-of-day.
*/
tod( sckt );
/*
** Close the connection and terminate.
*/
(void) SYSCALL( "close",
__LINE__,
close( sckt ) );
return 0;
} /* End main() */
/******************************************************************************
* Function: openSckt
*
* Description:
* Sets up a UDP socket to a remote server. Getaddrinfo(3) is used to
* perform lookup functions and can return multiple address records (i.e. a
* list of 'struct addrinfo' records). This function traverses the list and
* tries to establish a connection to the remote server. The function ends
* when either a connection has been established or all records in the list
* have been processed.
*
* Parameters:
* host - A pointer to a character string representing the hostname or IP
* address (IPv4 or IPv6) of the remote server.
* service - A pointer to a character string representing the service name or
* well-known port number.
* scopeId - For IPv6 sockets only. This is the index corresponding to the
* network interface on which to exchange datagrams. This
* parameter is ignored for IPv4 sockets or when an IPv6 "scoped
* address" is specified in 'host' (i.e. where the colon-hex
* network address is augmented with the scope ID).
*
* Return Value:
* Returns the socket descriptor for the connection, or INVALID_DESC if all
* address records have been processed and a socket could not be initialized.
******************************************************************************/
static int openSckt( const char *host,
const char *service,
unsigned int scopeId )
{
struct addrinfo *ai;
int aiErr;
struct addrinfo *aiHead;
struct addrinfo hints;
sockaddr_in6_t *pSadrIn6;
int sckt;
/*
** Initialize the 'hints' structure for getaddrinfo(3).
**
** Notice that the 'ai_family' field is set to PF_UNSPEC, indicating to
** return both IPv4 and IPv6 address records for the host/service. Most of
** the time, the user isn't going to care whether an IPv4 connection or an
** IPv6 connection is established; the user simply wants to exchange data
** with the remote host and doesn't care how it's done. Sometimes, however,
** the user might want to explicitly specify the type of underlying socket.
** It is left as an exercise for the motivated reader to add a command line
** option allowing the user to specify the IP protocol, and then process the
** list of addresses accordingly (it's not that difficult).
*/
memset( &hints, 0, sizeof( hints ) );
hints.ai_family = PF_UNSPEC; /* IPv4 or IPv6 records (don't care). */
hints.ai_socktype = SOCK_DGRAM; /* Connectionless communication. */
hints.ai_protocol = IPPROTO_UDP; /* UDP transport layer protocol only. */
/*
** Look up the host/service information.
*/
if ( ( aiErr = getaddrinfo( host,
service,
&hints,
&aiHead ) ) != 0 )
{
fprintf( stderr,
"%s (line %d): ERROR - %s.\n",
pgmName,
__LINE__,
gai_strerror( aiErr ) );
return INVALID_DESC;
}
/*
** Go through the list and try to open a connection. Continue until either
** a connection is established or the entire list is exhausted.
*/
for ( ai = aiHead, sckt = INVALID_DESC;
( ai != NULL ) && ( sckt == INVALID_DESC );
ai = ai->ai_next )
{
/*
** IPv6 kluge. Make sure the scope ID is set.
*/
if ( ai->ai_family == PF_INET6 )
{
pSadrIn6 = (sockaddr_in6_t*) ai->ai_addr;
if ( pSadrIn6->sin6_scope_id == 0 )
{
pSadrIn6->sin6_scope_id = scopeId;
} /* End IF the scope ID wasn't set. */
} /* End IPv6 kluge. */
/*
** Display the address info for the remote host.
*/
if ( verbose )
{
/*
** Temporary character string buffers for host & service.
*/
char hostBfr[ NI_MAXHOST ];
char servBfr[ NI_MAXSERV ];
/*
** Display the address information just fetched. Start with the
** common (protocol-independent) stuff first.
*/
fprintf( stderr,
"Address info:\n"
" ai_flags = 0x%02X\n"
" ai_family = %d (PF_INET = %d, PF_INET6 = %d)\n"
" ai_socktype = %d (SOCK_STREAM = %d, SOCK_DGRAM = %d)\n"
" ai_protocol = %d (IPPROTO_TCP = %d, IPPROTO_UDP = %d)\n"
" ai_addrlen = %d (sockaddr_in = %d, "
"sockaddr_in6 = %d)\n",
ai->ai_flags,
ai->ai_family,
PF_INET,
PF_INET6,
ai->ai_socktype,
SOCK_STREAM,
SOCK_DGRAM,
ai->ai_protocol,
IPPROTO_TCP,
IPPROTO_UDP,
ai->ai_addrlen,
sizeof( struct sockaddr_in ),
sizeof( struct sockaddr_in6 ) );
/*
** Display the protocol-specific formatted address.
*/
getnameinfo( ai->ai_addr,
ai->ai_addrlen,
hostBfr,
sizeof( hostBfr ),
servBfr,
sizeof( servBfr ),
NI_NUMERICHOST | NI_NUMERICSERV );
switch ( ai->ai_family )
{
case PF_INET: /* IPv4 address record. */
{
sockaddr_in_t *pSadrIn = (sockaddr_in_t*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin_addr: %s\n"
" sin_port: %s\n",
pSadrIn->sin_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr );
break;
} /* End CASE of IPv4 record. */
case PF_INET6: /* IPv6 address record. */
{
pSadrIn6 = (sockaddr_in6_t*) ai->ai_addr;
fprintf( stderr,
" ai_addr = sin6_family: %d (AF_INET = %d, "
"AF_INET6 = %d)\n"
" sin6_addr: %s\n"
" sin6_port: %s\n"
" sin6_flowinfo: %d\n"
" sin6_scope_id: %d\n",
pSadrIn6->sin6_family,
AF_INET,
AF_INET6,
hostBfr,
servBfr,
pSadrIn6->sin6_flowinfo,
pSadrIn6->sin6_scope_id );
break;
} /* End CASE of IPv6 record. */
default: /* Can never get here, but just for completeness. */
{
fprintf( stderr,
"%s (line %d): ERROR - Unknown protocol family (%d).\n",
pgmName,
__LINE__,
ai->ai_family );
break;
} /* End DEFAULT case (unknown protocol family). */
} /* End SWITCH on protocol family. */
} /* End IF verbose mode. */
/*
** Create a socket.
*/
if ( !SYSCALL( "socket",
__LINE__,
sckt = socket( ai->ai_family,
ai->ai_socktype,
ai->ai_protocol ) ) )
{
sckt = INVALID_DESC;
continue; /* Try the next address record in the list. */
}
/*
** Set the target destination for the remote host on this socket. That
** is, this socket only communicates with the specified host.
*/
if ( !SYSCALL( "connect",
__LINE__,
connect( sckt,
ai->ai_addr,
ai->ai_addrlen ) ) )
{
(void) close( sckt ); /* Could use SYSCALL() again here, but why? */
sckt = INVALID_DESC;
continue; /* Try the next address record in the list. */
}
} /* End FOR each address record returned by getaddrinfo(3). */
/*
** Clean up & return.
*/
freeaddrinfo( aiHead );
return sckt;
} /* End openSckt() */
/******************************************************************************
* Function: tod
*
* Description:
* Receive the time-of-day from the remote server and write it to stdout.
*
* Parameters:
* sckt - The socket descriptor for the connection.
*
* Return Value: None.
******************************************************************************/
static void tod( int sckt )
{
char bfr[ MAXBFRSIZE+1 ];
int inBytes;
/*
** Send a datagram to the server to wake it up. The content isn't
** important, but something must be sent to let it know we want the TOD.
*/
if ( !SYSCALL( "write",
__LINE__,
write( sckt, "Are you there?", 14 ) ) )
{
return;
}
/*
** Read the time-of-day from the remote host.
*/
if ( !SYSCALL( "read",
__LINE__,
inBytes = read( sckt,
bfr,
MAXBFRSIZE ) ) )
{
return;
}
bfr[ inBytes ] = '\0'; /* Null-terminate the received string. */
fputs( bfr, stdout ); /* Null string if EOF (inBytes == 0). */
fflush( stdout );
} /* End tod() */