Rbind()--Set Remote Address for Socket

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

 int Rbind(int socket_descriptor,
         struct sockaddr *local_address,
         int address_length)

  #define _XOPEN_SOURCE 520
  #include <sys/socket.h>

 int Rbind(int socket_descriptor,
         const struct sockaddr *local_address,
         socklen_t address_length)

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 IBM^® i client SOCKS support in the Socket programming topic collection.

There are two versions of the API, as shown above. The base IBM i API uses BSD 4.3 structures and syntax. The other uses syntax and structures compatible with the UNIX 98 programming interface specifications. You can select the UNIX 98 compatible interface with the _XOPEN_SOURCE macro.

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>.

The BSD 4.3 structure is:

      struct sockaddr {
         u_short sa_family;
         char    sa_data[14];
      };

The BSD 4.4/UNIX 98 compatible structure is:

      typedef uchar   sa_family_t;

      struct sockaddr {
         uint8_t     sa_len;
         sa_family_t sa_family;
         char        sa_data[14];
      };

The BSD 4.4 sa_len field is the length of the address. 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.

Authorities

• When the address type of the socket identified by the socket_descriptor is AF_INET, the thread must have retrieve, insert, delete, and update authority to the port specified by the local_address field. When the thread does not have this level of authority, an errno of EACCES is returned.
  
  
• When the address type of the socket identified by the socket_descriptor is AF_INET and is running IP over SNA, the thread must have retrieve, insert, delete, and update authority to the APPC device. When the thread does not have this level of authority, an errno of EACCES is returned.

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:

Error Messages

Usage Notes

1. 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.
   
   
2. 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.
   
   
3. 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.
   
   
4. When you develop in C-based languages and an application is compiled with the _XOPEN_SOURCE macro defined to the value 520 or greater, the Rbind() API is mapped to qso_Rbind98().

Related Information

• _XOPEN_SOURCE--Using _XOPEN_SOURCE for the UNIX 98 compatible interface
  
  
• accept()--Wait for Connection Request and Make Connection
  
  
• bind()--Set Local Address for Socket
  
  
• connect()--Establish Connection or Destination Address
  
  
• getsockname()--Retrieve Local Address of Socket

[ Back to top | UNIX-Type APIs | APIs by category ]