Index for Section 3

Alphabetical listing for C

Bottom of page

clusvc_getcommport(3)
NAME
  clusvc_getcommport, clusvc_getresvcommport - Bind to a common port

LIBRARY
  Cluster Library (libclu.a and libclu.so)

SYNOPSIS
  #include <netinet/in.h>

  int clusvc_getcommport (
	  int sockfd ,
	  uint prog ,
	  uint proto ,
	  struct sockaddr_in *addr );

  int clusvc_getresvcommport (
	  int sockfd ,
	  uint prog ,
	  uint proto ,
	  struct sockaddr_in *addr );

PARAMETERS
  sockfd    A socket descriptor. If sockfd is set to RPC_ANYSOCK, the
	    function creates an AF_INET socket with a type and protocol
	    derived from the value of proto.

  prog	    RPC program number.

  proto	    Protocol: IPPROTO_UDP or IPPROTO_TCP.

  addr	    Pointer to a caller-allocated sockaddr_in structure.

DESCRIPTION
  Programs that use RPC can call the clusvc_getcommport() and
  clusvc_getresvcommport() functions to bind to a common port within a
  cluster. Use clusvc_getresvcommport() when binding to a reserved
  (privileged) port, a port number in the range 0-1023.

  Use the clusvc_getcommport() and clusvc_getresvcommport() functions in the
  following circumstances:

    ·  The service does not use a well-known port (services that use well-
       known ports can have in_multi entries in /etc/clua_services).

    ·  Multiple instances of the service will run in a cluster.

    ·  Requests for the service will be directed to a cluster alias, which
       will provide load balancing among the instances of the service.

  These functions make it possible to run an RPC application on multiple
  cluster members, all accessible via cluster alias.  In addition to ensuring
  that each instance of an RPC application uses the same common port, the
  functions also inform the portmapper that the application is a multi-
  instance, alias application. If you do not use one of these functions to
  bind to the port, you can still run multiple instances of the application,
  but only one instance will receive requests directed to a cluster alias.

  The clusvc_getcommport() and clusvc_getresvcommport() functions attempt to
  take an exclusive DLM lock on the resource defined by the program number
  and the protocol.

    ·  If the lock is granted, this is the first instance of the server in
       the cluster. The function then binds to a port, calls getsockname() to
       get the name, and calls clua_registerservice() to register the service
       as a multi-instance service, CLUASRV_MULTI. (See
       clua_registerservice(3) for a description of multi-instance services.)

    ·  If the lock is not granted, an instance of the server is already
       running in the cluster. In this case, the function queries the DLM
       lock to obtain the port number and attempts to bind to the port. If
       the bind fails because the port is in use, the function writes a
       syslog message indicating that it cannot bind to the port, sleeps, and
       tries again. When the port becomes available, the function binds to
       the port and registers the service as a multi-instance service.

EXAMPLES
  The following code fragment shows a typical calling sequence:

       #include <netinet/in.h>
       #include <rpc.h>
       #include <syslog.h>

	    int s;
	    int cluster = 0;
	    uint prog = 100999;	 /* replace with real program number */
	    struct sockaddr_in addr;
	    int len = sizeof(struct sockaddr_in);

	    cluster = clu_is_member();

	    if ((s = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP)) < 0) {
		     syslog(LOG_ERR, "socket: %m");
		     exit(1);
	    }
	    bzero(&addr, sizeof(addr));
	    addr.sin_family = AF_INET;
	    addr.sin_addr.s_addr = INADDR_ANY;

	    if (cluster) {
	       if (clusvc_getcommport(s, prog, IPPROTO_UDP, &addr) < 0) {
		   syslog(LOG_ERR, "clusvc_getcommport: %m");
		   exit(1);
	       }
	    } else {
	       addr.sin_port = 0;
	       if (bind(s, &addr, sizeof(addr)) < 0) {
		   syslog(LOG_ERR, "bind: %m");
		   exit(1);
	       }
	       if (getsockname(s, &addr, &len) != 0) {
		   syslog(LOG_ERR, "getsockname: %m");
		   (void) close(s);
		   exit(1);
	       }
	    }

  The following code fragment shows another approach:

	     s = RPC_ANYSOCK;
	     pmap_unset(prog, version);
	     if (cluster) {
		 addr.sin_family = AF_INET;
		 addr.sin_addr.s_addr = INADDR_ANY;
		 if (s = clusvc_getcommport(RPC_ANYSOCK, prog,
			 IPPROTO_UDP, &addr) < 0) {
		     syslog(LOG_ERR, "clusvc_getcommport: %m");
			  exit(1);
		 }
	     }
	     /* In the non-cluster case, svcudp_create creates the
		socket and binds the port.
	      */
	      if ((transp = svcudp_create(s)) == NULL) {
		   syslog(LOG_ERR, "couldn't create UDP transport");
		   exit(1);
	      }

RETURN VALUES
  The clusvc_getcommport() and clusvc_getresvcommport() functions return the
  socket descriptor on success, and -1 on error.

RELATED INFORMATION
  Functions:

  bind(2), clua_registerservice(3), rpc(3)

  Files:

  clua_services(4)

Index for Section 3

Alphabetical listing for C

Top of page