paggctl  - controls and provides status for Process Aggre­
       gation (PAGG) modules


SYNOPSIS

       int paggctl (char *module_name, int request, void *data);


DESCRIPTION

       The ppaaggggccttll system call is used as the system call  inter­
       face  for  Process Aggregation (PAGG) modules.  For a PAGG
       module to support the paggctl interface, it must have pro­
       vided  a reference to a processing function that is imple­
       mented in the module to handle paggctl calls  the  request
       the module.  It is not required that a PAGG module support
       the paggctl system call.

       The ppaaggggccttll system call allows processes to obtain  infor­
       mation  from the PAGG modules, such as status information.
       In addition, this interface provides  processes  with  the
       ability to provide information to the PAGG module.

       The  use of the paggctl system call requires three parame­
       ters.  The first, module_name, is a string  that  provides
       the  name  of  the module that should service the request.
       The second argument, request, is a code that indicates  to
       the  module  what  the operation the caller is requesting.
       The final argument, data, is a  pointer  to  a  strucuture
       used  to transfer data between the process and the module.
       The module servicing the request will provide  the  struc­
       ture definitions for the data argument.

       Each  PAGG  module  that implements a service function for
       ppaaggggccttll should provide a manual page that  provides  addi­
       itonal  details.   The Linux Job module is an example of a
       PAGG module.  The Job module manual page, job_paggctl(3c),
       provides  additional  details  about the requests that the
       service function provided by the Job module may handle and
       any required header files.

       The  PAGG system handles requests for information concern­
       ing PAGG modules that are currently registered.   To  per­
       form  PAGG  module  queries,  the  first argument, /f2mod­
       ule_name/f1 should be set to the PPAAGGGG_MMOODD macro (found  in
       the  paggctl.h  include file).  The second and third argu­
       ments should be set as follows:

       MMOODD_GGEETTCCNNTT
              Get a count for the number  of  PAGG  modules  cur­
              rently  registered.   The data structure referenced
              by data is a pointer to an int.  The count of  mod­
              ules  will  be  stored  in the memory referenced by
              this pointer.

              Get the list of modules currently registered.   The
              data  structure  referenced by data is a pointer to
              the following struct:

                   typedef struct mod_getlst_s {
                        int   r_val;
                        pagg_namestr_t *list;
                   } mod_getlst_t;

              The list of PAGG module service names  is  returned
              in the list of character arrays pointed to the list
              member.  The caller is responsible  for  allocating
              and  freeing  the  memory for the list.  The caller
              specifies the number of elements in the array using
              the  r_val  member.   Upon return, the r_val member
              will contain the number of module names  that  were
              inserted into the list.  The number of module names
              returned is limited to the numer of elemets  speci­
              fied by what the caller specifies in the r_val mem­
              ber.  An example of allocating a list of  that  can
              contain up to five module names is as follows:

                   mod_getlst_t getlst;
                   getlst.r_val = 5;
                   getlst.list = (pagg_namestr_t *)malloc(
                                  (sizeof(pagg_namestr_t)*getlst.r_val);

       MMOODD_GGEETTCCHHKK
              Determine if a specific PAGG module is  registered.
              The  data structure referenced by data is a pointer
              to the following struct:

                   typedef struct mod_getchk_s {
                        int   r_val;
                        pagg_namestr_t name;
                   } mod_getlst_t;

              The caller specifies the PAGG module  service  name
              via  the  name  member  of the struct.  If the PAGG
              module is not registered, the value 0  is  returned
              via  the  r_val  member of the struct.  If the PAGG
              module  is  registered,  then  a  value  of  1   is
              returned.


ERRORS

       Under the following conditions, the aaccccttccttll function fails
       and sets errno to:

       [ENOSYS]       The paggctl system call is not implemented.

       [ENXIO]        The  module/driver  does not provide a pag­
                      gctl service function.

                      found.  That driver has not registered as a
                      pagg service provider.

       Additional errno codes are listed on the manual pages pro­
       vided by the PAGG modules


DIAGNOSTICS

       Upon  successful completion, paggctl returns a value of 0.
       Otherwise, a value of -1 is returned and errno is  set  to
       indicate the error.


Man(1) output converted with man2html