SYNOPSIS

    #include "libut/ut.h"
    int UT_net_connect(char *name, UT_fd_cb *cb, void *data, int flags,...);

DESCRIPTION

This function attempts to establish a TCP/IP socket to a particular host and port. The function also permits the source IP address and port to be specified, or these can be chosen automatically by the kernel.

The name argument is a descriptive name for the connection (which will be copied, and silently truncated if too long). This name is only used in the output of the fds control port command and in log messages.

The cb argument specifies the callback to be invoked when the connection succeeds or fails, and (in the case of success) when data from the remote side is readable. See the CALLBACK section below.

The data argument is an opaque pointer that is passed back to the callback.

The flags argument is a bitwise-OR using these pre-defined constants:

UT_CONNECT_FROM_IPPORT

If this flag is specified, the following argument is an IP:port string (e.g., ``127.0.0.1:4444'') specifying the source IP address and port number to use. The port number can be 0, in which case the choice is left to the kernel. This flag may be omitted in which case the source IP address and port are automatically chosen by the kernel.

UT_CONNECT_TO_IPPORT

This flag is mandatory. The last argument to the function is an IP:port string (e.g., ``127.0.0.1:5555'') specifying the destination IP address and port number to which the connection should be made.

THE CALLBACK

The I/O callback must have this prototype: int (UT_fd_cb)(int fd, char *name, int status, void *data);

The name and data arguments are passed to the callback exactly as they were passed to UT_net_connect(). The fd argument is the file descriptor of the socket. The status argument informs the callback of the disposition of the file descriptor using the following bits (other bits may be set and must be ignored):

UTFD_IS_CONSUCCESS

This is initial notification that the connection has been accepted by the remote side.

UTFD_IS_CONFAILURE

The connection attempt failed. The reason is indicated in the log. Do not close the file descriptor; libut does this.

UTFD_IS_READABLE

The file descriptor is readable. (This can also indicate EOF).

Closing the connection

When the connection is no longer needed, or the callback detects that the remote side has closed the socket, the callback should call close(2) and UT_fd_unreg(2) on the file descriptor.

Callback return value

The callback's return value is ignored.

RETURN VALUE

If an error occurs, -1 is returned and the reason is logged. A non-negative return value indicates that a connection attempt has been initiated; it may or may not be accepted. The callback will be notified when the connection is accepted or fails.

RELATED CONTROL PORT COMMANDS

The fds control port command displays connecting sockets, and other file descriptors.

SEE ALSO

UT_net_resolve(3), UT_fd_cntl(3), UT_net_listen(3)

AUTHOR

Troy D. Hanson <thanson@users.sourceforge.net>