job_paggctl,  paggctl  - control and obtain status for the
       Job PAGG module


SYNOPSIS

       #include <paggctl.h>

       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.  The ppaaggggccttll
       system call allows processes to obtain status  information
       about jobs and to create new jobs.  When the Job module is
       to be used to service a request, the paggctl.h header file
       should be included to obtain the proper request macros and
       data structures.

       The use of the paggctl system call requires three  parame­
       ters.   The  first, module_name, is a string that provides
       the name module that should service the  request.  In  the
       case  of  a request for the Job module, the JOB_NAME macro
       is provided to use for this argument.

       The second argument, request, is a code that indicates  to
       the  Job  module  what operation the caller is requesting.
       Macros that specify the requests are provided in the  pag­
       gctl.h  include  file.   The  macro  for  job  requests is
       PPAAGGGG_JJOOBB.

       The final arugment, data, is a void  pointer  that  refer­
       ences  the structure used to pass data between the calling
       process and the Job  module's  ppaaggggccttll  service  function.
       The  data  structure types passed via the data pointer are
       defined in the paggctl.h include file.

       The Job module handles the following  request  macros  (as
       defined in paggctl.h):

       JJOOBB_CCRREEAATTEE
              Create  a new job.  The calling process is attached
              to   the   new   job.    This   request    requires
              CAP_SYS_RESOURCE  capability.   (See  the  capabil­
              ity(4)  and  capabilities(4)  man  pages  for  more
              information  on  the  capability mechanism for con­
              trolling process privileges.)  The  data  structure
              pointed to by data is defined as follows:

                   typedef struct job_create_s {
                        uint64_t   r_jid;
                        uint64_t   jid;
                        uid_t      user;
                        int        options;
                   } job_create_t;

              the new job.  If the  operation  to  create  a  job
              failed,  then r_jid will be set to 0.  The jid mem­
              ber allows the caller to specify a jid value to use
              when  creating the job.  If the caller want the Job
              module to generate the job ID, then set jid  to  0.
              The user member is used to supply the user ID (uid)
              value for the user that  will  own  the  job.   The
              options member is for future use.

       JJOOBB_GGEETTJJIIDD
              Get the job ID (jid) for the specified process pid.
              The data structure pointed to by data is defined as
              follows:

                   typedef struct job_getjid_s {
                        uint64_t  r_jid;
                        pid_t          pid;
                   } job_getjid_t;

              The  r_jid member is the job ID (jid) value for the
              job to which process is attached.  The r_jid  value
              will be equal to 0 if the attempt to get the job ID
              failed, and errno  will  be  set  to  indicate  the
              error.   The pid member is used to specify the pro­
              cess for which the caller is requesting the jid.

       JJOOBB_WWAAIITTJJIIDD
              Wait for the job, specified by the supplied jid, to
              complete.  The data structure pointed to by data is
              defined as follows:

                   typedef struct job_waitjid_s {
                        uint64_t  r_jid;
                        uint64_t  jid;
                        int       stat;
                        int       options;
                   } job_waitjid_t;

              The r_jid data member is the jid value for the  job
              that  was  waited  upon.   If  the  wait  operation
              failed, then r_jid will be set equal to 0 and errno
              will  be  set to indicate the error. The jid member
              is the jid value that identifies the  job  to  wait
              upon.   The stat member is the completion status of
              the job.  The completion status  is  determined  by
              the  exit  status  for  the last process in the job
              that exits. The status can be evaluated  using  the
              same  macros  as  described  in  the wait(2) manual
              page.  The options data member is for future use.

       JJOOBB_KKIILLLLJJIIDD
              Send a signal to all  processes  in  the  specified
              job.  The data argument should point to a structure


                   typedef struct job_killjid_s {
                        int       r_val;
                        uint64_t  jid;
                        int       sig;
                   } job_killjid_t;

              The r_val member is the return value for the opera­
              tion.   On success, r_val=0 and on failure r_val<0.
              The jid member specifies the  job  that  should  be
              sent  the  signal.   the  sig member specifies what
              signal should be sent.

       JJOOBB_GGEETTJJIIDDCCNNTT
              Get the number of jobs  currently  running  on  the
              system.  The data argument should point to a struc­
              ture of type job_jidcnt_t defined as follows:

                   typedef struct job_jidcnt_s {
                        int       r_val;
                   } job_jidcnt_t;

              The number of jobs on the system is returned in the
              r_val  member.   This value will be greater than or
              equal to 0.

       JJOOBB_GGEETTJJIIDDLLSSTT
              Get the list of job jids for job currently  running
              on  the system. The data argument should point to a
              structure of type job_jidlst_t defined as follows:

                   typedef struct job_jidlst_s {
                        int       r_val;
                        uint64_t  *jid;
                   } job_jidlst_t;

              The list of job jid values is returned in the array
              pointed  to  by  the  jid  member.   The  caller is
              responsible for allocating and freeing  the  memory
              for the array pointed to by jid.  The caller speci­
              fies the number of elements in the array using  the
              r_val  member.   Upon return, the r_val member will
              contain the number of  job  jid  values  that  were
              inserted  into  the  array by the Job module.   The
              number of jid values returned via the jid  list  is
              limited  to the number of elements specified by the
              caller using r_val.

       JJOOBB_GGEETTPPIIDDCCNNTT
              Get the number of processes (pids)  attached  to  a
              specified job.  The data argument should point to a
              structure of type job_pidcnt_t, defined as follows:

                        int       r_val;
                        uint64_t  jid;
                   } job_pidcnt_t;

              The  r_val member indicates the number of processes
              attached to the job upon return.  The jid member is
              set  by the caller to specify the job that is to be
              queried for the number of attached processes.

       JJOOBB_GGEETTPPIIDDLLSSTT
              Get the list of process pids attached to  a  speci­
              fied  job.   The  data  argument  should point to a
              structure of type job_pidlst_t, defined as follows:

                   typedef struct job_pidlst_s {
                        int       r_val;
                        pid_t          *pid;
                        uint64_t  jid;
                   } job_pidlst_t;

              The  list  of process pid values is returned in the
              array pointed to by the pid member.  The caller  is
              responsible  for  allocating and freeing the memory
              for the array pointed to by pid.  The caller speci­
              fies  the number of elements in the array using the
              r_val member.  Upon return, the r_val  member  will
              contain the number of pid values that were inserted
              into the array by the Job module.   The  number  of
              pid  values returned via the pid list is limited to
              the number of  elements  specified  by  the  caller
              using r_val.

       JJOOBB_GGEETTUUSSEERR
              Get  the  owner of a job.  The data argument should
              point to a structure of type job_user_t, defined as
              follows:

                   typedef struct job_user_s {
                        uint16_t  r_user;
                        uint64_t  jid;
                   } job_user_t;

              The jid member is used by the caller to specify the
              job to query to determine  the  owning  user.   The
              r_user  member is set by the Job module to the user
              ID (uid) that owns the job.

       JJOOBB_GGEETTPPRRIIMMEEPPIIDD
              Get the prime (oldest) process pid for a job.   The
              data  argument  should point to a structure of type
              job_primepid_t, defined as follows:

                   typedef struct job_primepid_s {

                        uint64_t  jid;
                   } job_primepid_t;

              The jid member is used by the caller to specify the
              job  to  query.  The process ID (pid) value will be
              returned in the r_pid data member.  If  the  opera­
              tion  failed, then r_pid will be set to 0 and errno
              will be set to indicate the error.


EXAMPLES

       The following example shows how to print a list of job IDs
       for  the jobs currently running on the system: You need to
       use the following include statements:

            #include <stdarg.h>
            #include <unistd.h>
            #include <linux/unistd.h>
            #include <paggctl.h>

            int
            main(void)
            {
                    job_jidcnt_t jidcnt;
                    job_jidlst_t jidlst;
                    int i;

                    /* Get current number of jobs on system */
                    jidcnt.r_val = 0;

                    if (paggctl(JOB_NAME, JOB_GETJIDCNT,
                                    (void *)&jidcnt)) {
                            perror("paggctl: JOB_GETJIDCNT");
                            exit(1);
                    }

                    /* No jobs found on system */
                    if (jidcnt.r_val == 0) {
                            printf("No JIDs on system\n");
                            return 0;
                    }

                    /* Alloc memory to hold list of jobs */
                    jidlst.r_val = jidcnt.r_val;
                    jidlst.jid = (uint64_t *)malloc(
                                   sizeof(uint64_t)
                                   *jidlst.r_val);

                    /* Get list of jobs */
                    if (paggctl(JOB_NAME, JOB_GETJIDLST,
                                    (void *)&jidlst)) {
                            perror("paggctl: JOB_GETJIDLST");
                            exit(1);


                    /* No jobs on system */
                    if (jidlst.r_val == 0) {
                            printf("No JIDs on system\n");
                            free(jidlst.jid);
                            return 0;
                    }

                    /* Print list of jobs on system */
                    printf("List of JIDs on system0);
                    for (i = 0; i < jidlst.r_val; i++) {
                            printf("\t%0#18Lx\n", jidlst.jid[i]);
                    }

                    /* Free memory alloc'd for list */
                    free(jidlst.jid);

                    return 0;

            }


ERRORS

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

       [EBADRQC]      An invalid request code was provided.

       [EBUSY]        Attempt to create a new  job  using  a  jid
                      value that is already in use.

       [EFAULT]       The  data  pointer  references  an  invalid
                      address.

       [EINPROGRESS]  The job is in process of  dying  and  being
                      cleaned up.

       [EINVAL]       An invalid argument was specified.

       [ENODATA]      The  process is not a member of any job.  A
                      jid value could not be found.

       [ENOMEM]       A memory allocation failed.

       [ENOSYS]       The paggctl system call in not implemented.

       [ENXIO]        The  job  module's paggctl service handling
                      function could not be found.

       [ENODEV]       The job module/driver is not loaded.  It is
                      not  registered as a pagg service provider.

       [EPERM]        The  process  does  not  have   appropriate

                      found for the process in question.

       [ESRCH]        The process could not be found.


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.


SEE ALSO

       paggctl(3), job(7).


Man(1) output converted with man2html