rpc_$use_family Library Routine

Purpose

Creates a socket of a specified address family for a Remote Procedure Call (RPC) server.

Syntax

void rpc_$use_family ( family,  sockaddr slength,  status)

unsigned long family;
socket_$addr_t *sockaddr;
unsigned long *slength;
status_$t *status;

Description

The rpc_$use_family routine creates a socket for a server without specifying its port number. (The RPC runtime software assigns the port number.) Use this routine to create the server socket unless the server must listen on a particular well-known port. If the socket must listen on a specific well-known port, use the rpc_$use_family_wk routine to create the socket.

A server can listen on more than one socket. However, a server normally does not listen on more than one socket for each address family, regardless of the number of interfaces that it exports. Therefore, most servers should make this call once for each supported address family.

Note: This routine is used by servers only.

Parameters

Input

Item Description
family Specifies the address family of the socket to be created. This value corresponds to the communications protocol used to access the socket and determines how the socket address (sockaddr) parameter is expressed.

Output

Item Description
sockaddr Points to the socket address of the socket on which the server listens.
slength Points to the length, in bytes, of the socket address (sockaddr) parameter.
status Points to the completion status.

Return Values

The rpc_$use_family routine can fail if one or more of the following is true:

Value Description
rpc_$cant_create_sock The RPC runtime library is unable to create a socket.
rpc_$cant_bind_sock The RPC runtime library created a socket but is unable to bind it to a socket address.
rpc_$too_many_sockets The server is trying to use more than the maximum number of sockets allowed. The server has called the rpc_$use_family or rpc_$use_family_wk routines too many times.

Examples

To create the bank server's socket, enter:

rpc_$use_family(atoi(argv[1]), &saddr, &slen, &st);

The numeric value of the address family to be used is supplied as an argument to the program.