FreeBSD/Linux Kernel Cross Reference
sys/man/timer_arm.man

      .\" 
     .\" Mach Operating System
     .\" Copyright (c) 1993 Carnegie Mellon University
     .\" All Rights Reserved.
     .\" 
     .\" Permission to use, copy, modify and distribute this software and its
     .\" documentation is hereby granted, provided that both the copyright
     .\" notice and this permission notice appear in all copies of the
     .\" software, derivative works or modified versions, and any portions
    .\" thereof, and that both notices appear in supporting documentation.
    .\" 
    .\" CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS IS"
    .\" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF ANY KIND FOR
    .\" ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF THIS SOFTWARE.
    .\" 
    .\" Carnegie Mellon requests users of this software to return to
    .\" 
    .\"  Software Distribution Coordinator  or  Software.Distribution@CS.CMU.EDU
    .\"  School of Computer Science
    .\"  Carnegie Mellon University
    .\"  Pittsburgh PA 15213-3890
    .\" 
    .\" any improvements or extensions that they make and grant Carnegie Mellon
    .\" the rights to redistribute these changes.
    .\" 
    .\" 
    .\" HISTORY
    .\" $Log:       timer_arm.man,v $
    .\" Revision 2.2  93/12/07  14:00:44  dbg
    .\"     Created.
    .\" 
    .\" 
    .TH timer_arm 2 9/22/93
    .CM 4
    .SH NAME
    .nf
    timer_arm  \-  arm a timer to expire
    .SH SYNOPSIS
    .nf
    .ft B
    #include <mach.h>
    
    .nf
    .ft B
    kern_return_t
    timer_arm(
            mach_timer_t    timer,
            time_spec_t     expire_time,
            time_spec_t     interval_time,
            mach_port_t     expire_port,
            thread_t        thread,
            int             flags);
    
    
    .fi
    .ft P
    .SH ARGUMENTS
    .TP 15
    .B
    timer
    The timer to arm.
    .TP 15
    .B expire_time
    The time at which the timer will expire, measured
    against
    .B timer's
    clock.
    .TP 15
    .B interval_time
    The interval at which the timer will again expire,
    if the timer is set to expire periodically.
    .TP 15
    .B expire_port
    A send right to a port to which the timer expiration
    message will be sent.
    .TP 15
    .B thread
    A thread to suspend when the timer expires, or
    THREAD_NULL if none.
    .TP 15
    .B flags
    Options for the expiration time and the action
    to be taken.
    
    
    .SH DESCRIPTION
    .B timer_arm
    sets a timer to expire at a particular time, and,
    optionally, to expire at periodic intervals after
    that time.  The expiration time may be specified
    as absolute, if
    .B TIMER_ABSOLUTE
    is set in
    .B flags;
    otherwise, the expiration time is relative to
    the current time (of
    .B timer's
    clock).  If
    .B TIMER_PERIODIC
   is set in
   .B flags,
   the timer will expire at
   .B expire_time,
   and at every
   .B interval_time
   interval afterwards.
   
   When the timer expires, a
   .B timer_expire
   message is sent to
   .B expire_port.
   The message contains the absolute time at which
   the timer expired.  If the timer is periodic,
   the message will be sent at the end of every
   period.  However, if
   .B expire_port
   is full (its message queue exceeds its queue limit),
   the message will not be sent.  Instead, the timer's
   .B overrun count
   will be incremented.  At the next timer expiration
   when the message can successfully be sent, the
   overrun count will be added to the timer expiration
   message, and the timer's overrun count will be reset
   to zero.
   
   If
   .B TIMER_THREAD_SUSPEND
   is set in
   .B flags,
   the specified thread will be suspended when the timer expires.
   If the thread is blocked in an uninterruptible wait within
   the Mach kernel, it is not guaranteed to be completely suspended
   by the time the timer_expire message is delivered.  The receiver
   of the message can issue a thread_get_state call to ensure that
   the suspension is complete.  The suspended thread can be
   resumed with the thread_resume call.
   
   If the timer is set to be periodic, the thread will be suspended
   again at the end of each period (unless the current interval is
   canceled with
   .B timer_cancel).  Thread_resume must be called as many times
   as the thread was suspended to make the thread run again.
   
   .SH DIAGNOSTICS
   .TP 25
   KERN_SUCCESS
   Operation completed successfully
   .TP 25
   KERN_INVALID_ARGUMENT
   .B timer
   is not a timer, or
   .B expire_time
   or
   .B interval_time
   is not a valid time specification, or
   .B interval_time
   is less than the resolution of
   .B timer's
   clock, or
   .B expire_port
   is not a valid port, or
   .B thread
   is not a valid thread.
   
   .TP 25
   KERN_FAILURE
   .B timer
   is currently armed.
   
   .SH BUGS
   
   .SH SEE ALSO
   .B timer_create, timer_terminate, timer_sleep, timer_cancel.
   

Cache object: 600bf30406cfce975e024cedf617c50d