System Calls                                             alarm(2)

NAME
     alarm - set a process alarm clock

SYNOPSIS
     #include <unistd.h>

     unsigned int alarm(unsigned int sec);

DESCRIPTION
     The alarm() function instructs the alarm clock of  the  cal-
     ling  process to send the signal SIGALRM to the calling pro-
     cess after the number of real time seconds specified by  sec
     have elapsed (see  signal(3C)).

     Alarm requests are not stacked; successive calls  reset  the
     alarm clock of the calling process.

     If sec is 0, any previously made alarm request is canceled.

     The fork(2) function sets the alarm clock of a  new  process
     to  0.  A  process  created  by  the exec family of routines
     inherits the time left on the old process's alarm clock.

     Calling alarm()  in  a  multithreaded  process  linked  with
     -lthread  (Solaris  threads)  and  not with -lpthread (POSIX
     threads) currently behaves in the following fashion:

        o  if the calling thread is a bound thread, the resulting
           SIGALRM  is  delivered to the bound thread's LWP, i.e.
           to the calling thread. There is a bug  currently  that
           this  signal  is not maskable via thr_sigsetmask(3THR)
           on this bound thread.

        o  if the  calling  thread  is  an  unbound  thread,  the
           resulting  SIGALRM  is  sent  to  the LWP on which the
           thread was running when it issued the call to alarm().
           This  is  neither  a  per-process semantic, nor a per-
           thread semantic, since the LWP  could  change  threads
           after  the  call  to  alarm()  but  before the SIGALRM
           delivery, causing some other thread to get  it  possi-
           bly. Hence this is basically a bug.

     The above documents current behavior and the  bugs  are  not
     going  to be fixed since the above semantics are going to be
     discontinued in the next release.

     The semantic for Solaris  threads  will  move  to  the  per-
     process  semantic  specified  by POSIX (see standards(5)) at
     this future date.  New applications should not  rely on  the
     per-thread  semantic  of  alarm(),  since this semantic will
     become obsolete.

SunOS 5.8           Last change: 28 Dec 1996                    1

System Calls                                             alarm(2)

     In a process linked with -lpthread (whether  or  not  it  is
     also  linked  with  -lthread),  the semantics of alarm() are
     per-process; the resulting SIGALRM is sent to  the  process,
     and  not  necessarily  to  the calling thread. This semantic
     will be supported in the future.

     This  semantic  is  obtainable  by   simply   linking   with
     -lpthread. One can continue to use Solaris thread interfaces
     by linking with both -lpthread and -lthread.

RETURN VALUES
     The alarm() function returns the amount of  time  previously
     remaining in the alarm clock of the calling process.

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Async-Signal-Safe           |
    |_____________________________|_____________________________|

SEE ALSO
     exec(2),        fork(2),        pause(2),        signal(3C),
     thr_sigsetmask(3THR), attributes(5), standards(5)

SunOS 5.8           Last change: 28 Dec 1996                    2