Mercurial > illumos > illumos-gate

comparison usr/src/lib/fm/libfmevent/common/libfmevent.h @ 12979:ab9ae749152f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
PSARC/2009/617 Software Events Notification Parameters CLI PSARC/2009/618 snmp-notify: SNMP Notification Daemon for Software Events PSARC/2009/619 smtp-notify: Email Notification Daemon for Software Events PSARC/2010/225 fmd for non-global Solaris zones PSARC/2010/226 Solaris Instance UUID PSARC/2010/227 nvlist_nvflag(3NVPAIR) PSARC/2010/228 libfmevent additions PSARC/2010/257 sysevent_evc_setpropnvl and sysevent_evc_getpropnvl PSARC/2010/265 FMRI and FMA Event Stabilty, 'ireport' category 1 event class, and the 'sw' FMRI scheme PSARC/2010/278 FMA/SMF integration: instance state transitions PSARC/2010/279 Modelling panics within FMA PSARC/2010/290 logadm.conf upgrade 6392476 fmdump needs to pretty-print 6393375 userland ereport/ireport event generation interfaces 6445732 Add email notification agent for FMA and software events 6804168 RFE: Allow an efficient means to monitor SMF services status changes 6866661 scf_values_destroy(3SCF) will segfault if is passed NULL 6884709 Add snmp notification agent for FMA and software events 6884712 Add private interface to tap into libfmd_msg macro expansion capabilities 6897919 fmd to run in a non-global zone 6897937 fmd use of non-private doors is not safe 6900081 add a UUID to Solaris kernel image for use in crashdump identification 6914884 model panic events as a defect diagnosis in FMA 6944862 fmd_case_open_uuid, fmd_case_uuisresolved, fmd_nvl_create_defect 6944866 log legacy sysevents in fmd 6944867 enumerate svc scheme in topo 6944868 software-diagnosis and software-response fmd modules 6944870 model SMF maintenance state as a defect diagnosis in FMA 6944876 savecore runs in foreground for systems with zfs root and dedicated dump 6965796 Implement notification parameters for SMF state transitions and FMA events 6968287 SUN-FM-MIB.mib needs to be updated to reflect Oracle information 6972331 logadm.conf upgrade PSARC/2010/290
author Gavin Maltby <gavin.maltby@oracle.com>
date Fri, 30 Jul 2010 17:04:17 +1000
parents b91faef0c984
children
comparison
equal deleted inserted replaced
12978:19d842faf8e4 12979:ab9ae749152f
18 * 18 *
19 * CDDL HEADER END 19 * CDDL HEADER END
20 */ 20 */
21 21
22 /* 22 /*
23 * Copyright 2009 Sun Microsystems, Inc. All rights reserved. 23 * Copyright (c) 2009, 2010, Oracle and/or its affiliates. All rights reserved.
24 * Use is subject to license terms.
25 */ 24 */
26 25
27 #ifndef _LIBFMEVENT_H 26 #ifndef _LIBFMEVENT_H
28 #define _LIBFMEVENT_H 27 #define _LIBFMEVENT_H
29 28
30 /* 29 /*
31 * FMA event library. 30 * FMA event library.
32 * 31 *
33 * A. Protocol event subscription interfaces (Committed). 32 * A. Protocol event subscription interfaces (Committed).
33 * B. Raw event publication interfaces (Consolidation Private).
34 */ 34 */
35 35
36 #ifdef __cplusplus 36 #ifdef __cplusplus
37 extern "C" { 37 extern "C" {
38 #endif 38 #endif
47 /* 47 /*
48 * Library ABI interface version. Quote the version you are using 48 * Library ABI interface version. Quote the version you are using
49 * to fmev_shdl_init. Only interfaces introduced in or prior to the 49 * to fmev_shdl_init. Only interfaces introduced in or prior to the
50 * quoted version will be available. Once introduced an interface 50 * quoted version will be available. Once introduced an interface
51 * only ever changes compatibly. 51 * only ever changes compatibly.
52 */ 52 *
53 * Introduced in
54 * API Function LIBFMEVENT_VERSION_*
55 * ----------------------- --------------------
56 * fmev_attr_list; 1
57 * fmev_class; 1
58 * fmev_dup; 1
59 * fmev_ev2shdl 2
60 * fmev_hold; 1
61 * fmev_localtime; 1
62 * fmev_rele; 1
63 * fmev_shdl_alloc; 1
64 * fmev_shdl_init; 1
65 * fmev_shdl_fini; 1
66 * fmev_shdl_free; 1
67 * fmev_shdl_getauthority 2
68 * fmev_shdl_nvl2str 2
69 * fmev_shdl_strdup 2
70 * fmev_shdl_strfree 2
71 * fmev_shdl_subscribe; 1
72 * fmev_shdl_unsubscribe; 1
73 * fmev_shdl_zalloc; 1
74 * fmev_shdlctl_serialize; 1
75 * fmev_shdlctl_sigmask; 1
76 * fmev_shdlctl_thrattr; 1
77 * fmev_shdlctl_thrcreate; 1
78 * fmev_shdlctl_thrsetup; 1
79 * fmev_strerror; 1
80 * fmev_timespec; 1
81 * fmev_time_nsec; 1
82 * fmev_time_sec; 1
83 */
84
53 #define LIBFMEVENT_VERSION_1 1 85 #define LIBFMEVENT_VERSION_1 1
54 86 #define LIBFMEVENT_VERSION_2 2
55 #define LIBFMEVENT_VERSION_LATEST LIBFMEVENT_VERSION_1 87
88 #define LIBFMEVENT_VERSION_LATEST LIBFMEVENT_VERSION_2
56 89
57 /* 90 /*
58 * Success and error return values. The descriptive comment for each 91 * Success and error return values. The descriptive comment for each
59 * FMEVERR_* becomes the string that is returned by fmev_strerror for that 92 * FMEVERR_* becomes the string that is returned by fmev_strerror for that
60 * error type. 93 * error type.
73 FMEVERR_BUSY, /* Resource is busy */ 106 FMEVERR_BUSY, /* Resource is busy */
74 FMEVERR_DUPLICATE, /* Duplicate request */ 107 FMEVERR_DUPLICATE, /* Duplicate request */
75 FMEVERR_BADCLASS, /* Bad event class or class pattern */ 108 FMEVERR_BADCLASS, /* Bad event class or class pattern */
76 FMEVERR_NOMATCH, /* No match to criteria provided */ 109 FMEVERR_NOMATCH, /* No match to criteria provided */
77 FMEVERR_MAX_SUBSCRIBERS, /* Exceeds maximum subscribers per handle */ 110 FMEVERR_MAX_SUBSCRIBERS, /* Exceeds maximum subscribers per handle */
78 FMEVERR_INVALIDARG /* Argument is invalid */ 111 FMEVERR_INVALIDARG, /* Argument is invalid */
112 FMEVERR_STRING2BIG, /* String argument exceeds maximum length */
113 FMEVERR_VARARGS_MALFORMED, /* Varargs list bad or incorrectly terminated */
114 FMEVERR_VARARGS_TOOLONG, /* Varargs list exceeds maximum length */
115 FMEVERR_BADRULESET, /* Ruleset selected for publication is bad */
116 FMEVERR_BADPRI, /* Priority selected for publication is bad */
117 FMEVERR_TRANSPORT, /* Error in underlying event transport implementation */
118 FMEVERR_NVLIST /* nvlist argument is not of type NV_UNIQUE_NAME */
79 } fmev_err_t; 119 } fmev_err_t;
80 120
81 /* 121 /*
82 * Some interfaces return an fmev_err_t - FMEV_SUCCESS on success, otherwise 122 * Some interfaces return an fmev_err_t - FMEV_SUCCESS on success, otherwise
83 * failure of the indicated type. You can use fmev_strerror to render an 123 * failure of the indicated type. You can use fmev_strerror to render an
207 extern fmev_err_t fmev_shdl_subscribe(fmev_shdl_t, const char *, fmev_cbfunc_t, 247 extern fmev_err_t fmev_shdl_subscribe(fmev_shdl_t, const char *, fmev_cbfunc_t,
208 void *); 248 void *);
209 extern fmev_err_t fmev_shdl_unsubscribe(fmev_shdl_t, const char *); 249 extern fmev_err_t fmev_shdl_unsubscribe(fmev_shdl_t, const char *);
210 250
211 /* 251 /*
252 * Retrieve an authority nvlist for the fault manager that is forwarding
253 * events to us. This may be NULL if the fault manager has not yet
254 * started up and made the information available. The caller is
255 * responsible for freeing the nvlist returned.
256 */
257 extern fmev_err_t fmev_shdl_getauthority(fmev_shdl_t, nvlist_t **);
258
259 /*
212 * Event access. In the common case that the event is processed to 260 * Event access. In the common case that the event is processed to
213 * completion in the context of the event callback you need only 261 * completion in the context of the event callback you need only
214 * use fmev_attr_list to access the nvlist of event attributes, 262 * use fmev_attr_list to access the nvlist of event attributes,
215 * with no responsibility for freeing the event or the nvlist; for 263 * with no responsibility for freeing the event or the nvlist; for
216 * convenience, fmev_class and fmev_timestamp can both be used to 264 * convenience, fmev_class and fmev_timestamp can both be used to
248 * The time at which a protocol event was generated is available via 296 * The time at which a protocol event was generated is available via
249 * fmev_timespec; tv_sec has seconds since the epoch, and tv_nsec nanoseconds 297 * fmev_timespec; tv_sec has seconds since the epoch, and tv_nsec nanoseconds
250 * past that second. This can fail with FMEVERR_OVERFLOW if the seconds 298 * past that second. This can fail with FMEVERR_OVERFLOW if the seconds
251 * value does not fit within a time_t; you can retrieve the 64-bit second 299 * value does not fit within a time_t; you can retrieve the 64-bit second
252 * and nanosecond values with fmev_time_sec and fmev_time_nsec. 300 * and nanosecond values with fmev_time_sec and fmev_time_nsec.
301 *
302 * An FMRI in an event payload is typically in nvlist form, i.e
303 * DATA_TYPE_NVLIST. That form is useful for extracting individual
304 * component fields, but that requires knowledge of the FMRI scheme and
305 * Public commitment thereof. FMRIs are typically Private, but in some
306 * cases they can be descriptive such as in listing the ASRU(s) affected
307 * by a fault; so we offer an API member which will blindly render any
308 * FMRI in its string form. Use fmev_shdl_nvl2str to format an nvlist_t
309 * as a string (if it is recognized as an FMRI); the caller is responsible
310 * for freeing the returned string using fmev_shdl_strfree. If
311 * fmev_shdl_nvl2str fails it will return NULL with fmev_errno set -
312 * FMEVERR_INVALIDARG if the nvlist_t does not appear to be a valid/known FMRI,
313 * FMEVERR_ALLOC if an allocation for memory for the string failed.
314 *
315 * fmev_ev2shdl will return the fmev_shdl_t with which a received fmev_t
316 * is associated. It should only be used in an event delivery callback
317 * context and for the event received in that callback.
253 */ 318 */
254 319
255 extern nvlist_t *fmev_attr_list(fmev_t); 320 extern nvlist_t *fmev_attr_list(fmev_t);
256 extern const char *fmev_class(fmev_t); 321 extern const char *fmev_class(fmev_t);
257 322
262 327
263 extern void fmev_hold(fmev_t); 328 extern void fmev_hold(fmev_t);
264 extern void fmev_rele(fmev_t); 329 extern void fmev_rele(fmev_t);
265 extern fmev_t fmev_dup(fmev_t); 330 extern fmev_t fmev_dup(fmev_t);
266 331
332 extern char *fmev_shdl_nvl2str(fmev_shdl_t, nvlist_t *);
333
334 extern fmev_shdl_t fmev_ev2shdl(fmev_t);
335
267 /* 336 /*
268 * The following will allocate and free memory based on the choices made 337 * The following will allocate and free memory based on the choices made
269 * at fmev_shdl_init. 338 * at fmev_shdl_init.
270 */ 339 */
271 void *fmev_shdl_alloc(fmev_shdl_t, size_t); 340 void *fmev_shdl_alloc(fmev_shdl_t, size_t);
272 void *fmev_shdl_zalloc(fmev_shdl_t, size_t); 341 void *fmev_shdl_zalloc(fmev_shdl_t, size_t);
273 void fmev_shdl_free(fmev_shdl_t, void *, size_t); 342 void fmev_shdl_free(fmev_shdl_t, void *, size_t);
343 extern char *fmev_shdl_strdup(fmev_shdl_t, char *);
344 extern void fmev_shdl_strfree(fmev_shdl_t, char *);
345
346 /*
347 * Part B - Raw Event Publication
348 * ======
349 *
350 * The following interfaces are private to the Solaris system and are
351 * subject to change at any time without notice. Applications using
352 * these interfaces will fail to run on future releases. The interfaces
353 * should not be used for any purpose until they are publicly documented
354 * for use outside of Sun. These interface are *certain* to change
355 * incompatibly, as the current interface is very much purpose-built for
356 * a limited application.
357 *
358 * The interfaces below allow a process to publish a "raw" event
359 * which will be transmitted to the fault manager and post-processed
360 * into a full FMA protocol event. The post-processing to be applied
361 * is selected by a "ruleset" specified either implicitly or explicitly
362 * at publication. A ruleset will take the raw event (comprising
363 * class, subclass, priority, raw payload) and mark it up into a full
364 * protocol event; it may also augment the payload through looking up
365 * details that would have been costly to compute at publication time.
366 *
367 * In this first implementation event dispatch is synchronous and blocking,
368 * and not guaranteed to be re-entrant. This limits the call sites
369 * at which publication calls can be placed, and also means that careful
370 * thought is required before sprinkling event publication code throughout
371 * common system libraries. The dispatch mechanism amounts to some
372 * nvlist chicanery followed by a sysevent_evc_publish. A future revision
373 * will relax the context from which one may publish, and add more-powerful
374 * publication interfaces.
375 *
376 * Some publication interfaces (those ending in _nvl) accept a preconstructed
377 * nvlist as raw event payload. We require that such an nvlist be of type
378 * NV_UNIQUE_NAME. The publication interfaces all call nvlist_free on any
379 * nvlist that is passed for publication.
380 *
381 * Other publication interfaces allow you to build up the raw event payload
382 * by specifying the members in a varargs list terminated by FMEV_ARG_TERM.
383 * Again we require that payload member names are unique (that is, you cannot
384 * have two members with the same name but different datatype). See
385 * <sys/nvpair.h> for the data_type_t enumeration of types supported - but
386 * note that DATA_TYPE_BOOLEAN is excluded (DATA_TYPE_BOOLEAN_VALUE is
387 * supported). A single-valued (non-array type) member is specified with 3
388 * consecutive varargs as:
389 *
390 * (char *)name, DATA_TYPE_foo, (type)value
391 *
392 * An array-valued member is specified with 4 consecutive varargs as:
393 *
394 * (char *)name, DATA_TYPE_foo_ARRAY, (int)nelem, (type *)arrayptr
395 *
396 * The varargs list that specifies the nvlist must begin with an
397 * integer that specifies the number of members that follow. For example:
398 *
399 * uint32_t mode;
400 * char *clientname;
401 * uint32_t ins[NARGS];
402 *
403 * fmev_publish("class", "subclass", FMEV_LOPRI,
404 * 3,
405 * "mode", DATA_TYPE_UINT32, mode,
406 * "client", DATA_TYPE_STRING, clientname,
407 * "ins", DATA_TYPE_UINT32_ARRAY, sizeof (ins) / sizeof (ins[0]), ins,
408 * FMEV_ARG_TERM);
409 *
410 * The following tables summarize the capabilities of the various
411 * publication interfaces.
412 *
413 * Detector
414 * Interface Ruleset? File/Line Func
415 * ---------------------------- -------- --------- ----
416 * fmev_publish_nvl default Yes No
417 * fmev_publish_nvl (C99) default Yes Yes
418 * fmev_rspublish_nvl chosen Yes No
419 * fmev_rspublish_nvl (C99) chosen Yes Yes
420 * fmev_publish default No No
421 * fmev_publish (C99) default Yes Yes
422 * fmev_rspublish chosen No No
423 * fmev_rspublish (C99) chosen Yes Yes
424 *
425 * Summary: if not using C99 then try to use the _nvl variants as the
426 * varargs variants will not include file, line or function in the
427 * detector.
428 */
429
430 /*
431 * In publishing an event you must select a "ruleset" (or accept the
432 * defaults). Rulesets are listed in the following header.
433 */
434 #include <fm/libfmevent_ruleset.h>
435
436 /*
437 * In publishing an event we can specify a class and subclass (which
438 * in post-processing combine in some way selected by the ruleset to
439 * form a full event protocol class). The maximum class and subclass
440 * string lengths are as follows.
441 */
442 #define FMEV_PUB_MAXCLASSLEN 32
443 #define FMEV_PUB_MAXSUBCLASSLEN 32
444
445 /*
446 * Events are either high-priority (try really hard not to lose) or
447 * low-priority (can drop, throttle etc). Convert a fmev_pri_t to
448 * a string with fmev_pri_string().
449 */
450 typedef enum fmev_pri {
451 FMEV_LOPRI = 0x1000,
452 FMEV_HIPRI
453 } fmev_pri_t;
454
455 extern const char *fmev_pri_string(fmev_pri_t);
456
457 /*
458 * The varargs event publication interfaces must terminate the list
459 * of nvpair specifications with FMEV_ARG_TERM. This is to guard
460 * against very easily-made mistakes in those arg lists.
461 */
462 #define FMEV_ARG_TERM (void *)0xa4a3a2a1
463
464 /*
465 * The following are NOT for direct use.
466 */
467 extern fmev_err_t _i_fmev_publish_nvl(
468 const char *, const char *, int64_t,
469 const char *, const char *, const char *,
470 fmev_pri_t, nvlist_t *);
471
472 extern fmev_err_t _i_fmev_publish(
473 const char *, const char *, int64_t,
474 const char *, const char *, const char *,
475 fmev_pri_t,
476 uint_t, ...);
477
478 /*
479 * Post-processing will always generate a "detector" payload member. In
480 * the case of the _nvl publishing variants the detector information
481 * includes file and line number, and - if your application is compiled
482 * with C99 enabled - function name.
483 */
484 #if __STDC_VERSION__ - 0 >= 199901L
485 #define _FMEVFUNC __func__
486 #else
487 #define _FMEVFUNC NULL
488 #endif
489
490 /*
491 * All these definitions "return" an fmev_err_t.
492 *
493 * In the _nvl variants you pass a preconstructed event payload; otherwise
494 * you include an integer indicating the number of payload
495 * (name, type, value) tuples that follow, then all those tuples, finally
496 * terminated by FMEV_ARG_TERM.
497 *
498 * In the rspublish variants you select a ruleset from
499 * libfmevent_ruleset.h - just use the final suffix (as in
500 * DEFAULT, EREPORT, ISV).
501 *
502 * The primary classification must not be NULL or the empty string.
503 *
504 * arg type Description
505 * ------- --------------- -------------------------------------------
506 * ruleset const char * Ruleset; can be NULL (implies default ruleset)
507 * cl1 const char * Primary classification string
508 * cl2 const char * Secondary classification string
509 * pri fmev_pri_t Priority
510 * nvl nvlist_t * Preconstructed attributes; caller must free
511 * ntuples int Number of tuples before FMEV_ARG_TERM
512 * suffix - See above.
513 */
514
515 /*
516 * fmev_publish_nvl - Default ruleset implied; class/subclass, pri and an nvl
517 */
518 #define fmev_publish_nvl(cl1, cl2, pri, nvl) \
519 _i_fmev_publish_nvl( \
520 __FILE__, _FMEVFUNC, __LINE__, \
521 FMEV_RULESET_DEFAULT, cl1, cl2, \
522 pri, nvl)
523
524 /*
525 * fmev_rspublish_nvl - As fmev_publish_nvl, but with a chosen ruleset.
526 */
527 #define fmev_rspublish_nvl(ruleset, cl1, cl2, pri, nvl) \
528 _i_fmev_publish_nvl( \
529 __FILE__, _FMEVFUNC, __LINE__, \
530 ruleset, cl1, cl2, \
531 pri, nvl)
532
533 #if __STDC_VERSION__ - 0 >= 199901L && !defined(__lint)
534
535 /*
536 * fmev_publish (C99 version) - Default ruleset; class/subclass, pri, nvpairs
537 */
538 #define fmev_publish(cl1, cl2, pri, ntuples, ...) \
539 _i_fmev_publish( \
540 __FILE__, __func__, __LINE__, \
541 FMEV_RULESET_DEFAULT, cl1, cl2, \
542 pri, \
543 ntuples, __VA_ARGS__)
544
545
546 /*
547 * fmev_rspublish (C99 version) - As fmev_publish, but with a chosen ruleset.
548 */
549 #define fmev_rspublish(ruleset, cl1, cl2, pri, ntuples, ...) \
550 _i_fmev_publish( \
551 __FILE__, __func__, __LINE__, \
552 ruleset, cl1, cl2, \
553 pri, \
554 ntuples, __VA_ARGS__)
555
556 #else
557
558 /*
559 * fmev_publish (pre C99)
560 */
561 extern fmev_err_t fmev_publish(const char *, const char *,
562 fmev_pri_t, uint_t, ...);
563
564 /*
565 * fmev_rspublish (pre C99)
566 */
567 extern fmev_err_t fmev_rspublish(const char *, const char *, const char *,
568 fmev_pri_t, uint_t, ...);
569
570 #endif /* __STDC_VERSION__ */
274 571
275 #ifdef __cplusplus 572 #ifdef __cplusplus
276 } 573 }
277 #endif 574 #endif
278 575