Syntax
#include <sys/types.h>
#include <sys/socket.h>
int Rbind(int socket_descriptor,
struct sockaddr *local_address,
int address_length)
Threadsafe: Yes
|
A program uses the Rbind() call to request that a SOCKS server
allow an inbound connection request across a firewall. This
call should only be used by applications that require inbound
connections across a firewall, and should only be used for
sockets with an address family of AF_INET.
Note that
for an Rbind() call to succeed, a previous connect() call must
have been issued for this thread,
and must have resulted in an outbound connection
over the same SOCKS server. The Rbind() inbound connection will
be from the same IP address addressed by the
original outbound connection. Caution must be exercised so that
outbound and inbound connections over the SOCKS server are paired.
In other words, all Rbind() inbound connections should
immediately follow the
outbound connection over the SOCKS server, and no intervening
non-SOCKS
connections relating to this thread
can be attempted before the Rbind() runs.
For an overview of using sockets
and how to interact with a SOCKS server,
see the topic about
AS/400 client SOCKS support in the
Sockets Programming book.
Parameters
- socket_descriptor
- (Input) The descriptor of the socket that is to be
bound.
- local_address
- (Input) A pointer to a buffer of type struct sockaddr
that contains the
local address to which the socket is to be bound.
The structure sockaddr is defined in <sys/socket.h>.
struct sockaddr {
u_short sa_family;
char sa_data[14];
};
The sa_family field identifies the
address family to which the address belongs,
and sa_data is the address whose format is
dependent on the address family.
- address_length
- (Input) The length of the local_address.
Return Value
Rbind() returns an integer. Possible values are:
- -1 (unsuccessful)
- 0 (successful)
Error Conditions
When an Rbind() fails, errno can be set to one of the following:
- [EADDRNOTAVAIL]
- Address not available.
This error code indicates one of the following:
- The SOCKS server specified is not reachable.
- The SOCKS server has denied the requested
inbound connection.
- The Socket can no longer be used for an inbound connection.
- [EAFNOSUPPORT]
- The type of socket is not supported in this protocol family.
The address family
specified in the address structure pointed to by
the local_address parameter
cannot be used with the socket pointed to by the
socket_descriptor parameter.
- [EBADF]
- Descriptor not valid.
- [EFAULT]
- Bad address.
The system detected an address that
was not valid while attempting to access the local_address parameter.
- [EINVAL]
- Parameter not valid.
This error code indicates one of the following:
- The address_length parameter
specifies a length that is negative or is
not valid for the address family.
- The socket referenced by socket_descriptor is
not a socket of type SOCK_RAW and is already bound to an address.
- The local address pointed to by the local_address parameter
specified an address that was not valid.
- [EIO]
- Input/output error.
- [ENOBUFS]
- There is not enough buffer space for the requested operation.
- [ENOTSOCK]
- The specified descriptor does not reference a socket.
- [EUNATCH]
- The protocol required to support the specified address family is
not available at this time.
- [EUNKNOWN]
- Unknown system state.
Error Messages
- CPE3418 E
- Possible APAR condition or hardware failure.
- CPF9872 E
- Program or service program &1
in library &2 ended. Reason code &3.
- CPFA081 E
- Unable to set return value or error code.
Usage Notes
-
If this call is issued for sockets with an
address family other than AF_INET, or
if the thread has not performed an outbound
connection through a SOCKS server, then
a
bind() call will be run instead.
In this case
the documented errno and usage notes for bind()
apply.
-
The local IP address and port number specified
for sockets with an address family of AF_INET
are ignored if Rbind() results in an inbound
connection over a SOCKS server.
In this scenario the socket is logically bound
to the SOCKS server IP address coupled with a port selected via
SOCKS server.
If a bind() is performed, then the socket
is bound to the local IP address and port number
specified.
-
The Rbind() function
may be explicitly used, or optionally you can
compile your application with the __Rbind macro defined when
you call the compiler. For example, if you are compiling with
a Create C Module
(CRTCMOD) CL command, specify __Rbind for the DEFINE
keyword to cause the __Rbind macro to be defined before the
compilation starts. Now all bind() calls in the program will become
Rbind().
See <sys/socket.h> for a definition of the
__Rbind macro.
Related Information