usr/src/man/man3sysevent/sysevent_post_event.3sysevent

   1 '\" te
   2 .\" Copyright (c) 2009, 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. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. 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
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SYSEVENT_POST_EVENT 3SYSEVENT "Jul 24, 2009"
   7 .SH NAME
   8 sysevent_post_event \- post system event for applications
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBcc\fR  [ \fIflag\fR\&.\|.\|. ]  \fIfile\fR\&.\|.\|. \fB-lsysevent\fR \fB -lnvpair \fR [ \fIlibrary\fR\&.\|.\|. ]
  13 #include <libsysevent.h>
  14 #include <libnvpair.h>
  15
  16 \fBint\fR \fBsysevent_post_event\fR(\fBchar *\fR\fIclass\fR, \fBchar *\fR\fIsubclass\fR, \fBchar *\fR\fIvendor\fR,
  17      \fBchar *\fR\fIpublisher\fR, \fBnvlist_t *\fR\fIattr_list\fR, \fBsysevent_id_t *\fR\fIeid\fR);
  18 .fi
  19
  20 .SH PARAMETERS
  21 .sp
  22 .ne 2
  23 .na
  24 \fB\fIattr_list\fR\fR
  25 .ad
  26 .RS 13n
  27 pointer to an \fBnvlist_t\fR, listing the name-value attributes associated with
  28 the event, or \fINULL\fR if there are no such attributes for this event
  29 .RE
  30
  31 .sp
  32 .ne 2
  33 .na
  34 \fB\fIclass\fR\fR
  35 .ad
  36 .RS 13n
  37 pointer to a string defining the event class
  38 .RE
  39
  40 .sp
  41 .ne 2
  42 .na
  43 \fB\fIeid\fR\fR
  44 .ad
  45 .RS 13n
  46 pointer to a system unique identifier
  47 .RE
  48
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIpublisher\fR\fR
  53 .ad
  54 .RS 13n
  55 pointer to a string defining the event's publisher nam
  56 .RE
  57
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fIsubclass\fR\fR
  62 .ad
  63 .RS 13n
  64 pointer to a string defining the event subclass
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fIvendor\fR\fR
  71 .ad
  72 .RS 13n
  73 pointer to a string defining the vendor
  74 .RE
  75
  76 .SH DESCRIPTION
  77 .sp
  78 .LP
  79 The \fBsysevent_post_event()\fR function causes a system event of the specified
  80 class, subclass, vendor, and publisher to be generated on behalf of the caller
  81 and queued for delivery to  the sysevent daemon \fBsyseventd\fR(1M).
  82 .sp
  83 .LP
  84 The vendor should be the company stock symbol (or similarly enduring
  85 identifier) of the event posting application. The publisher should be the name
  86 of the application generating the event.
  87 .sp
  88 .LP
  89 For example, all events posted by Sun applications begin with the company's
  90 stock symbol, "SUNW". The publisher is usually the name of the application
  91 generating the system event. A system event generated by \fBdevfsadm\fR(1M) has
  92 a publisher string of \fBdevfsadm\fR.
  93 .sp
  94 .LP
  95 The publisher information is used by sysevent consumers to filter unwanted
  96 event publishers.
  97 .sp
  98 .LP
  99 Upon successful queuing of the system event, a unique identifier is assigned to
 100 \fIeid\fR.
 101 .SH RETURN VALUES
 102 .sp
 103 .LP
 104 The \fBsysevent_post_event()\fR function returns \fB0\fR if the system event
 105 has been queued successfully for delivery. Otherwise it returns \fB\(mi1\fR and
 106 sets \fBerrno\fR to indicate the error.
 107 .SH ERRORS
 108 .sp
 109 .LP
 110 The \fBsysevent_post_event()\fR function will fail if:
 111 .sp
 112 .ne 2
 113 .na
 114 \fB\fBENOMEM\fR\fR
 115 .ad
 116 .RS 10n
 117 Insufficient resources to queue the system event.
 118 .RE
 119
 120 .sp
 121 .ne 2
 122 .na
 123 \fB\fBEIO\fR\fR
 124 .ad
 125 .RS 10n
 126 The \fBsyseventd\fR daemon is not responding and events cannot be queued or
 127 delivered at this time.
 128 .RE
 129
 130 .sp
 131 .ne 2
 132 .na
 133 \fB\fBEINVAL\fR\fR
 134 .ad
 135 .RS 10n
 136 Invalid argument.
 137 .RE
 138
 139 .sp
 140 .ne 2
 141 .na
 142 \fB\fBEPERM\fR\fR
 143 .ad
 144 .RS 10n
 145 Permission denied.
 146 .RE
 147
 148 .sp
 149 .ne 2
 150 .na
 151 \fB\fBEFAULT\fR\fR
 152 .ad
 153 .RS 10n
 154 A copy error occurred.
 155 .RE
 156
 157 .SH EXAMPLES
 158 .LP
 159 \fBExample 1 \fRPost a system event event with no attributes.
 160 .sp
 161 .LP
 162 The following example posts a system event event with no attributes.
 163
 164 .sp
 165 .in +2
 166 .nf
 167 if (sysevent_post_event(EC_PRIV, "ESC_MYSUBCLASS", "SUNW", argv[0],
 168     NULL), &eid == -1) {
 169         fprintf(stderr, "error logging system event\en");
 170 }
 171 .fi
 172 .in -2
 173
 174 .LP
 175 \fBExample 2 \fRPost a system event with two name-value pair attributes.
 176 .sp
 177 .LP
 178 The following example posts a system event event with two name-value pair
 179 attributes, an integer value and a string.
 180
 181 .sp
 182 .in +2
 183 .nf
 184 nvlist_t        *attr_list;
 185 uint32_t        uint32_val = 0XFFFFFFFF;
 186 char            *string_val = "string value data";
 187
 188 if (nvlist_alloc(&attr_list, 0, 0) == 0) {
 189         err = nvlist_add_uint32(attr_list, "uint32 data", uint32_val);
 190         if (err == 0)
 191                 err = nvlist_add_string(attr_list, "str data",
 192                     string_val);
 193         if (err == 0)
 194                 err = sysevent_post_event(EC_PRIV, "ESC_MYSUBCLASS",
 195                     "SUNW", argv[0], attr_list, &eid);
 196         if (err != 0)
 197                 fprintf(stderr, "error logging system event\en");
 198         nvlist_free(attr_list);
 199 }
 200 .fi
 201 .in -2
 202
 203 .SH ATTRIBUTES
 204 .sp
 205 .LP
 206 See \fBattributes\fR(5) for descriptions of the following attributes:
 207 .sp
 208
 209 .sp
 210 .TS
 211 box;
 212 c | c
 213 l | l .
 214 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 215 _
 216 Interface Stability     Committed
 217 _
 218 MT-Level        MT-Safe
 219 .TE
 220
 221 .SH SEE ALSO
 222 .sp
 223 .LP
 224 \fBdevfsadm\fR(1M), \fBsyseventd\fR(1M), \fBnvlist_add_boolean\fR(3NVPAIR),
 225 \fBnvlist_alloc\fR(3NVPAIR), \fBattributes\fR(5)
 226 .SH NOTES
 227 .sp
 228 .LP
 229 The \fBlibsysevent\fR interfaces do not work at all in non-global zones.