raise()

Generate a signal

Synopsis:

#include <signal.h>

int raise( int condition );

Arguments:

condition

The signal that you want to raise. For more information, see signal().

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The raise() function generates the signal specified by condition. Calling raise() is equivalent to calling:

pthread_kill(pthread_self(), condition);

Use SignalAction() or signal() to specify the actions to take when a signal is received.

Returns:

0 if the specified condition is sent, or nonzero if an error occurs (errno is set).

The raise() function doesn't return if the action for that signal is to terminate the program or to transfer control using the longjmp() function.

Errors:

EAGAIN

Insufficient system resources are available to deliver the signal.

EINVAL

The value of condition isn't a valid signal number.

Examples:

Wait until a SIGINT signal is received. The signal is automatically raised on iteration 10000, or when you press Ctrl-C:

#include <stdio.h>
#include <stdlib.h>
#include <signal.h>

sig_atomic_t signal_count;
sig_atomic_t signal_number;

void alarm_handler( int signum )
{
    ++signal_count;
    signal_number = signum;
}

int main( void )
{
    unsigned long i;

    signal_count = 0;
    signal_number = 0;
    signal( SIGINT, alarm_handler );

    printf("Iteration:      ");
    for( i = 0; i < 100000; ++i ) {
        printf( "\b\b\b\b\b%*d", 5, i );

        if( i == 10000 ) raise( SIGINT );

        if( signal_count > 0 ) break;
    }

    if( i == 100000 ) {
        printf( "\nNo signal was raised.\n" );
    } else if( i == 10000 ) {
        printf( "\nSignal %d was raised by the "
                "raise() function.\n", signal_number );
    } else {
        printf( "\nUser raised signal #%d.\n",
                signal_number );
    }

    return EXIT_SUCCESS;
}

Classification:

ANSI, POSIX 1003.1

See also:

signal(), SignalAction()