Technical Reference: Communications, Volume 2

socks5_getserv Subroutine

Purpose

Return the address of the SOCKSv5 server (if any) to use when connecting to a given destination.

Library

Standard C Library (libc.a)

Syntax

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

struct sockaddr * socks5_getserv (Dst, DstLen)
struct sockaddr *Dst;
size_t DstLen;

Description

The socks5_getserv subroutine determines which (if any) SOCKSv5 server should be used as an intermediary when connecting to the address specified in Dst.

The address returned in Dst may be IPv4 or IPv6 or some other family. The user should check the address family before using the returned data.

Parameters

Dst	Specifies the external address of the target socket to use as a key for looking up the appropriate SOCKSv5 server.
DstLength	Specifies the length of the address structure in Dst.

Return Values

Upon successful lookup, the socks_getserv subroutine returns a reference to a sockaddr struct.
If the socks5tcp_connect subroutine is unsuccessful in finding a server, for any reason, a value of NULL is returned. If an error occurred, an error code, indicating the generic system error, is moved into the errno global variable.

Error Codes (placed in errno)

The socks5_getserv subroutine is unsuccessful if no server is indicated or if any of the following errors occurs:

EAFNOSUPPORT	The addresses in the specified address family cannot be used with this socket.
EFAULT	The Dst parameter is not in a writable part of the user address space.
EINVAL	One or more of the specified arguments is invalid.
ENOMEM	The Dst parameter is not large enough to hold the server address.

Examples

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

struct sockaddr_in6 dst;
 
struct sockaddr *srv;
.
.
.
srv = socks5_getserv((struct sockaddr*)&dst, sizeof(dst));
 
if (srv !=NULL)  {
 
     /* Success: srv should be used as the socks5 server */
 
} else {
     /* Failure: no server could be returned.  check errno */
     
}

Implementation Specifics

The socks5_getserv 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_connect subroutine, socks5tcp_bind subroutine, socks5tcp_accept subroutine, socks5udp_associate subroutine, socks5udp_sendto subroutine, /etc/socks5c.conf file, connect subroutine.

Sockets Overview and Understanding Socket Connections in AIX 5L Version 5.1 Communications Programming Concepts.

SOCKS5C_CONFIG Environment Variable in AIX 5L Version 5.1 Files Reference.