FreeBSD Manual Pages
SOCKS(3) socks SOCKS(3) NAME socks - Socks 5 proxy client API SYNOPSIS #include <socks.h> int rc=Rconnect(fd, addr, addrlen); int rc=Rbind(fd, addr, addrlen); cc {-o binary} [argument...] {-lsocks} DESCRIPTION This is the Courier Socks 5 client proxy library. It is used by the Courier mail server, starting with version 0.46, to send outgoing E-mail through a Socks 5 proxy server. This is a generic proxy API. This library may be used with other applications to establish network connections using a Socks 5 proxy. Explicit usage There are several ways to use this API library. The preferred way is to in- clude the header file socks.h which declares the Socks-aware equivalents of the socket API functions: Rconnect is the Socks-aware version of con- nect(2), Rbind is the Socks-aware version of bind(2), and so on. Use the Socks-aware functions just like their regular counterparts. They will transparently use a Socks 5 proxy to establish and use the network connec- tions, as specified by the socksrc(5)[1] configuration file. See "CAPABILITIES", below, for differences in behavior between the regular network functions and their Socks-aware counterparts. Finally, link the application against the socks library, by adding -lsocks to the link command. Note Some platforms do not provide the socket functions in the standard C library. Applications that use socket functions normally have to ex- plicitly link with a separate library, such as -lsocket or -lnsl_s. Try to avoid linking with a separate socket library when using -lsocks. In most cases, linking with those separate libraries is not required any more. Continue to link with them only if it is still necessary to do so (try not to link with them, and see what happens). socks.h declares the following functions: Raccept Rbind Rclose Rconnect Rdup Rdup2 Rfclose Rgetpeername Rgetsockname Rgetsockopt Rlisten Rpoll Rread Rreadv Rrecv Rrecvfrom Rrecvmsg Rselect Rsend Rsendmsg Rsendto Rwrite Rwritev Note Only some of the above functions are really defined. The rest are mapped, using "#define"-s, to their "R"-less counterparts, but applica- tions should use the "R" functions in order to remain upward-compatible with future versions of this library. CAPABILITIES This Socks 5 proxy library supports the following functionality: 1. Establishing blocking or non-blocking SOCK_STREAM client connec- tions. 2. Accepting a single incoming SOCK_STREAM connection using Rbind, Rlisten, and Raccept. Note This Socks 5 proxy library does not support using Rbind to bind a socket to a specific port, then using Rconnect to establish an out- going connection originating from the specific port. The Rbind function can only be used for a listening socket, and is expected to be followed by Rlisten. This is a limitation of the Socks 5 protocol. Note Only one connection may be received by a bound, listening socket. After the first connection is established, that's it. The Socks 5 protocol no longer listens for more connections on the listening socket. This implementation of Rbind, Rlisten, and Raccept mimics the usual semantics of the non-proxying versions of these func- tions. As far as the application is concerned, only one incoming connection will ever be received on the listening socket Continuing to listen on the socket will never produce any more incoming con- nections. This is a limitation of the Socks 5 protocol. Implicit usage #define SOCKS_REMAP #include <socks.h> cc {-o binary} [argument...] {-lsocks} The alternative way to use this Socks 5 API is to define SOCKS_REMAP before including socks.h, and then using the usual socket functions, like connect, bind, and the rest. It's rather obvious that SOCKS_REMAP runs a bunch of C preprocessor defini- tions, such as: #define connect Rconnect #define bind Rbind /* More of the same */ This is going to work because this Socks 5 API library automatically ig- nores file descriptors that are not TCP sockets. A PF_UNIX file descriptor passed to Rbind is automatically shunted off to the real bind function, and the application will not know any better. Other Socks 5 API functions work in the same way. The preferred, explicit usage of the "R" functions permits fine-grained control over proxying. The application has complete control of which net- work connections will use a Socks 5 proxy server (by using the "R" func- tions with that file descriptor), and which network connections won't (by using normal network socket functions). Implicit usage, via SOCKS_REMAP, loses the control over this process. All TCP network connections will use Socks 5 proxies, if so indicated by the socksrc(5)[1] configuration file. Library wrapper cc {-o binary} [argument...] {-lsockswrap} The third alternative mechanism of using this Socks 5 API involves no changes to the source code. The only change is to the link command. The fi- nal application executable is linked to the sockswrap library instead of the socks library. This mechanism may not be available on all platforms, or may not work reli- ably with all applications. The sockswrap library provides fake definitions of the normal socket functions, just as connect, bind, and all the others. These function calls are intercepted, and redirected to their "R" equiva- lents. Note Some platforms require explicit linkage with the socks library in addi- tion to the sockwrap library: cc {-o binary} [argument...] {-lsockswrap} {-lsocks} In any case, if possible, do not link against any extra libraries, even if your platform otherwise requires linking against extra libraries, such as -lsocket or -lnsl_s. This mechanism is equivalent to running the socksify(1)[2] wrapper with an already-linked executable. This approach may succeed in adding Socks 5 proxying abilities to an existing object code library, or module, if its source code is not available. SEE ALSO socksify(1)[2], socksrc(5)[1]. AUTHORS Double Precision, Inc. NOTES 1. socksrc(5) [set $man.base.url.for.relative.links]/socksrc.html 2. socksify(1) [set $man.base.url.for.relative.links]/socksify.html Courier Mail Server 05/22/2022 SOCKS(3)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | AUTHORS | NOTES
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=socks&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>