socks5tcp_bind Subroutine

Communications Technical Reference, Volume 2

socks5tcp_bind Subroutine

Purpose

Connect to a SOCKSv5 server and request a listening socket for incoming remote connections.

Library

Standard C Library (libc.a)

Syntax

#include <sys/types.h>
#include <sys/socket.h>
#include <socks5_api.h>

int socks5tcp_bind(Socket, Dst, DstLen, Svr, SvrLen)
Int Socket;
struct sockaddr *Dst;
size_t DstLen;
struct sockaddr *Svr;
size_t SrvLen;

Description

The socks5tcp_bind subroutine requests a listening socket on the SOCKSv5 server specified in Svr, in preparation for an incoming connection from a remote destination, specified by Dst. Upon success, Svr will be overwritten with the actual address of the newly bound listening socket, and Socket may be used in a subsequent call to socks5tcp_accept.

Socket must be an open socket descriptor of type SOCK_STREAM.

Parameters

Socket	Specifies the unique name of the socket.
Dst	Specifies the address of the SOCKSv5 server to use to request the relayed connection; on success, this space will be overwritten with the actual bound address on the server.
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; on success, this space will be overwritten with the actual bound address on the server.
SvrLength	Specifies the length of the address structure in Svr.

Return Values

Upon successful completion, the socks5tcp_bind subroutine returns a value of 0, and modifies Svr to reflect the actual address of the newly bound listener socket.

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

Returns a value of -1 to the calling program.
Moves an error code, indicating the generic system error, into the errno global variable.
Moves an error code, indicating the specific SOCKSv5 error, into the socks5_errno global variable.

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

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

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:

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_EADDRINUSE	Requested bind address is already in use (at the SOCKSv5 server).
S5_ENOERV	No server found.

Examples

The following program fragment illustrates the use of the socks5tcp_bind subroutine by a client to request a listening socket from a server.

struct sockaddr_in svr;
struct sockaddr_in dst;
.
.
.
socks5tcp_bind(s, (struct sockaddr *)&dst, sizeof(dst), (structsockaddr *)&svr, sizeof(svr));

Implementation Specifics

The socks5tcp_bind subroutine is part of Base Operating System (BOS) Runtime.

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.

Related Information

The socks5tcp_accept subroutine, socks5tcp_connect subroutine, socks5_getserv subroutine, /etc/socks5c.conf file, accept subroutine, bind subroutine, getsockname subroutine, send subroutine, socket subroutine.

Sockets Overview, and Understanding Socket Connections in AIX Version 4.3 Communications Programming Concepts.