SOConnect

Syntax

#include <cafe.h>
#include <cafe/network.h>

int SOConnect(int fd, struct sockaddr *addr, int addrlen);

Parameters

fd Descriptor of the socket to connect.
addr Address to which the socket is to be connected.
addrlen Length of the address (in bytes).

Return Values

0 upon success. Upon failure, returns -1 and errno is set appropriately.

Errors

SO_ELIBNOTREADY Socket library is not initialized.
SO_ENOMEM Insufficient memory in the stack.
SO_ENOTSOCK The argument fd does not refer to a socket.
SO_EOPNOTSUPP Non-supported operation occurred in the stack.
SO_EAFNOSUPPORT Addresses in the specified address family cannot be used with this socket.
SO_EISCONN The socket is already connected.
SO_EALREADY For blocking sockets, indicates that there is already a previous blocked connect call on the same socket.
SO_ETIMEDOUT Connection establishment timed out without establishing a connection.
SO_ECONNREFUSED The attempt to connect was forcefully rejected. The socket must be closed and recreated. Further attempts to connect on this socket will yield SO_EINVAL.
SO_ENETUNREACH The network is not reachable from this host.
SO_EADDRNOTAVAIL The specified address is not available on this machine.
SO_EADDRINUSE The address is already in use.
SO_EINPROGRESS The socket is non-blocking and the connection cannot be completed immediately. It is possible to SOSelect for completion by selecting the socket for writing (for future use).
SO_EABORTED The operation was aborted. When a socket is closed, operations that are blocked on the socket are aborted.
SO_EINVAL Invalid operation.
SO_EBUSY Socket resource manager busy processing requests.
SO_EUNKNOWN Unknown error.
SO_EWOULDBLOCK Requested operation would block.
SO_EFAULT Specified pointer is outside the address space.
SO_ENOBUFS Insufficient resources.
SO_EIEIO I/O error.
SO_ERANGEINVALID Internal API error, invalid error code.
SO_EAPIERROR Internal API error.

Description

The parameter fd is a socket. If it is of type SOCK_DGRAM, then this call specifies the peer with which the socket is to be associated; the address to which datagrams are sent and the only address from which datagrams are received. If it is of type SOCK_STREAM, then this call attempts to make a connection to another socket. The other socket is specified by a name, which is an address in the communications space of the socket. Each communications space interprets the name parameter in its own way.

If a SOCK_STREAM socket is set to non-blocking, then the socket allows repeated calls to SOConnect. These calls will return 0 after the socket is connected, or -1 if it is in the process of connecting. Datagram sockets may use SOConnect multiple times to change their association. Datagram sockets may also dissolve the association by connecting to an invalid address, such as a zero address.

NOTE:
Should a call to SOConnect return -1 and SOLastError return SO_ECONNREFUSED, the corresponding socket must be closed and recreated with a call to SOSocket before another connect attempt can be made. Repeated calls to SOConnect after receiving SO_ECONNREFUSED will cause SOLastError to return with SO_EINVAL.

Do Not Call From

Callbacks Do not call this function from any callback function.
Interrupt handler Do not call this function from any interrupt handler.
Exception handler Do not call this function from any exception handler.

See Also

SOAccept
SOBind
SOClose
SOListen
SOShutdown
SOSocket

Revision History

2012/10/09 Updated Errors section.
2012/08/16 Cleanup pass.
2011/07/11 Added Errors section.
2011/02/21 Initial version.


CONFIDENTIAL