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