'\" te
.\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
.TH ct_pr_status_get_param 3CONTRACT "25 Feb 2008" "SunOS 5.11" "Contract Management Library Functions"
.SH NAME
ct_pr_status_get_param, ct_pr_status_get_fatal, ct_pr_status_get_members, ct_pr_status_get_contracts, ct_pr_status_get_svc_fmri, ct_pr_status_get_svc_aux, ct_pr_status_get_svc_ctid, ct_pr_status_get_svc_creator \- process contract status functions
.SH SYNOPSIS
.LP
.nf
cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB-D_LARGEFILE64_SOURCE\fR \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ] 
#include <libcontract.h>
#include <sys/contract/process.h>

\fBint\fR \fBct_pr_status_get_param\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBuint_t *\fR\fIparamp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_fatal\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBuint_t *\fR\fIeventsp\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_members\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBpid_t **\fR\fIpidpp\fR, \fBuint_t *\fR\fIn\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_contracts\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBctid_t **\fR\fIidpp\fR, \fBuint_t *\fR\fIn\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_svc_fmri\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBchar **\fR\fIfmri\fR); 
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_svc_aux\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBchar **\fR\fIaux\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_svc_ctid\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBctid_t *\fR\fIctid\fR);
.fi

.LP
.nf
\fBint\fR \fBct_pr_status_get_svc_creator\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
     \fBchar **\fR\fIcreator\fR);
.fi

.SH DESCRIPTION
.sp
.LP
These functions read process contract status information from a status object returned by \fBct_status_read\fR(3CONTRACT).
.sp
.LP
The \fBct_pr_status_get_param()\fR function reads the parameter set term. The value is a collection of bits as described in \fBprocess\fR(4).
.sp
.LP
The \fBct_pr_status_get_fatal()\fR function reads the fatal event set term. The value is a collection of bits as described in \fBprocess\fR(4).
.sp
.LP
The \fBct_pr_status_get_members()\fR function obtains a list of the process IDs of the members of the process contract. A pointer to an array of process IDs is stored in *\fIpidpp\fR. The number of elements in this array is stored in *\fIn\fR. These data are freed when the status object is freed by a call to \fBct_status_free\fR(3CONTRACT).
.sp
.LP
The \fBct_pr_status_get_contracts()\fR function obtains a list of IDs of contracts that have been inherited by the contract. A pointer to an array of IDs is stored in *\fIidpp\fR. The number of elements in this array is stored in *\fIn\fR. These data are freed when the status object is freed by a call to \fBct_status_free()\fR.
.sp
.LP
The \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR, and \fBct_pr_status_get_svc_aux()\fR functions read, respectively, the service FMRI, the contract's creator \fBexecname\fR and  the creator's auxiliary field. The buffer pointed to by \fIfmri\fR, \fIaux\fR or \fIcreator\fR, is freed by a call to \fBct_status_free()\fR and should not be modified.
.sp
.LP
The \fBct_pr_status_get_svc_ctid()\fR function reads the process contract id for which the service FMRI was first set.
.SH RETURN VALUES
.sp
.LP
Upon successful completion, \fBct_pr_status_get_param()\fR, \fBct_pr_status_get_fatal()\fR, \fBct_pr_status_get_members()\fR, \fBct_pr_status_get_contracts()\fR, \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR, \fBct_pr_status_get_svc_aux()\fR, and \fBct_pr_status_get_svc_ctid()\fR return 0. Otherwise, they return a non-zero error value.
.SH ERRORS
.sp
.LP
The \fBct_pr_status_get_param()\fR, \fBct_pr_status_get_fatal()\fR, \fBct_pr_status_get_members()\fR, \fBct_pr_status_get_contracts()\fR, \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR, \fBct_pr_status_get_svc_aux()\fR, and \fBct_pr_status_get_svc_ctid()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBEINVAL\fR\fR
.ad
.RS 10n
.rt  
The \fIstathdl\fR argument is not a process contract status object.
.RE

.sp
.LP
The \fBct_pr_status_get_param()\fR, \fBct_pr_status_get_fatal()\fR, \fBct_pr_status_get_members()\fR, \fBct_r_status_get_contracts()\fR, \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR, \fBct_pr_status_get_svc_aux()\fR, and \fBct_pr_status_get_svc_ctid()\fR functions will fail if:
.sp
.ne 2
.mk
.na
\fB\fBENOENT\fR\fR
.ad
.RS 10n
.rt  
The requested data were not available in the status object.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRPrint members of process contract 1.
.sp
.LP
Open the status file for contract 1, read the contract's status, obtain the list of processes, print them, and free the status object.

.sp
.in +2
.nf
#include <sys/types.h>
#include <fcntl.h>
#include <libcontract.h>
#include <stdio.h>
 
\&...
int fd;
uint_t i, n;
pid_t *procs;
ct_stathdl_t st;
 
fd = open("/system/contract/process/1/status");
ct_status_read(fd, &st);
ct_pr_status_get_members(st, &procs, &n);
for (i = 0 ; i < n; i++)
        printf("%ld\en", (long)procs[i]);
ct_status_free(stat);
close(fd);
\&...
.fi
.in -2

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
tab() box;
cw(2.75i) |cw(2.75i) 
lw(2.75i) |lw(2.75i) 
.
ATTRIBUTE TYPEATTRIBUTE VALUE
_
Interface StabilityCommitted
_
MT-LevelSafe
.TE

.SH SEE ALSO
.sp
.LP
\fBct_status_free\fR(3CONTRACT), \fBct_status_read\fR(3CONTRACT), \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBprocess\fR(4), \fBattributes\fR(5), \fBlfcompile\fR(5)