socks5tcp_connect Subroutine

Purpose

Connect to a SOCKSv5 server and request a connection to an external destination.

Library

Standard C Library (libc.a)

Syntax

#include <stdlib.h>
#include <netinet/in.h>
#include <sys/socket.h>
int socks5tcp_connect (Socket, Dst, DstLen, Svr, SvrLen)
int Socket;
struct sockaddr *Dst;
size_t DstLen;
struct sockaddr *Svr;
size_t SrvLen;

Description

The socks5tcp_connect subroutine requests a connection to Dst from the SOCKSv5 server specified in Svr. If successful, Dst and Svr will be overwritten with the actual addresses of the external connection and subsequent writes to and reads from Socket will be relayed through Svr.

Socket must be an open socket descriptor of type SOCK_STREAM; Dst and Svr may be either IPv4 or IPv6 addresses.

The socket applications can be compiled with COMPAT_43 defined. This will make the sockaddr structure BSD 4.3 compatible. For more details refer to socket.h.

Parameters

Item Description
Socket Specifies the unique name of the socket.
Dst Specifies the external address of the target socket to which the SOCKSv5 server will attempt to connect.
DstLength Specifies the length of the address structure in Dst.
Svr If non-NULL, specifies the address of the SOCKSv5 server to use to request the relayed connection.
SvrLength Specifies the length of the address structure in Svr.

Return Values

Upon successful completion, the socks5tcp_connect subroutine returns a value of 0, and modifies Dst and Svr to reflect the actual endpoints of the created external socket.

If the socks5tcp_connect subroutine is unsuccessful, the system handler performs the following functions:

Error Codes (placed in errno; inherited from underlying call to connect())

The socks5tcp_connect subroutine is unsuccessful if any of the following errors occurs:

Error Description
EBADF The Socket parameter is not valid.
ENOTSOCK The Socket parameter refers to a file, not a socket.
EADDRNOTAVAIL The specified address is not available from the local machine.
EAFNOSUPPORT The addresses in the specified address family cannot be used with this socket.
EISCONN The socket is already connected.
ETIMEDOUT The establishment of a connection timed out before a connection was made.
ECONNREFUSED The attempt to connect was rejected.
ENETUNREACH No route to the network or host is present.
EADDRINUSE The specified address is already in use.
EFAULT The Address parameter is not in a writable part of the user address space.
EINPROGRESS The socket is marked as nonblocking. The connection cannot be immediately completed. The application program can select the socket for writing during the connection process.
EINVAL One or more of the specified arguments is invalid.
ENETDOWN The specified physical network is down.
ENOSPC There is no space left on a device or system table.
ENOTCONN The socket could not be connected.

Error Codes (placed in socks5_errno; SOCKSv5-specific errors)

The socks5tcp_connect subroutine is unsuccessful if any of the following errors occurs:

Error Description
S5_ESRVFAIL General SOCKSv5 server failure.
S5_EPERM SOCKSv5 server ruleset rejection.
S5_ENETUNREACH SOCKSv5 server could not reach target network.
S5_EHOSTUNREACH SOCKSv5 server could not reach target host.
S5_ECONNREFUSED SOCKSv5 server connection request refused by target host.
S5_ETIMEDOUT SOCKSv5 server connection failure due to TTL expiry.
S5_EOPNOTSUPP Command not supported by SOCKSv5 server.
S5_EAFNOSUPPORT Address family not supported by SOCKSv5 server.
S5_ENOSERV No server found.

Examples

The following program fragment illustrates the use of the socks5tcp_connect subroutine by a client to request a connection from a server's socket.

struct sockaddr_in svr;
struct sockaddr_in6 dst;
.
.
.
socks5tcp_connect(s,(struct sockaddr*)&dst, sizeof(dst), (struct sockaddr *)&svr, sizeof(svr));