share/man/man3contract/ct_pr_status_get_param.3contract

   1 '\" te
   2 .\" Copyright (c) 2008, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH CT_PR_STATUS_GET_PARAM 3CONTRACT "Feb 25, 2008"
   7 .SH NAME
   8 ct_pr_status_get_param, ct_pr_status_get_fatal, ct_pr_status_get_members,
   9 ct_pr_status_get_contracts, ct_pr_status_get_svc_fmri,
  10 ct_pr_status_get_svc_aux, ct_pr_status_get_svc_ctid,
  11 ct_pr_status_get_svc_creator \- process contract status functions
  12 .SH SYNOPSIS
  13 .LP
  14 .nf
  15 cc [ \fIflag\fR\&.\|.\|. ] \fIfile\fR\&.\|.\|. \fB -lcontract \fR [ \fIlibrary\fR\&.\|.\|. ]
  16 #include <libcontract.h>
  17 #include <sys/contract/process.h>
  18
  19 \fBint\fR \fBct_pr_status_get_param\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBuint_t *\fR\fIparamp\fR);
  20 .fi
  21
  22 .LP
  23 .nf
  24 \fBint\fR \fBct_pr_status_get_fatal\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBuint_t *\fR\fIeventsp\fR);
  25 .fi
  26
  27 .LP
  28 .nf
  29 \fBint\fR \fBct_pr_status_get_members\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
  30      \fBpid_t **\fR\fIpidpp\fR, \fBuint_t *\fR\fIn\fR);
  31 .fi
  32
  33 .LP
  34 .nf
  35 \fBint\fR \fBct_pr_status_get_contracts\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
  36      \fBctid_t **\fR\fIidpp\fR, \fBuint_t *\fR\fIn\fR);
  37 .fi
  38
  39 .LP
  40 .nf
  41 \fBint\fR \fBct_pr_status_get_svc_fmri\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBchar **\fR\fIfmri\fR);
  42 .fi
  43
  44 .LP
  45 .nf
  46 \fBint\fR \fBct_pr_status_get_svc_aux\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBchar **\fR\fIaux\fR);
  47 .fi
  48
  49 .LP
  50 .nf
  51 \fBint\fR \fBct_pr_status_get_svc_ctid\fR(\fBct_stathdl_t\fR \fIstathdl\fR, \fBctid_t *\fR\fIctid\fR);
  52 .fi
  53
  54 .LP
  55 .nf
  56 \fBint\fR \fBct_pr_status_get_svc_creator\fR(\fBct_stathdl_t\fR \fIstathdl\fR,
  57      \fBchar **\fR\fIcreator\fR);
  58 .fi
  59
  60 .SH DESCRIPTION
  61 .sp
  62 .LP
  63 These functions read process contract status information from a status object
  64 returned by \fBct_status_read\fR(3CONTRACT).
  65 .sp
  66 .LP
  67 The \fBct_pr_status_get_param()\fR function reads the parameter set term. The
  68 value is a collection of bits as described in \fBprocess\fR(4).
  69 .sp
  70 .LP
  71 The \fBct_pr_status_get_fatal()\fR function reads the fatal event set term. The
  72 value is a collection of bits as described in \fBprocess\fR(4).
  73 .sp
  74 .LP
  75 The \fBct_pr_status_get_members()\fR function obtains a list of the process IDs
  76 of the members of the process contract. A pointer to an array of process IDs is
  77 stored in *\fIpidpp\fR. The number of elements in this array is stored in
  78 *\fIn\fR. These data are freed when the status object is freed by a call to
  79 \fBct_status_free\fR(3CONTRACT).
  80 .sp
  81 .LP
  82 The \fBct_pr_status_get_contracts()\fR function obtains a list of IDs of
  83 contracts that have been inherited by the contract. A pointer to an array of
  84 IDs is stored in *\fIidpp\fR. The number of elements in this array is stored in
  85 *\fIn\fR. These data are freed when the status object is freed by a call to
  86 \fBct_status_free()\fR.
  87 .sp
  88 .LP
  89 The \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR,
  90 and \fBct_pr_status_get_svc_aux()\fR functions read, respectively, the service
  91 FMRI, the contract's creator \fBexecname\fR and  the creator's auxiliary field.
  92 The buffer pointed to by \fIfmri\fR, \fIaux\fR or \fIcreator\fR, is freed by a
  93 call to \fBct_status_free()\fR and should not be modified.
  94 .sp
  95 .LP
  96 The \fBct_pr_status_get_svc_ctid()\fR function reads the process contract id
  97 for which the service FMRI was first set.
  98 .SH RETURN VALUES
  99 .sp
 100 .LP
 101 Upon successful completion, \fBct_pr_status_get_param()\fR,
 102 \fBct_pr_status_get_fatal()\fR, \fBct_pr_status_get_members()\fR,
 103 \fBct_pr_status_get_contracts()\fR, \fBct_pr_status_get_svc_fmri()\fR,
 104 \fBct_pr_status_get_svc_creator()\fR, \fBct_pr_status_get_svc_aux()\fR, and
 105 \fBct_pr_status_get_svc_ctid()\fR return 0. Otherwise, they return a non-zero
 106 error value.
 107 .SH ERRORS
 108 .sp
 109 .LP
 110 The \fBct_pr_status_get_param()\fR, \fBct_pr_status_get_fatal()\fR,
 111 \fBct_pr_status_get_members()\fR, \fBct_pr_status_get_contracts()\fR,
 112 \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR,
 113 \fBct_pr_status_get_svc_aux()\fR, and \fBct_pr_status_get_svc_ctid()\fR
 114 functions will fail if:
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fBEINVAL\fR\fR
 119 .ad
 120 .RS 10n
 121 The \fIstathdl\fR argument is not a process contract status object.
 122 .RE
 123
 124 .sp
 125 .LP
 126 The \fBct_pr_status_get_param()\fR, \fBct_pr_status_get_fatal()\fR,
 127 \fBct_pr_status_get_members()\fR, \fBct_r_status_get_contracts()\fR,
 128 \fBct_pr_status_get_svc_fmri()\fR, \fBct_pr_status_get_svc_creator()\fR,
 129 \fBct_pr_status_get_svc_aux()\fR, and \fBct_pr_status_get_svc_ctid()\fR
 130 functions will fail if:
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fBENOENT\fR\fR
 135 .ad
 136 .RS 10n
 137 The requested data were not available in the status object.
 138 .RE
 139
 140 .SH EXAMPLES
 141 .LP
 142 \fBExample 1 \fRPrint members of process contract 1.
 143 .sp
 144 .LP
 145 Open the status file for contract 1, read the contract's status, obtain the
 146 list of processes, print them, and free the status object.
 147
 148 .sp
 149 .in +2
 150 .nf
 151 #include <sys/types.h>
 152 #include <fcntl.h>
 153 #include <libcontract.h>
 154 #include <stdio.h>
 155
 156 \&...
 157 int fd;
 158 uint_t i, n;
 159 pid_t *procs;
 160 ct_stathdl_t st;
 161
 162 fd = open("/system/contract/process/1/status");
 163 ct_status_read(fd, &st);
 164 ct_pr_status_get_members(st, &procs, &n);
 165 for (i = 0 ; i < n; i++)
 166         printf("%ld\en", (long)procs[i]);
 167 ct_status_free(stat);
 168 close(fd);
 169 \&...
 170 .fi
 171 .in -2
 172
 173 .SH ATTRIBUTES
 174 .sp
 175 .LP
 176 See \fBattributes\fR(5) for descriptions of the following attributes:
 177 .sp
 178
 179 .sp
 180 .TS
 181 box;
 182 c | c
 183 l | l .
 184 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 185 _
 186 Interface Stability     Committed
 187 _
 188 MT-Level        Safe
 189 .TE
 190
 191 .SH SEE ALSO
 192 .sp
 193 .LP
 194 \fBct_status_free\fR(3CONTRACT), \fBct_status_read\fR(3CONTRACT),
 195 \fBlibcontract\fR(3LIB), \fBcontract\fR(4), \fBprocess\fR(4),
 196 \fBattributes\fR(5)