HPlogo HP-UX Reference Volume 3 of 5 > c

connect(2)
» 

Technical documentation

Complete book in PDF

 » Table of Contents

 » Index

spacerspacerspacer
spacer
spacer
  		 
 

NAME

connect — initiate a connection on a socket

SYNOPSIS

#include <sys/socket.h>

AF_CCITT only

#include <x25/x25addrstr.h>

AF_INET and AF_VME_LINK only

#include <netinet/in.h>

AF_UNIX only

#include <sys/un.h>

int connect(int s, const void *addr, int addrlen);

_XOPEN_SOURCE_EXTENDED only (UNIX 98)

int connect(int s, const struct sockaddr *addr, socklen_t addrlen);

Obsolescent _XOPEN_SOURCE_EXTENDED only (UNIX 95)

int connect(int s, const struct sockaddr *addr, size_t addrlen);

DESCRIPTION

The connect() function initiates a connection on a socket.

s is a socket descriptor.

addr is a pointer to a socket address structure containing the address of a remote socket to which a connection is to be established.

addrlen is the size of this address structure. Since the size of the socket address structure varies among socket address families, the correct socket address structure should be used with each address family (for example, struct sockaddr_in for AF_INET and AF_VME_LINK and struct sockaddr_un for AF_UNIX). Typically, the sizeof() function is used to pass this value (for example, sizeof(struct sockaddr_in)).

If the socket is of type SOCK_DGRAM, connect() specifies the peer address to which messages are to be sent, and the call returns immediately. Furthermore, this socket can only receive messages sent from this address.

If the socket is of type SOCK_STREAM, connect() attempts to contact the remote host to make a connection between the remote socket (peer) and the local socket specified by s. The call normally blocks until the connection completes. If nonblocking mode has been enabled with the O_NONBLOCK or O_NDELAY fcntl() flags or the FIOSNBIO ioctl() request and the connection cannot be completed immediately, connect() returns an error as described below. In these cases, select() can be used on this socket to determine when the connection has completed by selecting it for writing.

The connect() system call may complete if remote program has a pending listen() even though remote program had not yet issued an accept() system call.

O_NONBLOCK and O_NDELAY are defined in <sys/fcntl.h> and explained in fcntl(2), fcntl(5), and socket(7). FIOSNBIO is defined in <sys/ioctl.h> and explained in ioctl(2), ioctl(5), and socket(7).

If s is a SOCK_STREAM socket that is bound to the same local address as another SOCK_STREAM socket, connect() returns [EADDRINUSE] if addr is the same as the peer address of that other socket. This situation can only happen if the SO_REUSEADDR option has been set on s, which is an AF_INET socket (see getsockopt(2)).

If the AF_INET socket does not already have a local address bound to it (see bind(2)), connect() also binds the socket to a local address chosen by the system.

An AF_VME_LINK socket always binds the socket to a local address chosen by the system.

Generally, stream sockets may successfully connect only once; datagram sockets may use connect() multiple times to change the peer address. For datagram sockets, a side effect of attempting to connect to some invalid address (see ERRORS below) is that the peer address is no longer maintained by the system. An example of an invalid address for a datagram socket is addrlen set to 0 and addr set to any value.

AF_CCITT Only

Use the x25addrstr struct for the address structure. The caller must know the X.121 address of the DTE to which the connection is to be established, including any subaddresses or protocol IDs that may be needed. Refer to af_ccitt(7F) for a detailed description of the x25addrstr address structure. If address-matching by protocol ID, specify the protocol ID with the X25_WR_USER_DATA ioctl() call before issuing the connect() call. The X25_WR_USER_DATA ioctl() call is described in socketx25(7).

DEPENDENCIES

AF_CCITT

The SO_REUSEADDR option to setsockopt() is not supported for sockets in the AF_CCITT address family.

RETURN VALUE

connect() returns the following values:

0

Successful completion.

-1

Failure. errno is set to indicate the error.

ERRORS

If connect() fails, errno is set to one of the following values.

[EADDRINUSE]

The specified address is already in use.

For datagram sockets, the peer address is no longer maintained by the system.

[EADDRNOTAVAIL]

The specified address is not available on this machine, or the socket is a TCP/UDP socket and the zero port number is specified.

For datagram sockets, the peer address is no longer maintained by the system.

[EAFNOSUPPORT]

The specified address is not a valid address for the address family of this socket.

For datagram sockets, the peer address is no longer maintained by the system.

[EALREADY]

Nonblocking I/O is enabled with O_NONBLOCK, O_NDELAY, or FIOSNBIO, and a previous connection attempt has not yet completed.

[EBADF]

s is not a valid file descriptor.

[ECONNREFUSED]

The attempt to connect was forcefully rejected.

[EFAULT]

addr is not a valid pointer.

[EINPROGRESS]

Nonblocking I/O is enabled using O_NONBLOCK, O_NDELAY, or FIOSNBIO, and the connection cannot be completed immediately. This is not a failure. Make the connect() call again a few seconds later. Alternatively, wait for completion by calling select() and selecting for write.

[EINTR]

The connect was interrupted by a signal before the connect sequence was complete. The building of the connection still takes place, even though the user is not blocked on the connect() call.

[EINVAL]

The socket has already been shut down or has a listen() active on it; addrlen is a bad value; an attempt was made to connect() an AF_UNIX socket to an NFS-mounted (remote) name; the X.121 address length is zero, negative, or greater than 15 digits.

For datagram sockets, if addrlen is a bad value, the peer address is no longer maintained by the system.

[EISCONN]

The socket is already connected.

[ENETDOWN]

The X.25 interface specified in the addr struct was found but was not in the initialized state. x25ifname field name is an interface which has been shut down or never initialized or suffered a power failure which erased its state information.

[ENETUNREACH]

The network is not reachable from this host.

For AF_CCITT only: X.25 Level 2 is down. The X.25 link is not working: wires might be broken, connections are loose on the interface hoods at the modem, the modem failed, or noise interfered with the line for an extremely long period of time.

[ENOBUFS]

No buffer space is available. The connect() has failed.

[ENOMEM]

No memory is available. The connect() has failed.

[ENODEV]

The x25ifname field refers to a nonexistent interface.

[ENOSPC]

All available virtual circuits are in use.

[ENOTSOCK]

s is a valid file descriptor, but it is not a socket.

[EOPNOTSUPP]

The socket referenced by s does not support connect(). With X.25 an attempt was made to issue a connect() call on a listen() socket.

[ETIMEDOUT]

Connection establishment timed out without establishing a connection. One reason could be that the connection requests queue at the remote socket may be full (see listen(2)).

OBSOLESCENCE

Currently, the socklen_t and size_t types are the same size. This is compatible with both the UNIX 95 and UNIX 98 profiles. However, in a future release, socklen_t might be a different size, but that should not adversely affect application behavior in this case. Applications may use socklen_t now. But applications that need to be portable to the UNIX 95 profile should follow the X/Open specification (see xopen_networking(7)).

FUTURE DIRECTION

Currently, the default behavior is the HP-UX BSD Sockets; however, it might be changed to X/Open Sockets in a future release. At that time, any HP-UX BSD Sockets behavior that is incompatible with X/Open Sockets might be obsoleted. Applications that conform to the X/Open specification now will avoid migration problems (see xopen_networking(7)).

MULTITHREAD USAGE

The connect() system call is thread-safe. It has a cancellation point; and it is async-cancel safe, async-signal safe, and fork-safe.

AUTHOR

connect() was developed by HP and the University of California, Berkeley.

SEE ALSO

accept(2), getsockname(2), select(2), socket(2), af_ccitt(7F), af_vme_link(7F), socket(7), socketx25(7), xopen_networking(7).



close
  		 


crashconf  
© Hewlett-Packard Development Company, L.P.