svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
fmev_shdl_init(3fm)
fmev_..._init(3FM) Fault Management Events Library Functionsfmev_..._init(3FM)
NAME
fmev_shdl_init, fmev_shdl_fini, fmev_shdl_subscribe, fmev_shdl_unsub‐
scribe, fmev_shdl_getauthority, fmev_errno, fmev_strerror,
fmev_attr_list, fmev_class, fmev_timespec, fmev_time_sec,
fmev_time_nsec, fmev_localtime, fmev_hold, fmev_hrtime, fmev_rele,
fmev_dup, fmev_ev2shdl, fmev_shdl_alloc, fmev_shdl_zalloc,
fmev_shdl_free, fmev_shdl_strdup, fmev_shdl_strfree, fmev_shdl_nvl2str,
fmev_shdlctl_serialize, fmev_shdlctl_thrattr, fmev_shdlctl_sigmask,
fmev_shdlctl_thrsetup, fmev_shdlctl_thrcreate - subscription to fault
management events from an external process
SYNOPSIS
cc [ flag... ] file... −L/usr/lib/fm −lfmevent −lnvpair [ library... ]
#include <fm/libfmevent.h>
#include <libnvpair.h>
typedef enum fmev_err_t;
extern fmev_err_t fmev_errno;
const char *fmev_strerror(fmev_err_t err);
typedef struct fmev_shdl *fmev_shdl_t;
typedef void fmev_cbfunc_t(fmev_t, const char *, nvlist_t *, void *);
fmev_shdl_t fmev_shdl_init(uint32_t api_version,
void *(*alloc)(size_t), void *(*zalloc)(size_t),
void (*free)(void *, size_t));
fmev_err_t fmev_shdl_fini(fmev_shdl_t hdl);
fmev_err_t fmev_shdl_subscribe(fmev_shdl_t hdl, const char *classpat,
fmev_cbfunc_t callback, void *cookie);
fmev_err_t fmev_shdl_unsubscribe(fmev_shdl_t hdl,
const char *classpat);
fmev_err_t fmev_shdl_getauthority(fmev_shdl_t hdl, nvlist_t **authp);
fmev_err_t fmev_shdlctl_serialize(fmev_shdl_t hdl);
fmev_err_t fmev_shdlctl_thrattr(fmev_shdl_t hdl, pthread_attr_t *attr);
fmev_err_t fmev_shdlctl_sigmask(fmev_shdl_t hdl, sigset_t *set);
fmev_err_t fmev_shdlctl_thrsetup(fmev_shdl_t hdl,
door_xcreate_thrsetup_func_t *setupfunc, void *cookie);
fmev_err_t fmev_shdlctl_thrcreate(fmev_shdl_t hdl,
door_xcreate_server_func_t *createfunc, void *cookie);
typedef struct fmev *fmev_t;
nvlist_t *fmev_attr_list(fmev_t ev);
const char *fmev_class(fmev_t ev);
fmev_err_t fmev_timespec(fmev_t ev, struct timespec *res);
uint64_t fmev_time_sec(fmev_t ev);
uint64_t fmev_time_nsec(fmev_t ev);
struct tm *fmev_localtime(fmev_t ev, struct tm *res);
hrtime_t fmev_hrtime(fmev_t ev);
void fmev_hold(fmev_t ev);
void fmev_rele(fmev_t ev);
fmev_t fmev_dup(fmev_t ev);
fmev_shdl_t fmev_ev2shdl(fmev_t ev);
void *fmev_shdl_alloc(fmev_shdl_t hdl, size_t sz);
void *fmev_shdl_zalloc(fmev_shdl_t hdl, size_t sz);
void fmev_shdl_free(fmev_shdl_t hdl, void *buf, size_t sz);
char *fmev_shdl_strdup(fmev_shdl_t hdl, char *str);
void fmev_shdl_strfree(fmev_shdl_t hdl, char *str);
char *fmev_shdl_nvl2str(fmev_shdl_t hdl, nvlist_t *fmri);
DESCRIPTION
The Solaris fault management daemon (fmd) is the central point in So‐
laris for fault management. It receives observations from various
sources and delivers them to subscribing diagnosis engines; if those
diagnosis engines diagnose a problem, the fault manager publishes addi‐
tional protocol events to track the problem lifecycle from initial di‐
agnosis through repair and final problem resolution. The event protocol
is specified in the Sun Fault Management Event Protocol Specification.
The interfaces described here allow an external process to subscribe to
protocol events. See the Fault Management Daemon Programmer's Reference
Guide for additional information on fmd.
The fmd module API (not a Committed interface) allows plugin modules to
load within the fmd process, subscribe to events of interest, and par‐
ticipate in various diagnosis and response activities. Of those mod‐
ules, some are notification agents and will subscribe to events de‐
scribing diagnoses and their subsequent lifecycle and render these to
console/syslog (for the syslog-msgs agent) and via SNMP trap and brows‐
able MIB (for the snmp-trapgen module and the corresponding dlmod for
the SNMP daemon). It has not been possible to subscribe to protocol
events outside of the context of an fmd plugin. The libfmevent inter‐
face provides this external subscription mechanism. External sub‐
scribers may receive protocol events as fmd modules do, but they cannot
participate in other aspects of the fmd module API such as diagnosis.
External subscribers are therefore suitable as notification agents and
for transporting fault management events.
Fault Management Protocol Events
This protocol is defined in the Sun Fault Management Event Protocol
Specification. Note that while the API described on this manual page
are Committed, the protocol events themselves (in class names and all
event payload) are not Committed along with this API. The protocol
specification document describes the commitment level of individual
event classes and their payload content. In broad terms, the list.*
events are Committed in most of their content and semantics while
events of other classes are generally Uncommitted with a few excep‐
tions.
All protocol events include an identifying class string, with the hier‐
archies defined in the protocol document and individual events regis‐
tered in the Events Registry. The libfmevent mechanism will permit sub‐
scription to events with Category 1 class of "list" and "swevent", that
is, to classes matching patterns "list.*" and "swevent.*".
All protocol events consist of a number of (name, datatype, value) tu‐
ples ("nvpairs"). Depending on the event class various nvpairs are re‐
quired and have well-defined meanings. In Solaris fmd protocol events
are represented as name-value lists using the libnvpair(3LIB) inter‐
faces.
API Overview
The API is simple to use in the common case (see Examples), but pro‐
vides substantial control to cater for more-complex scenarios.
We obtain an opaque subscription handle using fmev_shdl_init(), quoting
the ABI version and optionally nominating alloc(), zalloc() and free()
functions (the defaults use the umem family). More than one handle may
be opened if desired. Each handle opened establishes a communication
channel with fmd, the implementation of which is opaque to the
libfmevent mechanism.
On a handle we may establish one or more subscriptions using
fmev_shdl_subscribe(). Events of interest are specified using a simple
wildcarded pattern which is matched against the event class of incoming
events. For each match that is made a callback is performed to a func‐
tion we associate with the subscription, passing a nominated cookie to
that function. Subscriptions may be dropped using fmev_shdl_unsub‐
scribe() quoting exactly the same class or class pattern as was used to
establish the subscription.
Each call to fmev_shdl_subscribe() creates a single thread dedicated to
serving callback requests arising from this subscription.
An event callback handler has as arguments an opaque event handle, the
event class, the event nvlist, and the cookie it was registered with in
fmev_shdl_subscribe(). The timestamp for when the event was generated
(not when it was received) is available as a struct timespec with
fmev_timespec(), or more directly with fmev_time_sec() and
fmev_time_nsec(); an event handle and struct tm can also be passed to
fmev_localtime() to fill the struct tm. A high-resolution timestamp for
an event may be retrieved using fmev_hrtime(); this value has the se‐
mantics described in gethrtime(3C).
The event handle, class string pointer, and nvlist_t pointer passed as
arguments to a callback are valid for the duration of the callback. If
the application wants to continue to process the event beyond the dura‐
tion of the callback then it can hold the event with fmev_hold(), and
later release it with fmev_rele(). When the reference count drops to
zero the event is freed.
Error Handling
In <libfmevent.h> an enumeration fmev_err_t of error types is defined.
To render an error message string from an fmev_err_t use fmev_str‐
error(). An fmev_errno is defined which returns the error number for
the last failed libfmevent API call made by the current thread. You may
not assign to fmev_errno.
If a function returns type fmev_err_t, then success is indicated by
FMEV_SUCCESS (or FMEV_OK as an alias); on failure a FMEVERR_* value is
returned (see <fm/libfmevent.h>).
If a function returns a pointer type then failure is indicated by a
NULL return, and fmev_errno will record the error type.
Subscription Handles
A subscription handle is required in order to establish and manage sub‐
scriptions. This handle represents the abstract communication mechanism
between the application and the fault management daemon running in the
current zone.
A subscription handle is represented by the opaque fmev_shdl_t
datatype. A handle is initialized with fmev_shdl_init() and quoted to
subsequent API members.
To simplify usage of the API, subscription attributes for all subscrip‐
tions established on a handle are a property of the handle itself ;
they cannot be varied per-subscription. In such use cases multiple han‐
dles will need to be used.
libfmevent ABI version
The first argument to fmev_shdl_init() indicates the libfmevent ABI
version with which the handle is being opened. Specify either
LIBFMEVENT_VERSION_LATEST to indicate the most recent version available
at compile time or LIBFMEVENT_VERSION_1 (_2, etc. as the interface
evolves) for an explicit choice.
Interfaces present in an earlier version of the interface will continue
to be present with the same or compatible semantics in all subsequent
versions. When additional interfaces and functionality are introduced
the ABI version will be incremented. When an ABI version is chosen in
fmev_shdl_init(), only interfaces introduced in or before that version
will be available to the application via that handle. Attempts to use
later API members will fail with FMEVERR_VERSION_MISMATCH.
This manual page describes LIBFMEVENT_VERSION_1.
Privileges
The libfmevent API is not least-privilege aware; you need to have all
privileges to call fmev_shdl_init(). Once a handle has been initialized
with fmev_shdl_init() a process can drop privileges down to the basic
set and continue to use fmev_shdl_subscribe() and other libfmevent in‐
terfaces on that handle.
Underlying Event Transport
The implementation of the event transport by which events are published
from the fault manager and multiplexed out to libfmevent consumers is
strictly private. It is subject to change at any time, and you should
not encode any dependency on the underlying mechanism into your appli‐
cation. Use only the API described on this manual page and in
<libfmevent.h>.
The underlying transport mechanism is guaranteed to have the property
that a subscriber may attach to it even before the fault manager is
running. If the fault manager starts first then any events published
before the first consumer subscribes will wait in the transport until a
consumer appears.
The underlying transport will also have some maximum depth to the queue
of events pending delivery. This may be hit if there are no consumers,
or if consumers are not processing events quickly enough. In practice
the rate of events is small. When this maximum depth is reached addi‐
tional events will be dropped.
The underlying transport has no concept of priority delivery; all
events are treated equally.
Subscription Handle Initialization
Obtain a new subscription handle with fmev_shdl_init(). The first argu‐
ment is the libfmevent ABI version to be used (see above). The remain‐
ing three arguments should be all NULL to leave the library to use its
default allocator functions (the libumem family), or all non-NULL to
appoint wrappers to custom allocation functions if required.
FMEVERR_VERSION_MISMATCH
The library does not support the version requested.
FMEVERR_ALLOC
An error occurred in trying to allocate data structures.
FMEVERR_API
The alloc(), zalloc(), or free() arguments must either be all NULL
or all non-NULL.
FMEVERR_NOPRIV
Insufficient privilege to perform operation. In version 1 root
privilege is required.
FMEVERR_INTERNAL
Internal library error.
Fault Manager Authority Information
Once a subscription handle has been initialized, authority information
for the fault manager to which the client is connected may be retrieved
with fmev_shdl_getauthority(). The caller is responsible for freeing
the returned nvlist using nvlist_free(3NVPAIR).
Subscription Handle Finalization
Close a subscription handle with fmev_shdl_fini(). This call must not
be performed from within the context of an event callback handler, else
it will fail with FMEVERR_API.
The fmev_shdl_fini() call will remove all active subscriptions on the
handle and free resources used in managing the handle.
FMEVERR_API
May not be called from event delivery context for a subscription on
the same handle.
Subscribing To Events
To establish a new subscription on a handle, use fmev_shdl_subscribe().
Besides the handle argument you provide the class or class pattern to
subscribe to (the latter permitting simple wildcarding using '*'), a
callback function pointer for a function to be called for all matching
events, and a cookie to pass to that callback function.
The class pattern must match events per the fault management protocol
specification, such as "list.suspect" or "list.*". Patterns that do not
map onto existing events will not be rejected - they just won't result
in any callbacks.
A callback function has type fmev_cbfunc_t. The first argument is an
opaque event handle for use in event access functions described below.
The second argument is the event class string, and the third argument
is the event nvlist; these could be retrieved using fmev_class() and
fmev_attr_list() on the event handle, but they are supplied as argu‐
ments for convenience. The final argument is the cookie requested when
the subscription was established in fmev_shdl_subscribe().
Each call to fmev_shdl_subscribe() opens a new door into the process
that the kernel uses for event delivery. Each subscription therefore
uses one file descriptor in the process.
See below for more detail on event callback context.
FMEVERR_API
Class pattern is NULL or callback function is NULL.
FMEVERR_BADCLASS
Class pattern is the empty string, or exceeds the maximum length of
FMEV_MAX_CLASS.
FMEVERR_ALLOC
An attempt to fmev_shdl_zalloc() additional memory failed.
FMEVERR_DUPLICATE
Duplicate subscription request. Only one subscription for a given
class pattern may exist on a handle.
FMEVERR_MAX_SUBSCRIBERS
A system-imposed limit on the maximum number of subscribers to the
underlying transport mechanism has been reached.
FMEVERR_INTERNAL
An unknown error occurred in trying to establish the subscription.
Unsubscribing
An unsubscribe request using fmev_shdl_unsubscribe() must exactly match
a previous subscription request or it will fail with FMEVERR_NOMATCH.
The request stops further callbacks for this subscription, waits for
any existing active callbacks to complete, and drops the subscription.
Do not call fmev_shdl_unsubscribe from event callback context, else it
will fail with FMEVERR_API.
FMEVERR_API
A NULL pattern was specified, or the call was attempted from call‐
back context.
FMEVERR_NOMATCH
The pattern provided does not match any open subscription. The pat‐
tern must be an exact match.
FMEVERR_BADCLASS
The class pattern is the empty string or exceeds FMEV_MAX_CLASS.
Event Callback Context
Event callback context is defined as the duration of a callback event,
from the moment we enter the registered callback function to the moment
it returns. There are a few restrictions on actions that may be per‐
formed from callback context:
o You can perform long-running actions, but this thread will
not be available to service other event deliveries until you
return.
o You must not cause the current thread to exit.
o You must not call either fmev_shdl_unsubscribe() or
fmev_shdl_fini() for the subscription handle on which this
callback has been made.
o You can invoke fork(), popen(), etc.
Event Handles
A callback receives an fmev_t as a handle on the associated event. The
callback may use the access functions described below to retrieve vari‐
ous event attributes.
By default, an event handle fmev_t is valid for the duration of the
callback context. You cannot access the event outside of callback con‐
text.
If you need to continue to work with an event beyond the initial call‐
back context in which it is received, you may place a "hold" on the
event with fmev_hold(). When finished with the event, release it with
fmev_rele(). These calls increment and decrement a reference count on
the event; when it drops to zero the event is freed. On initial entry
to a callback the reference count is 1, and this is always decremented
when the callback returns.
An alternative to fmev_hold() is fmev_dup(), which duplicates the event
and returns a new event handle with a reference count of 1. When
fmev_rele() is applied to the new handle and reduces the reference
count to 0, the event is freed. The advantage of fmev_dup() is that it
allocates new memory to hold the event rather than continuing to hold a
buffer provided by the underlying delivery mechanism. If your operation
is going to be long-running, you may want to use fmev_dup() to avoid
starving the underlying mechanism of event buffers.
Given an fmev_t, a callback function can use fmev_ev2shdl() to retrieve
the subscription handle on which the subscription was made that re‐
sulted in this event delivery.
The fmev_hold() and fmev_rele() functions always succeed.
The fmev_dup() function may fail and return NULL with fmev_errno of:
FMEVERR_API A NULL event handle was passed.
FMEVERR_ALLOC The fmev_shdl_alloc() call failed.
Event Class
A delivery callback already receives the event class as an argument, so
fmev_class() will only be of use outside of callback context (that is,
for an event that was held or duped in callback context and is now be‐
ing processed in an asynchronous handler). This is a convenience func‐
tion that returns the same result as accessing the event attributes
with fmev_attr_list() and using nvlist_lookup_string(3NVPAIR) to lookup
a string member of name "class".
The string returned by fmev_class() is valid for as long as the event
handle itself.
The fmev_class() function may fail and return NULL with fmev_errno of:
FMEVERR_API A NULL event handle was passed.
FMEVERR_MALFORMED_EVENT The event appears corrupted.
Event Attribute List
All events are defined as a series of (name, type) pairs. An instance
of an event is therefore a series of tuples (name, type, value). Al‐
lowed types are defined in the protocol specification. In Solaris, and
in libfmevent, an event is represented as an nvlist_t using the libn‐
vpair(3LIB) library.
The nvlist of event attributes can be accessed using fmev_attr_list().
The resulting nvlist_t pointer is valid for the same duration as the
underlying event handle. Do not use nvlist_free() to free the nvlist.
You may then lookup members, iterate over members, and so on using the
libnvpair interfaces.
The fmev_attr_list() function may fail and return NULL with fmev_errno
of:
FMEVERR_API A NULL event handle was passed.
FMEVERR_MALFORMED_EVENT The event appears corrupted.
Event Timestamp
These functions refer to the time at which the event was originally
produced, not the time at which it was forwarded to libfmevent or de‐
livered to the callback.
Use fmev_timespec() to fill a struct timespec with the event time in
seconds since the Epoch (tv_sec, signed integer) and nanoseconds past
that second (tv_nsec, a signed long). This call can fail and return
FMEVERR_OVERFLOW if the seconds value will not fit in a signed 32-bit
integer (as used in struct timespec tv_sec).
You can use fmev_time_sec() and fmev_time_nsec() to retrieve the same
second and nanosecond values as uint64_t quantities.
The fmev_localtime function takes an event handle and a struct tm
pointer and fills that structure according to the timestamp. The result
is suitable for use with strftime(3C). This call will return NULL and
fmev_errno of FMEVERR_OVERFLOW under the same conditions as above.
FMEVERR_OVERFLOW The fmev_timespec() function cannot fit the seconds
value into the signed long integer tv_sec member of
a struct timespec.
String Functions
A string can be duplicated using fmev_shdl_strdup(); this will allocate
memory for the copy using the allocator nominated in fmev_shdl_init().
The caller is responsible for freeing the buffer using fmev_shdl_str‐
free(); the caller can modify the duplicated string but must not change
the string length.
An FMRI retrieved from a received event as an nvlist_t may be rendered
as a string using fmev_shdl_nvl2str(). The nvlist must be a legal FMRI
(recognized class, version and payload), or NULL is returned with
fmev_errno() of FMEVERR_INVALIDARG. The formatted string is rendered
into a buffer allocated using the memory allocation functions nominated
in fmev_shdl_init(), and the caller is responsible for freeing that
buffer using fmev_shdl_strfree().
Memory Allocation
The fmev_shdl_alloc(), fmev_shdl_zalloc(), and fmev_shdl_free() func‐
tions allocate and free memory using the choices made for the given
handle when it was initialized, typically the libumem(3LIB) family if
all were specified NULL.
Subscription Handle Control
The fmev_shdlctl_*() interfaces offer control over various properties
of the subscription handle, allowing fine-tuning for particular appli‐
cations. In the common case the default handle properties will suffice.
These properties apply to the handle and uniformly to all subscriptions
made on that handle. The properties may only be changed when there are
no subscriptions in place on the handle, otherwise FMEVERR_BUSY is re‐
turned.
Event delivery is performed through invocations of a private door. A
new door is opened for each fmev_shdl_subscribe() call. These invoca‐
tions occur in the context of a single private thread associated with
the door for a subscription. Many of the fmev_shdlctl_*() interfaces
are concerned with controlling various aspects of this delivery thread.
If you have applied fmev_shdlctl_thrcreate(), "custom thread creation
semantics" apply on the handle; otherwise "default thread creation se‐
mantics" are in force. Some fmev_shdlctl_*() interfaces apply only to
default thread creation semantics.
The fmev_shdlctl_serialize() control requests that all deliveries on a
handle, regardless of which subscription request they are for, be seri‐
alized - no concurrent deliveries on this handle. Without this control
applied deliveries arising from each subscription established with
fmev_shdl_subscribe() are individually single-threaded, but if multiple
subscriptions have been established then deliveries arising from sepa‐
rate subscriptions may be concurrent. This control applies to both cus‐
tom and default thread creation semantics.
The fmev_shdlctl_thrattr() control applies only to default thread cre‐
ation semantics. Threads that are created to service subscriptions will
be created with pthread_create(3C) using the pthread_attr_t provided by
this interface. The attribute structure is not copied and so must per‐
sist for as long as it is in force on the handle.
The default thread attributes are also the minimum requirement: threads
must be created PTHREAD_CREATE_DETACHED and PTHREAD_SCOPE_SYSTEM. A
NULL pointer for the pthread_attr_t will reinstate these default at‐
tributes.
The fmev_shdlctl_sigmask() control applies only to default thread cre‐
ation semantics. Threads that are created to service subscriptions will
be created with the requested signal set masked - a pthread_sigmask(3C)
request to SIG_SETMASK to this mask prior to pthread_create(). The de‐
fault is to mask all signals except SIGABRT.
See door_xcreate(3C) for a detailed description of thread setup and
creation functions for door server threads.
The fmev_shdlctl_thrsetup() function runs in the context of the newly-
created thread before it binds to the door created to service the sub‐
scription. It is therefore a suitable place to perform any thread-spe‐
cific operations the application may require. This control applies to
both custom and default thread creation semantics.
Using fmev_shdlctl_thrcreate() forfeits the default thread creation se‐
mantics described above. The function appointed is responsible for all
of the tasks required of a door_xcreate_server_func_t in door_xcre‐
ate().
The fmev_shdlctl_*() functions may fail and return NULL with fmev_errno
of:
FMEVERR_BUSY Subscriptions are in place on this handle.
EXAMPLES
Example 1 Subscription example
The following example subscribes to list.suspect events and prints out
a simple message for each one that is received. It foregoes most error
checking for the sake of clarity.
#include <fm/libfmevent.h>
#include <libnvpair.h>
/*
* Callback to receive list.suspect events
*/
void
mycb(fmev_t ev, const char *class, nvlist_t *attr, void *cookie)
{
struct tm tm;
char buf[64];
char *evcode;
if (strcmp(class, "list.suspect") != 0)
return; /* only happens if this code has a bug! */
(void) strftime(buf, sizeof (buf), NULL,
fmev_localtime(ev, &tm));
(void) nvlist_lookup_string(attr, "code", &evcode);
(void) fprintf(stderr, "Event class %s published at %s, "
"event code %s\n", class, buf, evcode);
}
int
main(int argc, char *argv[])
{
fmev_shdl_t hdl;
sigset_t set;
hdl = fmev_shdl_init(LIBFMEVENT_VERSION_LATEST,
NULL, NULL, NULL);
(void) fmev_shdl_subscribe(hdl, "list.suspect", mycb, NULL);
/* Wait here until signalled with SIGTERM to finish */
(void) sigemptyset(&set);
(void) sigaddset(&set, SIGTERM);
(void) sigwait(&set);
/* fmev_shdl_fini would do this for us if we skipped it */
(void) fmev_shdl_unsubscribe(hdl, "list.suspect");
(void) fmev_shdl_fini(hdl);
return (0);
}
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Architectureall _ Interface StabilityCommitted _ MT-
LevelSafe
SEE ALSO
door_xcreate(3C), gethrtime(3C), pthread_create(3C), pthread_sig‐
mask(3C), strftime(3C), libnvpair(3LIB), libumem(3LIB),
nvlist_lookup_string(3NVPAIR), attributes(7), privileges(7)
Oracle Solaris 11.4 6 Jul 2012 fmev_..._init(3FM)