scds_fm_net_connect(3HA) (Sun Cluster Reference Manual for Solaris OS)

Sun Cluster Reference Manual for Solaris OS

scds_fm_net_connect(3HA)

NAME

scds_fm_net_connect– establish a TCP connection to an application

SYNOPSIS

cc [flags…]-I /usr/cluster/include file -L /usr/cluster/lib -l dsdev
#include <rgm/libdsdev.h>

handle

socklist

count

addr

timeout

DESCRIPTION

The scds_fm_net_connect() function establishes one or more TCP connections (depending on the protocol value of Port_list for each address, as described below) to a process that is being monitored.

You can retrieve a list of network addresses for the resource by using scds_get_netaddr_list(3HA). That call also fills the protocol value for each address in the list. If tcp6 is specified as the protocol in Port_list for that address, the protocol value is set to SCDS_IPPROTO_TCP6. If tcp is specified as the protocol in Port_list for that address or if no protocol is specified in Port_list, the protocol value is set to SCDS_IPPROTO_TCP.

This function also resolves the hostname that is supplied in addr and connects to:

The IPv4 address of the hostname at the specified port, if the protocol that is specified in addr is SCDS_IPPROTO_TCP.
Both the IPv4 address (if there is one) and the IPv6 address (if there is one) of the hostname at the specified port, if the protocol specified in addr is SCDS_IPPROTO_TCP6. The status and the file descriptor, if applicable, are stored in the scds_socket_t array that is supplied to this function. The first member of this array is used for the IPv4 mapping and the second member of this array is used for IPv6. The status can be set to one of the following values:
- SCDS_FMSOCK_OK — The operation succeeded and the associated socket file descriptor is valid.
- SCDS_FMSOCK_NA — The address type (IPv4 or IPv6) does not apply to this hostname. If the hostname contains only one or more IPv4 mappings, the status of the second member in the array that is passed to this function is set to SCDS_FMSOCK_NA. The associated socket file descriptor is set to an unknown value, and should never be used.
- SCDS_FMSOCK_ERR — The operation failed or timed out. The associated socket file descriptor is set to an unknown value, and should never be used.

PARAMETERS

The following parameters are supported:

handle: The handle that is returned by scds_initialize(3HA).
socklist: An array of SCDS_MAX_IPADDR_TYPES members of type scds_socket_t. Each member in the array holds a status and a socket file descriptor for a TCP connection. This parameter is an output argument that is set by this function.
count: The number of members in the socklist array. Set this parameter to SCDS_MAX_IPADDR_TYPES.
addr: The hostname, TCP port number, and protocol identifier that specify where the process is listening.
timeout: The timeout value in seconds. Each socket gets the same time period for a connection to be established before it is timed out. As these time intervals proceed in parallel, this value is effectively the maximum time that the function takes to execute.

RETURN VALUES

The scds_fm_net_connect() function returns the following values:

0: The function succeeded. At least one socket connected.
SCHA_ERR_INVAL: The function was called with invalid paramaters.
nonzero: Not a single connection could be established, due to a timeout, a refused connection, or some other error. You can inspect the status field of all members of the socklist array that are set to SCDS_FMSOCK_ERR to determine the exact error.

ERRORS

SCHA_ERR_NOERR: Indicates that the function succeeded.
SCHA_ERR_INTERNAL: Indicates that an internal error occurred while the function was executing.
SCHA_ERR_STATE: Indicates that the connection request was refused by the server.
SCHA_ERR_TIMEOUT: Indicates that the connection request timed out.

EXAMPLES

Example 1 Using the `scds_fm_net_connect()` Function

/* this function is called repeatedly, 
   after thorough_probe_interval seconds */
int probe(scds_handle_t scds_handle, ...)
{
	scds_socket_t socklist[SCDS_MAX_IPADDR_TYPES];
	...

	/* for each hostname/port/proto */
	for (i = 0; i < netaddr->num_netaddrs, i++) {
		if (scds_fm_net_connect(scds_handle, socklist,
		    SCDS_MAX_IPADDR_TYPES, netaddr[i], timeout) !=
		    SCHA_ERR_NOERR)
			{
				/* failed completely */
				...
		} else {
			/* at least one sock connected */
			for (j = 0, j < SCDS_MAX_IPADDR_TYPES, j++) {
				if (socklist[j].status == SCDS_FM_SOCK_NA)
					continue;

				if (socklist[j].status == SCDS_FMSOCK_ERR) {
					/* this particular connection failed */
					scds_syslog(LOG_ERR, "Failed: %s",
					    scds_error_string(socklist[j].err));
					continue;
				}

				/* use socklist[i].fd to perform write/read */
				...
			}
			(void) scds_fm_net_disconnect(scds_handle, socklist,
			    SCDS_MAX_IPADDR_TYPES, remaining_time);
		}
		
	}
	...
	return (result);
}

FILES

/usr/cluster/include/rgm/libdsdev.h: Include file
/usr/cluster/lib/libdsdev.so: Library

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	`SUNWscdev`
Interface Stability	Evolving