#include <sys.types.h>
#include <sys.socket.h>
#include <netinet.in.h> /* only for AF_INET and AF_INET6 */
#include <iso.h> /* only for AF_ISO */
Kernighan-Ritchie-C:
int connect(s, name, namelen);
int s;
int namelen;
struct sockaddr_in *name; /* only for AF_INET */
struct sockaddr_in6 *name; /* only for AF_INET6 */
struct sockaddr_iso *name; /* only for AF_ISO */
ANSI-C:
int connect(int s, struct sockaddr* name, int namelen);
Description
A task uses connect() to initiate communications with a partner socket via socket s of type SOCK_STREAM. If the partner socket is of type SOCK_DGRAM, the partner information is only saved in socket s.
The s parameter designates the socket on which the task initiates communications with another socket. name is a pointer to the address of the communications partner. The communications partner is a socket which belongs to the same address family. In the AF_ISO address family both sockets must belong to the same address family.
Communication in both directions is possible between the AF_INET and AF_INET6 address families with the help of IPv4-mapped IPv6 addresses, i.e. it is possible to establish a connection between an AF_INET socket on a host, which only has IPv4 addresses, and an AF_INET6 partner socket on a host, which exclusively or partly has IPv6 addresses.
*name is an address in the address range of the socket to which the connection is to be initiated. Each address range interprets the name parameter in its own way. namelen contains the length of the address of the communications partner in bytes.
The exact functionality of connect() is determined by the address family used.
connect() for AF_INET and AF_INET6
The manner in which connect() proceeds differs according to whether the socket type is SOCK_STREAM or SOCK_DGRAM.
With a socket of type SOCK_STREAM (stream socket), connect() sends a connection request to a partner and tries in this way to set up a connection to this partner. The partner is specified with the name parameter. For example, a client task uses connect() to initiate a connection to a server on a stream socket.
Stream sockets can generally set up a connection with connect() only once.With a socket of type SOCK_DGRAM (datagram socket), a task uses connect() to define the name of the communications partner with which data is to be exchanged. The task then sends the datagrams to this communications partner. This communications partner is also the only socket from which the task can receive datagrams.
If both an IP address and a port not equal to 0 are specified, the transport system generates a route to which it assigns a local interface. This local interface can be inquired using getsockname().
connect() can be used several times with datagram sockets to change the communications partner. The assignment to a specific partner can be terminated by entering a null pointer for the name parameter.
connect() for AF_ISO
connect() is used to set up the connection to an ISO partner. The partner must not only accept the connection request with accept(), but must also call a transfer function (send() or sendmsg()) as confirmation. However, no data need be sent with the transfer function. This can, for example, be done with a sendmsg() call.
Here again, the connection between two end points can only be set up once by connect().
Return value
0:
If successful.
-1:
If errors occur. errno is set to indicate the error.
Errors indicated by errno
EADDRINUSE
The specified address is already in use.
EAFNOSUPPORT
Addresses in the specified address family cannot be used with this socket.
EBADF
s is not a valid descriptor.
ECONNREFUSED
The connection attempt was rejected, probably because the requested service was not available at the time of the function call.
EFAULT
The length of the area for accepting the address is too small.
EINPROGRESS
Connection setup has not yet been completed successfully.
EISCONN
The socket already has a connection.
ENETDOWN
The connection to the network is down.
Note
If the connection is established with a non-blocking socket of the type SOCK_STREAM (either with soc_ioctl() NONBLOCKING being set or by using an external bourse), in the case of an application produced with Sockets >= V2.6 a return value of -1 can occur with errno EINPROGRESS. This means that the connection has not been successfully established at the time control is returned to the caller. Consequently, before this socket is used you must use select() or soc_poll() to check that it can be written to.
When a write/read access takes place before the connection has been fully established, it is rejected with a return value of -1 and the errno EWOULDBLOCK.
See also
accept(), getsockname() select(), soc_close(), socket()