Source Code 1994 March/Source_Code_CD-ROM_Walnut_Creek_March_1994.iso/compsrcs/unix/volume27/clc/part15

Text File | 1993-11-28 | 29.0 KB | 897 lines

Newsgroups: comp.sources.unix
From: [e-mail] (Panos Tsirigotis)
Subject: v27i121: clc - C Libraries Collection, Part15/20
References: <[e-mail]>
Sender: [e-mail]
Approved: [e-mail]

Submitted-By: [e-mail] (Panos Tsirigotis)
Posting-Number: Volume 27, Issue 121
Archive-Name: clc/part15

#! /bin/sh
# This is a shell archive.  Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file".  To overwrite existing
# files, type "sh file -c".  You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g..  If this archive is complete, you
# will see the following message at the end:
#        "End of archive 15 (of 20)."
# Contents:  libs/src/dict/dll.c libs/src/timer/STATES
#   libs/src/timer/timer.3
# Wrapped by panos@eclipse on Sun Nov 28 14:48:17 1993
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'libs/src/dict/dll.c' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'libs/src/dict/dll.c'\"
else
echo shar: Extracting \"'libs/src/dict/dll.c'\" \(8638 characters\)
sed "s/^X//" >'libs/src/dict/dll.c' <<'END_OF_FILE'
X/*
X * (c) Copyright 1993 by Panagiotis Tsirigotis
X * All rights reserved.  The file named COPYRIGHT specifies the terms
X * and conditions for redistribution.
X */
X
Xstatic char RCSid[] = "$Id: dll.c,v 3.3 93/09/28 21:07:56 panos Exp $" ;
X
X#include "dllimpl.h"
X
X
Xdict_h dll_create( oo_comp, ko_comp, flags, errnop )
X    dict_function    oo_comp ;                    /* object-object comparator */
X    dict_function    ko_comp ;                    /* key-object comparator */
X    int                flags ;
X    int                *errnop ;
X{
X    header_s            *hp ;
X    char                *id = "dll_create" ;
X
X    if ( ! __dict_args_ok( id,
X                flags, errnop, oo_comp, ko_comp, DICT_ORDERED + DICT_UNORDERED ) )
X        return( NULL_HANDLE ) ;
X
X    hp = (header_s *) malloc( sizeof( header_s ) ) ;
X    if ( hp == NULL )
X        return( __dict_create_error( id, flags, errnop, DICT_ENOMEM ) ) ;
X
X    /*
X     * Create an allocator
X     */
X    hp->alloc = fsm_create( sizeof( node_s ), 0,
X                ( flags & DICT_RETURN_ERROR ) ? FSM_RETURN_ERROR : FSM_NOFLAGS ) ;
X    if ( hp->alloc == NULL )
X    {
X        free( (char *)hp ) ;
X        return( __dict_create_error( id, flags, errnop, DICT_ENOMEM ) ) ;
X    }
X
X    /*
X     * Allocate and initialize head node
X     */
X    hp->head = (node_s *) fsm_alloc( hp->alloc ) ;
X    if ( hp->head == NULL )
X    {
X        fsm_destroy( hp->alloc ) ;
X        free( (char *)hp ) ;
X        return( __dict_create_error( id, flags, errnop, DICT_ENOMEM ) ) ;
X    }
X
X    NEXT( hp->head ) = PREV( hp->head ) = hp->head ;
X    OBJ( hp->head ) = NULL ;
X
X    /*
X     * Initialize dictionary header, hints
X     */
X    __dict_init_header( DHP( hp ), oo_comp, ko_comp, flags, errnop ) ;
X    HINT_CLEAR( hp, last_search ) ;
X    HINT_CLEAR( hp, last_successor ) ;
X    HINT_CLEAR( hp, last_predecessor ) ;
X
X    return( (dict_h) hp ) ;
X}
X
X
Xvoid dll_destroy( handle )
X    dict_h        handle ;
X{
X    header_s        *hp = LHP( handle ) ;
X
X    fsm_destroy( hp->alloc ) ;
X    free( (char *)hp ) ;
X}
X
X
X
XPRIVATE int dll_do_insert( hp, must_be_uniq, object, objectp )
X    register header_s        *hp ;
X    bool_int                    must_be_uniq ;
X    register dict_obj        object ;
X    dict_obj                    *objectp ;
X{
X    register dheader_s    *dhp                = DHP( hp ) ;
X    register bool_int     unordered_list = ( dhp->flags & DICT_UNORDERED ) ;
X    register node_s        *np ;
X    node_s                    *new ;
X    node_s                    *before, *after ;
X    char                        *id = "dll_do_insert" ;
X
X    if ( object == NULL )
X        HANDLE_ERROR( dhp, id, DICT_ENULLOBJECT, DICT_ERR ) ;
X
X    if ( unordered_list && ! must_be_uniq )
X        np = NEXT( hp->head ) ;
X    else
X    {
X        /*
X         * Find node n such that key(OBJ(n)) >= key(object)
X         */
X        for ( np = NEXT( hp->head ) ; np != hp->head ; np = NEXT( np ) )
X        {
X            register int v = (*dhp->oo_comp)( OBJ( np ), object ) ;
X
X            if ( v > 0 && ! unordered_list )
X                break ;
X            if ( v == 0 )
X                if ( must_be_uniq )
X                {
X                    if ( objectp != NULL )
X                        *objectp = OBJ( np ) ;
X                    ERRNO( dhp ) = DICT_EEXISTS ;
X                    return( DICT_ERR ) ;
X                }
X                else
X                    break ;
X        }
X    }
X
X    new = (node_s *) fsm_alloc( hp->alloc ) ;
X    if ( new == NULL )
X        HANDLE_ERROR( dhp, id, DICT_ENOMEM, DICT_ERR ) ;
X
X    /*
X     * The new node is inserted BEFORE np
X     */
X    before = PREV( np ) ;
X    after = np ;
X    NEXT( new ) = after ;
X    PREV( new ) = before ;
X    NEXT( before ) = new ;
X    PREV( after ) = new ;
X    OBJ( new ) = object ;
X    if ( objectp != NULL )
X        *objectp = object ;
X    return( DICT_OK ) ;
X}
X
X
Xint dll_insert( handle, object )
X    dict_h        handle ;
X    dict_obj        object ;
X{
X    header_s        *hp = LHP( handle ) ;
X
X    return( dll_do_insert( hp, hp->dh.flags & DICT_UNIQUE_KEYS,
X                    object, (dict_obj *)NULL ) ) ;
X}
X
X
X
Xint dll_insert_uniq( handle, object, objectp )
X    dict_h        handle ;
X    dict_obj        object ;
X    dict_obj        *objectp ;
X{
X    header_s        *hp    = LHP( handle ) ;
X    dheader_s    *dhp    = DHP( hp ) ;
X
X    if ( dhp->oo_comp == NULL_FUNC )
X        HANDLE_ERROR( dhp, "dll_insert_uniq", DICT_ENOOOCOMP, DICT_ERR ) ;
X    return( dll_do_insert( hp, TRUE, object, objectp ) ) ;
X}
X
X
Xint dll_delete( handle, object )
X    dict_h                handle ;
X    register dict_obj object ;
X{
X    register header_s *hp    = LHP( handle ) ;
X    dheader_s            *dhp    = DHP( hp ) ;
X    register node_s    *np ;
X    node_s                *after, *before ;
X
X    if ( object == NULL )
X        HANDLE_ERROR( dhp, "dll_delete", DICT_ENULLOBJECT, DICT_ERR ) ;
X
X    if ( OBJ( hp->hint.last_search ) == object )
X        np = hp->hint.last_search ;
X    else
X        for ( np = NEXT( hp->head ) ;; np = NEXT( np ) )
X            if ( np == hp->head )
X            {
X                ERRNO( dhp ) = DICT_ENOTFOUND ;
X                return( DICT_ERR ) ;
X            }
X            else if ( object == OBJ( np ) )
X                break ;
X
X    /*
X     * First disconnect, then release
X     */
X    after = NEXT( np ) ;
X    before = PREV( np ) ;
X    NEXT( before ) = after ;
X    PREV( after ) = before ;
X    OBJ( np ) = NULL ;
X    fsm_free( hp->alloc, (char *)np ) ;
X
X    /*
X     * Clear all hints
X     */
X    HINT_CLEAR( hp, last_search ) ;
X    HINT_CLEAR( hp, last_successor ) ;
X    HINT_CLEAR( hp, last_predecessor ) ;
X
X    return( DICT_OK ) ;
X}
X
X
Xdict_obj dll_search( handle, key )
X    dict_h                    handle ;
X    register dict_key        key ;
X{
X    register header_s        *hp                = LHP( handle ) ;
X    register dheader_s    *dhp                = DHP( hp ) ;
X    register bool_int        unordered_list    = ( dhp->flags & DICT_UNORDERED ) ;
X    register node_s        *np ;
X
X    for ( np = NEXT( hp->head ) ; np != hp->head ; np = NEXT( np ) )
X    {
X        register int v = (*dhp->ko_comp)( key, OBJ( np ) ) ;
X
X        if ( v == 0 )
X        {
X            hp->hint.last_search = np ;        /* update search hint */
X            return( OBJ( np ) ) ;
X        }
X        else if ( v < 0 && ! unordered_list )
X            break ;
X    }
X    return( NULL_OBJ ) ;
X}
X
X
X/*
X * Returns a pointer to the object with the smallest key value or
X * NULL if the list is empty.
X *
X * NOTE: here we depend on the fact that OBJ( head ) == NULL
X */
Xdict_obj dll_minimum( handle )
X    dict_h        handle ;
X{
X    header_s        *hp = LHP( handle ) ;
X    node_s        *np = NEXT( hp->head ) ;
X
X    hp->hint.last_successor = np ;            /* update hint */
X    return( OBJ( np ) ) ;
X}
X
X
X/*
X * Returns a pointer to the object with the greatest key value or
X * NULL if the list is empty.
X *
X * NOTE: here we depend on the fact that OBJ( head ) == NULL
X */
Xdict_obj dll_maximum( handle )
X    dict_h        handle ;
X{
X    header_s        *hp = LHP( handle ) ;
X    node_s        *np = PREV( hp->head ) ;
X
X    hp->hint.last_predecessor = np ;            /* update hint */
X    return( OBJ( np ) ) ;
X}
X
X
X/*
X * Returns a pointer to the object with the next >= key value or
X * NULL if the list is empty or the given object is the last one on the
X * list.
X *
X * NOTE: here we depend on the fact that OBJ( head ) == NULL
X */
Xdict_obj dll_successor( handle, object )
X    dict_h                handle ;
X    register dict_obj object ;
X{
X    register header_s *hp    = LHP( handle ) ;
X    dheader_s            *dhp    = DHP( hp ) ;
X    register node_s    *np ;
X    node_s                *successor ;
X    char                    *id = "dll_successor" ;
X
X    if ( object == NULL )
X        HANDLE_ERROR( dhp, id, DICT_ENULLOBJECT, NULL_OBJ ) ;
X
X    if ( OBJ( hp->hint.last_successor ) == object )
X        successor = NEXT( hp->hint.last_successor ) ;
X    else
X    {
X        ERRNO( dhp ) = DICT_ENOERROR ;
X        for ( np = NEXT( hp->head ) ; np != hp->head ; np = NEXT( np ) )
X            if ( OBJ( np ) == object )
X                break ;
X        if ( np == hp->head )
X            HANDLE_ERROR( dhp, id, DICT_EBADOBJECT, NULL_OBJ ) ;
X        successor = NEXT( np ) ;
X    }
X    hp->hint.last_successor = successor ;
X    return( OBJ( successor ) ) ;
X}
X
X
X
X/*
X * Returns a pointer to the object with the next <= key value or
X * NULL if the list is empty or the given object is the first one on the
X * list.
X *
X * NOTE: here we depend on the fact that OBJ( head ) == NULL
X */
Xdict_obj dll_predecessor( handle, object )
X    dict_h                handle ;
X    register dict_obj object ;
X{
X    register header_s *hp    = LHP( handle ) ;
X    dheader_s            *dhp    = DHP( hp ) ;
X    node_s                *predecessor ;
X    register node_s    *np ;
X    char                    *id = "dll_predecessor" ;
X
X    if ( object == NULL )
X        HANDLE_ERROR( dhp, id, DICT_ENULLOBJECT, NULL_OBJ ) ;
X
X    if ( OBJ( hp->hint.last_predecessor ) == object )
X        predecessor = PREV( hp->hint.last_predecessor ) ;
X    else
X    {
X        ERRNO( dhp ) = DICT_ENOERROR ;
X        for ( np = PREV( hp->head ) ; np != hp->head ; np = PREV( np ) )
X            if ( OBJ( np ) == object )
X                break ;
X        if ( np == hp->head )
X            HANDLE_ERROR( dhp, id, DICT_EBADOBJECT, NULL_OBJ ) ;
X        predecessor = PREV( np ) ;
X    }
X    hp->hint.last_predecessor = predecessor ;
X    return( OBJ( predecessor ) ) ;
X}
X
X
Xvoid dll_iterate( handle, direction )
X    dict_h                    handle ;
X    enum dict_direction    direction ;
X{
X    register header_s        *hp    = LHP( handle ) ;
X    dheader_s                *dhp    = DHP( hp ) ;
X    struct dll_iterator    *dip    = &hp->iter ;
X
X    if ( dhp->flags & DICT_UNORDERED )
X        dip->direction = DICT_FROM_START ;
X    else
X        dip->direction = direction ;
X
X    if ( dip->direction == DICT_FROM_START )
X        dip->next = NEXT( hp->head ) ;
X    else
X        dip->next = PREV( hp->head ) ;
X}
X
X
Xdict_obj dll_nextobj( handle )
X    dict_h        handle ;
X{
X    struct dll_iterator    *dip        = &LHP( handle )->iter ;
X    node_s                    *current = dip->next ;
X
X    if ( dip->direction == DICT_FROM_START )
X        dip->next = NEXT( current ) ;
X    else
X        dip->next = PREV( current ) ;
X    return( OBJ( current ) ) ;
X}
X
END_OF_FILE
if test 8638 -ne `wc -c <'libs/src/dict/dll.c'`; then
    echo shar: \"'libs/src/dict/dll.c'\" unpacked with wrong size!
fi
# end of 'libs/src/dict/dll.c'
fi
if test -f 'libs/src/timer/STATES' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'libs/src/timer/STATES'\"
else
echo shar: Extracting \"'libs/src/timer/STATES'\" \(8393 characters\)
sed "s/^X//" >'libs/src/timer/STATES' <<'END_OF_FILE'
X
XThe following is a state table showing how the state of a timer changes
Xwhen various operations are applied to it.  The state is represented as
Xa triple: the first member shows the state of the "ticking" part of the
Xtimer, the second member shows if the timer is blocked  and the third
Xmember shows the state of the action associated with the timer.
X
XThe "ticking" state can be:
X   INACTIVE    :  the timer is not ticking
X   TICKING     :  the timer is ticking
X   DESTROYED   :  the timer has been destroyed
X
XThe "blocked" state can be TRUE or FALSE.
X
XThe action state can be:
X   IDLE        :  this is the original state (quiescent)
X    SCHEDULED:        the action is scheduled to be invoked
X   PENDING     :  the timer has expired but the action is pending because the
X                        the timer is blocked.
X   INVOKED     :  the action has been invoked (i.e. the user-specified function
X                  is running)
X
X
XThe operations that affect timers fall into 2 groups. In the first group
Xare the operations available by the library interface:
X
X   timer_start
X   timer_stop
X   timer_block
X   timer_unblock
X   timer_destroy
X
XIn the second group are internal operations:
X
X   INVOKE      :  invoke the function associated with the timer
X   RETURN      :  the function associated with the timer returns
X   INTERRUPT   :  the timer expired
X
XThe initial timer state is (INACTIVE,NONE).
X
X
X
X
X
X
X
X
X
X
XSTATES      | start     | stop      | block     | unblock   | destroy   | INVOKE    | RETURN    | INTERRUPT
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XUNBLOCKED   |  T,U,ID   |     X     |     X     |     X     | destroy   |     X     |     X     |    X
XIDLE        |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XUNBLOCKED   |    E      |  I,U,ID   |  I,B,P    |     X     | destroy   |     X     |     X     |    X
XPENDING     |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XUNBLOCKED   |    E      |  I,U,IN   |  I,B,S    |     X     |  D,U,IN   |  I,U,IN   |     X     |    X
XSCHEDULED   |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XUNBLOCKED   |  T,U,IN   |     X     |     X     |     X     |  D,U,IN   |     X     |  I,U,ID   |    X
XINVOKED     |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,ID   |     X     |  I,U,S    | destroy   |     X     |     X     |    X
XPENDING     |           |           |           |+ INVOKE(1)|           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XINACTIVE    |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,IN   |     X     |  I,U,S    |  D,U,IN   |  I,B,P    |     X     |    X
XSCHEDULED   |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XUNBLOCKED   |     E     |  I,U,ID   |  T,B,ID   |     X     | destroy   |     X     |     X     |  I|T,U,S (2)
XIDLE        |           |           |           |           |           |           |           |+ INVOKE
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XUNBLOCKED   |     E     |  I,U,IN   |  T,B,S    |     X     |  D,U,IN   |  T,U,IN   |     X     |  T,U,S (3)
XSCHEDULED   |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XUNBLOCKED   |     E     |  I,U,IN   |  T,B,IN   |     X     |  D,U,IN   |     X     |  T,U,ID   |  T,U,S (3)
XINVOKED     |           |           |           |           |           |           |           |+ INVOKE (1)
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,ID   |     X     |  T,U,ID   | destroy   |     X     |     X     |  I|T,B,P (2)
XIDLE        |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,ID   |     X     |  T,U,S    | destroy   |     X     |     X     |    X
XPENDING     |           |           |           |+ INVOKE(1)|           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,IN   |     X     |  T,U,S    |  D,U,IN   |  T,B,P    |  T,B,P    |    X
XSCHEDULED   |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XTICKING     |           |           |           |           |           |           |           |
XBLOCKED     |     E     |  I,U,IN   |     X     |  T,U,IN   |  D,U,IN   |     X     |  T,B,ID   |  T,B,S
XINVOKED     |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
XDESTROYED   |           |           |           |           |           |           |           |
XUNBLOCKED   |     E     |     X     |     X     |     X     |     X     |     X     | destroy   |    X
XINVOKED     |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
X            |           |           |           |           |           |           |           |
X            |           |           |           |           |           |           |           |
X            |           |           |           |           |           |           |           |
X------------|-----------|-----------|-----------|-----------|-----------|-----------|-----------|------------------
X
XX stands for NO-OP.
X
XNotes:
X
X1. The INVOKE operation immediately follows.
X2. Whether the ticking state changes to INACTIVE depends on whether the timer expires periodically (if it does,
X   the ticking state does not change).
X3. There is no change of the ticking state since we know that the timer expires periodically.
X
X
XSome states may seem impossible. For example, (TICKING, BLOCKED, INVOKED) can only happen if the user function
Xissues a timer_block operation. This makes sense, if the timer expires periodically.
X
END_OF_FILE
if test 8393 -ne `wc -c <'libs/src/timer/STATES'`; then
    echo shar: \"'libs/src/timer/STATES'\" unpacked with wrong size!
fi
# end of 'libs/src/timer/STATES'
fi
if test -f 'libs/src/timer/timer.3' -a "${1}" != "-c" ; then
  echo shar: Will not clobber existing file \"'libs/src/timer/timer.3'\"
else
echo shar: Extracting \"'libs/src/timer/timer.3'\" \(9093 characters\)
sed "s/^X//" >'libs/src/timer/timer.3' <<'END_OF_FILE'
X.\"(c) Copyright 1993 by Panagiotis Tsirigotis
X.\"All rights reserved.  The file named COPYRIGHT specifies the terms
X.\"and conditions for redistribution.
X.\"
X.\" $Id: timer.3,v 5.1 93/11/26 12:16:09 panos Exp $
X.TH TIMER 3X "20 April 1993"
X.SH NAME
Xtimer_create, timer_destroy, timer_start, timer_stop, timer_block, timer_unblock, timer_expirations, timer_block_type, timer_unblock_type - timer management functions
X.SH SYNOPSIS
X.LP
X.nf
X.ft B
X#include "timer.h"
X.LP
X.ft B
Xenum timer_types { TIMER_REAL, TIMER_VIRTUAL, TIMER_PROF } ;
Xenum timer_timetypes { TIMER_ABSOLUTE, TIMER_RELATIVE } ;
X.LP
X.ft B
Xextern int timer_errno ;
X.LP
X.ft B
Xtimer_h timer_create( type, flags, errnop )
Xenum timer_types type ;
Xint flags ;
Xint *errnop ;
X.LP
X.ft B
Xvoid timer_destroy( handle )
Xtimer_h handle ;
X.LP
X.ft B
Xint timer_start( handle, itvp, time_type, action )
Xtimer_h handle ;
Xstruct itimerval *itvp ;
Xenum timer_timetypes time_type ;
Xstruct timer_action *action ;
X.LP
X.ft B
Xvoid timer_stop( handle )
Xtimer_h handle ;
X.LP
X.ft B
Xvoid timer_block( handle )
Xtimer_h handle ;
X.LP
X.ft B
Xvoid timer_unblock( handle )
Xtimer_h handle ;
X.LP
X.ft B
Xunsigned timer_expirations( handle )
Xtimer_h handle ;
X.LP
X.ft B
Xvoid timer_block_type( type )
Xenum timer_types type ;
X.LP
X.ft B
Xvoid timer_unblock_type( type )
Xenum timer_types type ;
X.SH DESCRIPTION
X.LP
XThis library provides support for multiple timers of various types by
Xmultiplexing the timers provided by the operating system.
XAn action is associated with each timer.
XThe action can either be a function that will be invoked when the
Xtimer expires,
Xor it can be an integer variable that will either be set to
X.SM TRUE
Xwhen the timer expires or it will be increased for every expiration
Xof the timer (it is up to the user to clear the variable after inspecting
Xits value).
XIf a function is used, then it is possible that while that function is running,
Xmore timers may expire and their functions be called
X(i.e. timer interrupts are not blocked while the function is running).
XThe timer-action association can change through the lifetime of the timer.
XThe timer types supported by this library depend on the operating system.
X.\" *********************** timer_create *****************************
X.LP
X.B timer_create()
Xcreates a timer and returns a handle to it. When the timer is created, it
Xis inactive. Possible values for \fItype\fP are:
X.TP 18
X.SB TIMER_REAL
Xtimers of this type are wall-clock timers
X.TP
X.SB TIMER_VIRTUAL
Xtimers of this type are running only when the process is running
X.TP
X.SB TIMER_PROF
Xtimers of this type are running only when the process is running
Xor the system is doing work on behalf of the process.
X.LP
XPossible values for \fIflags\fP are formed by ORing any of the following
Xconstants:
X.TP 20
X.SB TIMER_RETURN_ERROR
Xif an error
Xoccurs while handling \fIthis\fP timer an error indication will be returned
X(the default is program termination)
X.LP
XYou can use the constant
X.B TIMER_NOFLAGS
Xto specify no flags at all.
XThe argument
X.I errnop
Xis a pointer to a variable where error values will be placed
X(the default, in case
X.I errnop
Xis
X.SM NULL,
Xis \fItimer_errno\fP).
X.\" *********************** timer_destroy *****************************
X.LP
X.B timer_destroy()
Xdestroys the timer specified by \fIhandle\fP.
XIf the timer is active, it is deactivated first.
X.\" *********************** timer_start *****************************
X.LP
X.B timer_start()
Xactivates the timer specified by
X.I handle.
XThe expiration time is determined by
X.I itvp
Xand
X.I time_type.
X.I time_type
Xcan be either
X.B TIMER_ABSOLUTE
Xor
X.B TIMER_RELATIVE.
XTimers of the former
Xtype expire at the time
Xspecified by
X.I "itvp->it_value"
X(if that time is before the
Xcurrent time then the timer expires immediately), while the expiration
Xtime of timers of the latter type expire at
X.I "current time + itvp->it_value."
X.I "itvp->it_interval"
Xis the interval between subsequent expirations of the timer after the
Xoriginal expiration.
XThe
X.I action
Xargument determines the action to be taken when the timer expires.
X.LP
X.I "struct timer_action"
Xis defined as follows:
X.sp 1
X.PD .1v
X.RS
X.nf
Xstruct timer_action
X{
X.RS
X.IP "int" 15
Xta_flags ;
X.IP "void"
X(*ta_func)() ;
X.IP void
X*ta_arg ;
X.IP jmp_buf
Xta_env ;
X.RE
X} ;
X.RE
X.PD
X.fi
X.LP
XThe type of action taken when a timer expires depends on
X.I ta_func
Xand
X.I ta_arg.
X.RS
X.IP "Case 1: ta_func != NULL"
XThe function will be invoked with 2 arguments: the handle of the expired
Xtimer and
X.I ta_arg.
X.I "Such functions should not use longjmp."
X.IP "Case 2: ta_func == NULL && ta_arg != NULL"
X.I ta_arg
Xis assumed to be a pointer to an integer variable. This variable will
Xeither be set to
X.SM TRUE
Xor its value will be increased.
X.IP "Case 3: ta_func == NULL && ta_arg == NULL"
Xnothing happens.
X.RE
X.sp 1
X.I ta_flags
Xis formed by ORing any of the following constants:
X.TP 20
X.SB TIMER_INC_VAR
XWhen the action associated with the timer is an integer variable then
Xthe variable will be increased by the number of timer expirations (the
Xdefault is for the variable to be set to 1).
X.TP
X.SB TIMER_BLOCK_ALL
XWhen the action associated with the timer is a function, all timer
Xinterrupts will be blocked while the function is running.
X.TP
X.SB TIMER_BLOCK_SAME
XWhen the action associated with the timer is a function, all timers
Xof the same type will be blocked while the function is running.
X.TP
X.SB TIMER_LONGJMP
XA longjmp(3) will be performed using
X.I ta_env
Xafter the action associated with the timer is performed.
X.LP
XYou can use the constant
X.B TIMER_NOFLAGS
Xto specify no flags at all.
X.\" *********************** timer_stop *****************************
X.LP
X.B timer_stop()
Xstops the specified timer. The timer becomes inactive and it cannot
Xbe restarted for the time that was remaining until expiration.
X.\" *********************** timer_block *****************************
X.LP
X.B timer_block()
Xblocks the specified timer. The timer is still active and may expire
Xbut its action will not be executed until the
Xtimer is unblocked.
X.\" *********************** timer_unblock *****************************
X.LP
X.B timer_unblock()
Xunblocks the specified timer. If the timer is past its expiration time,
Xthe associated action will be executed immediately.
X.\" *********************** timer_expirations *****************************
X.LP
X.B timer_expirations()
Xshould be used by the user-specified function to find out
Xthe number of times the timer expired until the function was called.
XMultiple expirations are possible for a timer that expires periodically.
X.\" *********************** timer_block_type *****************************
X.LP
X.B timer_block_type()
Xblocks all timers of the specified \fItype\fP.
XThis also includes any timers started
X.I after
Xthis function is invoked.
X.\" *********************** timer_unblock_type *****************************
X.LP
X.B timer_unblock_type()
Xunblocks all timers of the specified \fItype\fP.
X.\" *********************** notes *****************************
X.SH NOTES
X.LP
XAny of the timer operations can be used on any timer handle at any time.
XSpecifically, the operations can be used from within the functions
Xinvoked when the timers expire.
X.LP
XThe function associated with a timer is not
Xinvoked for each expiration of that timer.
XIt is possible for a timer to expire
Xmultiple times while its function is running (because timers can
Xbe scheduled to expire periodically), or while other timer functions
Xare running. The timer function can find out how many times its timer
Xhas expired by using the
X.B timer_expirations()
Xoperation.
X.LP
XIt is guaranteed that the function associated with a specific timer will
Xnot be called recursively if that timer expires multiple times.
X.LP
XThe order of execution of timer-associated functions for
Xtimers that expire at the same time is undefined.
X.SH "RETURN VALUES"
X.LP
XValues for
X.I timer_errno
Xwill be stored in the user-specified variable if one was provided.
X.LP
X.B timer_create()
Xreturns a timer handle if successful or
X.SM NULL
Xif it fails.
X.LP
X.B timer_start()
Xreturns
X.B TIMER_OK
Xif successful or
X.B TIMER_ERR
Xif it fails.
X.LP
X.B timer_expirations()
Xreturns a positive (non-zero) number when invoked from a timer-associated
Xfunction; otherwise its return value is undefined.
X.RE
X.SH "ERRORS"
XThe following is a list of error codes which will be placed in
X.I timer_errno
Xor the user-specified variable when a timer operation fails:
X.RS
X.TP 20
X.SB TIMER_ENOMEM
XA memory allocation request failed.
X.TP
X.SB TIMER_EBADTYPE
XAn unknown timer type was specified.
X.TP
X.SB TIMER_ESIGPROBLEM
XA signal handler could not be installed.
X.TP
X.SB TIMER_EBADSTATE
XThe timer state does not allow this operation (for example, the timer is
Xrunning and the operation attempted was \fBtimer_start()\fP).
X.TP
X.SB TIMER_EBADTIME
XThe time value specified was negative.
X.TP
X.SB TIMER_ENOTAVAILABLE
XThe requested timer type is not available.
X.TP
X.SB TIMER_ECANTINSERT
XThe insertion of this timer in the queue of timers failed.
X.TP
X.SB TIMER_SIGPROBLEM
XThere was an error while trying to install a signal handler.
X.SH "SEE ALSO"
Xsetitimer(2), setjmp(3), longjmp(3)
END_OF_FILE
if test 9093 -ne `wc -c <'libs/src/timer/timer.3'`; then
    echo shar: \"'libs/src/timer/timer.3'\" unpacked with wrong size!
fi
# end of 'libs/src/timer/timer.3'
fi
echo shar: End of archive 15 \(of 20\).
cp /dev/null ark15isdone
MISSING=""
for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 ; do
    if test ! -f ark${I}isdone ; then
    MISSING="${MISSING} ${I}"
    fi
done
if test "${MISSING}" = "" ; then
    echo You have unpacked all 20 archives.
    rm -f ark[1-9]isdone ark[1-9][0-9]isdone
else
    echo You still need to unpack the following archives:
    echo "        " ${MISSING}
fi
##  End of shell archive.
exit 0