sigevent(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
SIGEVENT(3)             NetBSD Library Functions Manual            SIGEVENT(3)


NAME

     sigevent -- signal event structure


SYNOPSIS

     #include <sys/signal.h>


DESCRIPTION

     The IEEE Std 1003.1-2004 (``POSIX.1'') standard extends traditional UNIX
     signal semantics by providing facilities for realtime signal generation
     and delivery.

     Please note that this manual describes an interface that is not yet fully
     functional in NetBSD: neither realtime signals nor SIGEV_THREAD are cur-
     rently supported.

     Realtime functions that can generate realtime signals include:

        1.   Completion of asynchronous I/O; see aio(3).

        2.   Expiration of per-process timers; see timer_create(2).

        3.   Arrival of a message to an empty message queue; see mq_notify(3).

     The <sys/signal.h> header, included by <signal.h>, defines a sigevent
     structure, which is the cornerstone in asynchronous delivery of realtime
     signals.  This structure is defined as:

           struct sigevent {
                   int               sigev_notify;
                   int               sigev_signo;
                   union sigval      sigev_value;
                   void            (*sigev_notify_function)(union sigval);
                   void             *sigev_notify_attributes;
           };

     The included union is further defined in <siginfo.h> as:

           typedef union sigval {
                   int      sival_int;
                   void    *sival_ptr;
           } sigval_t;

     The sigev_notify integer defines the action taken when a notification
     such as timer expiration occurs.  The possiblue values are:

       SIGEV_NONE     This constant specifies a ``null'' handler: when a noti-
                      fication arrives, nothing happens.

       SIGEV_SIGNAL   The SIGEV_SIGNAL constant specifies that notifications
                      are delivered by signals.  When a notification arrives,
                      the kernel sends the signal specified in sigev_signo.

                      In the signal handler the `si_value' of siginfo_t is set
                      to the value specified by the sigev_value.  In another
                      words, the sigev_value member is an application-defined
                      value to be passed to a particular signal handler at the
                      time of signal delivery.  Depending whether the speci-
                      fied value is an integer or a pointer, the delivered
                      value can be either sigval_intr or sigval_ptr.

       SIGEV_THREAD   This constant specifies a thread-driven notification
                      mechanism.  When a notification occurs, the kernel cre-
                      ates a new thread that starts executing the function
                      specified in the function pointer sigev_notify_function.
                      The single argument passed to the function is specified
                      in sigev_value.

                      If sigev_notify_attributes is not NULL, the provided
                      attribute specifies the behavior of the thread; see
                      pthread_attr(3).  (Note that although a pointer to void
                      is specified for sigev_notify_attributes, the type is
                      pthread_attr_t in practice.)

                      The threads are created as detached, or in an unspeci-
                      fied way if pthread_attr_setdetachstate(3) is used with
                      sigev_notify_attributes to set PTHREAD_CREATE_JOINABLE.
                      It is not valid to call pthread_join(3) in either case.
                      Hence, it is impossible to determine the lifetime of the
                      created thread.  This in turn means that it is neither
                      possible to recover the memory nor the address of the
                      memory possibly dedicated as thread stack via
                      pthread_attr_setstack() or pthread_attr_setstackaddr().


SEE ALSO

     siginfo(2), timer_create(2), aio(3), mq(3)


HISTORY

     The sigevent structure first appeared in NetBSD 1.6.

NetBSD 6.1.2                     June 24, 2010                    NetBSD 6.1.2