netmgt_init_rpc_agent manual page
Table of Contents

NAME

netmgt_init_rpc_agent - initialize an RPC-based agent

SYNOPSIS

bool_t
netmgt_init_rpc_agent(name, serial program, version, proto, timeout, reserved, flags, verify, dispatch, reap, shutdown)
char
*name; u_int serial; u_long program; u_long version; u_long proto; struct timeval timeout; u_int reserved; u_int flags; bool_t (* verify)();
void
(* dispatch)();
void
(* reap)();
void
(* shutdown)();

DESCRIPTION

netmgt_init_rpc_agent initializes the Agent Services library and registers the agent with the RPC system to receive requests via RPC from manager processes.

INPUT ARGUMENTS

name agent name as it appears in the rpc database.

serial
agent serial number, beginning with 1 and increasing for each release of the agent. This is not the RPC version number. It is a method for (among other things) ensuring the agent and its schema file are in sync. In the current release the snm(1) and snm_cmd(1) managers don't look at this information but future releases will. Therefore, you should include it.

program
RPC program number.

version
RPC version number. For the current release, use NETMGT_VERS.

proto
transport service. IPROTO_UDP is the only option available in the current release.

timeout
maximum time to wait for a reply from the rendezvous when sending a data or event report.

reserved
currently unused. For compatibility with future releases, set this to zero.

flags
startup options. Two options are available to the agent: NETMGT_DONT_FORK and NETMGT_DONT_EXIT. If NETMGT_DONT_FORK is set, the Agent Services library won't fork(2) an agent subprocess to handle the request. Instead, the agent dispatch routine is run in the context of the original process. NETMGT_DONT_FORK is useful for debugging agents (stepping through the dispatch function, setting breakpoints, and the like) with debuggers that don't handle child processes well, such as dbx(1). This option should not be used in production code. Two notes about this option: First, the manager request will probably time out because it won't get a confirmation message. Second, the activity daemon won't know about any requests sent to the agent. If NETMGT_DONT_EXIT is set, an agent will not exit when it has no child processes handling requests. Similarly, a command such as snm_cmd -A -a ping will not cause the ping parent process to exit, although any children will be terminated.
Discretionary use of this option is advised. Usually only special agents like the event dispatcher and activity daemon need to use it.

verify
function called to verify the request parameters. When a request message is received, the verify function is called before the agent dispatch function is called. If any of the request parameters are invalid, the ver_ify function should send an error with netmgt_send_error(3n) indicating the problem, and then return FALSE. If the verification succeeds, the verify function should return TRUE.
If the verify function returns FALSE, the dispatch function is not called.

dispatch
function called after a request message has been verified as okay for processing. It is called in the context of the child process, unless NETMGT_DONT_FORK has been set in the flags argument. It should return rather than exit(2) when finished with a request, to allow the Agent Services library to regain control and do final cleanup.

reap optional function used for agent - specific cleanup, called before an agent child process exits.

shutdown
optional function used for agent - specific cleanup, called when an agent parent process exits. If this value is NULL, the Agent Services library will call netmgt_shutdown_agent(3n). If the value is not null, the shutdown function should call netmgt_shutdown_agent(3n) as the last thing it does.

RETURN VALUE

TRUE if successful, otherwise FALSE.

DIAGNOSTICS

If FALSE is returned, global variable netmgt_error indicates the error. The caller can get the reason for the error with netmgt_fetch_error(3n).

SEE ALSO

snm_cmd(1),
netmgt_fetch_error(3n), netmgt_shutdown_agent(3n) Site/SunNet/Domain Manager Application and Agent Development Guide

NOTES

The Agent Services library uses the following signals in the parent: SIGINT, SIGQUIT, SIGTERM, and SIGCHLD. If the parent wishes to have control passed to its own functions when one of these signals occurs, it should specify the functions in the shutdown (for SIGINT, SIGQUIT, and SIGTERM) and reap (for SIGCHLD) parameters. One signal is used in the child process: SIGUSR1. Agents should avoid using this signal.


Table of Contents