Controls API Functions
int pr_ctrls_register(module *module, const char *action, int (*ctrls_cb)(pr_ctrls_t *, int, char **)); int pr_ctrls_unregister(module *module, const char *action); int pr_ctrls_add_arg(pr_ctrls_t *ctrl, char *ctrls_arg); int pr_ctrls_add_response(pr_ctrls_t *ctrl, char *fmt, ...); int pr_ctrls_connect(void); int pr_ctrls_copy_args(pr_ctrls_t *src_ctrl, pr_ctrls_t *dest_ctrl); int pr_ctrls_copy_resps(pr_ctrls_t *src_ctrl, pr_ctrls_t *dest_ctrl); int pr_ctrls_flush_response(pr_ctrls_t *ctrl); int pr_ctrls_parse_msg(pool *msg_pool, char *msg, unsigned int *msgargc, char ***msgargv); int pr_ctrls_recv_request(pr_ctrls_cl_t *cl); int pr_ctrls_recv_response(pool *resp_pool, int ctrls_sockfd, int *status, char ***respargv); int pr_ctrls_send_msg(int sockfd, int msgstatus, unsigned int msgargc, char **msgargv); void pr_block_ctrls(void); void pr_unblock_ctrls(void); int pr_check_ctrls(void); int pr_run_ctrls(module *module, const char *action); void pr_clear_ctrls(); void pr_init_ctrls();
pr_ctrls_register() function will be used by modules to
register custom control handlers with the Controls layer. The registration
consists of a pointer to the registering module module, the
action by which clients can request this control to be run, and a
callback function pointer to the control's handler. The control handler must
return an integer status value (preferably conforming to the norm of
0 indicating success,
-1 indicating an error), and
must take three arguments: a pointer to the registered
object, and integer number of request strings, and an array of the indicated
number of request strings (similar to the
argc, argv of most
main() function). This function will return the ID of
pr_ctrls_t control object if successful, or
-1 if an error occurred during registration.
pr_ctrls_unregister() function unregisters any registered
control handlers that match the given module and action
arguments. module may be
ANY_MODULE, meaning that
control handlers from all modules should be searched. action may not
NULL, else this function will return
errno set to
EINVAL. If no matching control
handlers were found, a
-1 will be returned with
EPERM. A return value of
0 means the
requested controls were successfully unregistered from the Controls layer.
pr_ctrls_add_arg() function is a utility function used to
add the given ctrls_arg string to the control object's handler argument
array. It will return
0 on success,
-1 on failure.
Most module code should not need to use this function.
pr_ctrls_add_response() function is used by control handlers
to add a text response string to the object that will eventually be returned
to the requesting client. This function will return
0 if the
response was succesfully added, or
-1 if there was a problem.
pr_ctrls_connect() function is to be used by client programs
that wish to make control requests; this includes
any core or module routines wishing to submit programmatic requests. It
connects to the well-defined Unix domain socket and returns the opened
socket descriptor for use by the client, or
-1 if there was an
errno set appropriately.
pr_ctrls_copy_args() function is a utility function used
to duplicate src_ctrl's handler argument array and place that duplicate
in dest_ctrl. Control handlers should not need to use this function.
pr_ctrls_copy_resps() function is a utility function used
to make a duplicate of src_ctrl's handler response array for
dest_ctrl. Control handlers should not need to use this function.
pr_ctrls_flush_response() function flushes any responses
of the given ctrl out to the client. Note that this function
should be used rarely, and only when the control handler will not
be returning normally (as when exiting the process). If ctrl is
NULL, it will return
that the function was unable to flush the response to the client. A value of
0 is returned if the flush was successful.
pr_ctrls_parse_msg() function parses the given msg
into the provided msgargc, msgargv pointers, splitting the
msg on whitespace (honoring quoting and escapes). The msgargv
array of strings is allocated from msg_pool. This is provided
as a utility function to modules, so that they may prepare a single string
for use by
pr_ctrls_send_msg(). A value of
returned if successful,
-1 if an error occurred.
pr_ctrls_recv_request() function reads in a client's control
request. It will return
errno set to
EOF if there was nothing to be read from the client socket;
errno may have other values as appropriate for
read(2) errors. A value of
0 will be returned if
the request was successfully read.
pr_ctrls_recv_response() function reads the control handler
response from the given socket ctrls_sockfd, allocating memory for
the strings from resp_pool. The return value of the control handler
will be stored in status, and the array of response strings in
respargv, if not
NULL. respargv may indeed be
NULL, as when the client does not really care about the
responses and simply wants the status or to know that the response was
successfully received. This function returns the number of responses
errno set properly if there
was an error.
pr_ctrls_send_msg() function is used to send both requests
and responses. It sends msgargc number of strings, found in
msgargv, to the socket sockfd. For requests, msgstatus
is largely ignored; for responses, it contains the return value of the control
handlers that handled the request.
pr_block_ctrls() function blocks control handlers from
being run. This is usually done when the control handler list is being
modified, and should not be used by modules.
pr_unblock_ctrls() function restores the control handler
list to useable status, signalling that the state of the list is once more
stable. This should not be used by modules.
pr_check_ctrls() function is used to do a sanity check of
the register control handlers. Some control handlers allow of only a single
instance to handle a requested action, some allow multiple handlers for a
requested action. Note: not currently implemented.
pr_run_ctrls() function iterates through the list of
pr_ctrls_t objects and invokes the callback
handler functions of any that match the given module and action
0 if successful, or
-1 if there
was a problem (as when controls are blocked). Modules and control handlers
should not need to make use of this function.
pr_clear_ctrls() function removes the control objects from
the list that were registered in response to client requests, clearing the
list for new client requests.
pr_init_ctrls() function initializes the Controls layer.
Author: $Author: castaglia $
Last Updated: $Date: 2002/07/19 21:56:20 $
© Copyright 2000-2002 TJ Saunders
All Rights Reserved