Page History

...

Code Block

bgColor	#ccccff
lang	c

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

enum { MAXLINE = 1024 };
volatile sig_atomic_t eflag = 0;

void handler(int signum) {
  eflag = 1;
}

void log_message(char *info1, char *info2) {
  static char *buf = NULL;
  static size_t bufsize;
  char buf0[MAXLINE];

  if (buf == NULL) {
    buf = buf0;
    bufsize = sizeof(buf0);
  }

  /*
   *  Try to fit a message into buf, else re-allocate
   *  it on the heap and then log the message.
   */
  if (buf == buf0) {
    buf = NULL;
  }
}

int main(void) {
  if (signal(SIGINT, handler) == SIG_ERR) {
    /* Handle error */
  }
  char *info1;
  char *info2;

  /* info1 and info2 are set by user input here */

  while (!eflag) {
    /* Main loop program code */
    log_message(info1, info2);
    /* More program code */
  }

  log_message(info1, info2);

  return 0;
}

Implementation Details

POSIX

The following table from the the Open Group Base Specifications [Open Group 2004] defines a set of functions that are asynchronous-signal-safe. Applications may invoke these functions, without restriction, from a signal handler.

Asynchronous-Signal-Safe Functions

`_Exit()`	`_exit()`	`abort()`	`accept()`
`access()`	`aio_error()`	`aio_return()`	`aio_suspend()`
`alarm()`	`bind()`	`cfgetispeed()`	`cfgetospeed()`
`cfsetispeed()`	`cfsetospeed()`	`chdir()`	`chmod()`
`chown()`	`clock_gettime()`	`close()`	`connect()`
`creat()`	`dup()`	`dup2()`	`execle()`
`execve()`	`fchmod()`	`fchown()`	`fcntl()`
`fdatasync()`	`fork()`	`fpathconf()`	`fstat()`
`fsync()`	`ftruncate()`	`getegid()`	`geteuid()`
`getgid()`	`getgroups()`	`getpeername()`	`getpgrp()`
`getpid()`	`getppid()`	`getsockname()`	`getsockopt()`
`getuid()`	`kill()`	`link()`	`listen()`
`lseek()`	`lstat()`	`mkdir()`	`mkfifo()`
`open()`	`pathconf()`	`pause()`	`pipe()`
`poll()`	`posix_trace_event()`	`pselect()`	`raise()`
`read()`	`readlink()`	`recv()`	`recvfrom()`
`recvmsg()`	`rename()`	`rmdir()`	`select()`
`sem_post()`	`send()`	`sendmsg()`	`sendto()`
`setgid()`	`setpgid()`	`setsid()`	`setsockopt()`
`setuid()`	`shutdown()`	`sigaction()`	`sigaddset()`
`sigdelset()`	`sigemptyset()`	`sigfillset()`	`sigismember()`
`sleep()`	`signal()`	`sigpause()`	`sigpending()`
`sigprocmask()`	`sigqueue()`	`sigset()`	`sigsuspend()`
`sockatmark()`	`socket()`	`socketpair()`	`stat()`
`symlink()`	`sysconf()`	`tcdrain()`	`tcflow()`
`tcflush()`	`tcgetattr()`	`tcgetpgrp()`	`tcsendbreak()`
`tcsetattr()`	`tcsetpgrp()`	`time()`	`timer_getoverrun()`
`timer_gettime()`	`timer_settime()`	`times()`	`umask()`
`uname()`	`unlink()`	`utime()`	`wait()`
`waitpid()`	`write()`

All functions not listed in this table are considered to be unsafe with respect to signals. In the presence of signals, all functions defined by IEEE standard 1003.1-2001 behave as defined when called from or interrupted by a signal handler, with a single exception: when a signal interrupts an unsafe function and the signal handler calls an unsafe function, the behavior is undefined.

Note that although raise() is on the list of asynchronous-safe functions, it should not be called within a signal handler if the signal occurs as a result of abort() or raise() function.

Section 7.14.1.1, para. 4, of the C standard [ISO/IEC 9899:2011] states:

If the signal occurs as the result of calling the abort or raise function, the signal handler shall not call the raise function.

(See also undefined behavior 131 of Annex J.)

Noncompliant Code Example

In this noncompliant code example, the int_handler() function is used to carry out SIGINT-specific tasks and then raises a SIGTERM. However, there is a nested call to the raise() function, which results in undefined behavior.

Code Block

bgColor	#ffcccc
lang	c

void term_handler(int signum) {
  /* SIGTERM handling specific */
}
 
void int_handler(int signum) {
  /* SIGINT handling specific */
  if (raise(SIGTERM) != 0) {  /* violation */
    /* Handle error */
  }
}
 
int main(void) {
  if (signal(SIGTERM, term_handler) == SIG_ERR) {
    /* Handle error */
  }
  if (signal(SIGINT, int_handler) == SIG_ERR) {
    /* Handle error */
  }
 
  /* Program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */
 
  return EXIT_SUCCESS;
}

Compliant Solution

In this compliant solution, the call to the raise() function inside handler() has been replaced by a direct call to log_msg().

Code Block

bgColor	#ccccff
lang	c

#include <signal.h>

void log_msg(int signum) {
  /* Log error message in some asynchronous-safe manner */
}

void handler(int signum) {
  /* Do some handling specific to SIGINT */
  log_msg(SIGUSR1);
}

int main(void) {
  if (signal(SIGUSR1, log_msg) == SIG_ERR) {
    /* Handle error */
  }
  if (signal(SIGINT, handler) == SIG_ERR) {
    /* handle error */
  }

  /* program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */

  return 0;
}

Compliant Solution (POSIX)

If a signal handler is assigned using the POSIX sigaction() function, the signal handler may safely call raise().

The POSIX standard is contradictory regarding raise() in signal handlers. The POSIX standard [Open Group 2004] prohibits signal handlers installed using signal() from calling the raise() function if the signal occurs as the result of calling the raise(), kill(), pthread_kill(), or sigqueue() functions. However, it also requires that the raise() function may be safely called within any signal handler. Consequently, it is not clear whether it is safe for POSIX applications to call raise() in signal handlers installed using signal(), but it is safe to call raise() in signal handlers installed using sigaction().

Code Block

bgColor	#ccccff
lang	c

#include <signal.h>

void log_msg(int signum) {
  /* Log error message in some asynchronous-safe manner */
}

void handler(int signum) {
  /* Do some handling specific to SIGINT */
  if (raise(SIGUSR1) != 0) {
    /* Handle error */
  }
}

int main(void) {
  struct sigaction act;
  act.sa_flags = 0;
  if (sigemptyset(&act.sa_mask) != 0) {
    /* Handle error */
  }
  act.sa_handler = log_msg;
  if (sigaction(SIGUSR1, &act, NULL) != 0) {
    /* Handle error */
  }
  act.sa_handler = handler;
  if (sigaction(SIGINT, &act, NULL) != 0) {
    /* Handle error */
  }

  /* program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */

  return 0;
}

POSIX recommends sigaction() and deprecates signal(). Unfortunately, sigaction() is not defined in the C standard and is consequently not as portable a solution.

OpenBSD

The OpenBSD signal() man page identifies functions that are asynchronous-signal safe. Applications may consequently invoke them, without restriction, from a signal handler.

The OpenBSD signal() manual page lists a few additional functions that are asynchronous-safe in OpenBSD but "probably not on other systems," including snprintf(), vsnprintf(), and syslog_r() (but only when the syslog_data struct is initialized as a local variable).

Compliant Solution

Signal handlers should be as concise as possible, ideally, unconditionally setting a flag and returning. They may also call the _Exit() function. Finally, they may call other functions provided that all implementations to which the code is ported guarantee that these functions are asynchronous-safe.

This example code achieves compliance with this rule by moving the final log message and call to free() outside the signal handler.

...

bgColor	#ccccff
lang	c

...

Noncompliant Code Example

In this noncompliant code example, the int_handler() function is used to carry out SIGINT-specific tasks and then raises a SIGTERM. However, there is a nested call to the raise() function, which results in undefined behavior.

Code Block

bgColor	#ffcccc
lang	c

void term_handler(int signum) {
  /* SIGTERM handling specific */
}
 
void int_handler(int signum) {
  /* SIGINT handling specific */
  if (raise(SIGTERM) != 0) {  /* violation */
    /* Handle error */
  }
}
 
int main(void) {
  if (signal(SIGTERM, term_handler) == SIG_ERR) {
    /* Handle error */
  }
  if (signal(SIGINT, int_handler) == SIG_ERR) {
    /* Handle error */
  }
 
  /* Program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */
 
  return EXIT_SUCCESS;
}

Compliant Solution

In this compliant solution, the call to the raise() function inside handler() has been replaced by a direct call to log_msg().

Code Block

bgColor	#ccccff
lang	c

#include <signal.h>

void log_msg(int signum) {
  /* Log error message in some asynchronous-safe manner */
}

void handler(int signum) {
  /* Do some handling specific to SIGINT */
  log_msg(SIGUSR1);
}

int main(void) {
  if (signal(SIGUSR1, log_msg) == SIG_ERR) {
    /* Handle error */
  }
  if (signal(SIGINT, handler) == SIG_ERR) {
    /* handle error */
  }

  /* program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */

  return 0;
}

Compliant Solution (POSIX)

If a signal handler is assigned using the POSIX sigaction() function, the signal handler may safely call raise().

The POSIX standard is contradictory regarding raise() in signal handlers. The POSIX standard [Open Group 2004] prohibits signal handlers installed using signal() from calling the raise() function if the signal occurs as the result of calling the raise(), kill(), pthread_kill(), or sigqueue() functions. However, it also requires that the raise() function may be safely called within any signal handler. Consequently, it is not clear whether it is safe for POSIX applications to call raise() in signal handlers installed using signal(), but it is safe to call raise() in signal handlers installed using sigaction().

Code Block

bgColor	#ccccff
lang	c

#include <signal.h>

void log_msg(int signum) {
  /* Log error message in some asynchronous-safe manner */
}

void handler(int signum) {
  /* Do some handling specific to SIGINT */
  if (raise(SIGUSR1) != 0) {
    /* Handle error */
  }
}

int main(void) {
  struct sigaction act;
  act.sa_flags = 0;
  if (sigemptyset(&act.sa_mask) != 0) {
    /* Handle error */
  }
  act.sa_handler = log_msg;
  if (sigaction(SIGUSR1, &act, NULL) != 0) {
    /* Handle error */
  }
  act.sa_handler = handler;
  if (sigaction(SIGINT, &act, NULL) != 0) {
    /* Handle error */
  }

  /* program code */
  if (raise(SIGINT) != 0) {
    /* Handle error */
  }
  /* More code */

  return 0;
}

POSIX recommends sigaction() and deprecates signal(). Unfortunately, sigaction() is not defined in the C standard and is consequently not as portable a solution.

Compliant Solution

Signal handlers should be as concise as possible, ideally, unconditionally setting a flag and returning. They may also call the _Exit() function. Finally, they may call other functions provided that all implementations to which the code is ported guarantee that these functions are asynchronous-safe.

This example code achieves compliance with this rule by moving the final log message and call to free() outside the signal handler.

Code Block

bgColor	#ccccff
lang	c

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

enum { MAXLINE = 1024 };
volatile sig_atomic_t eflag = 0;
char *info = NULL;

void log_message(void) {
  fprintf(stderr, info);
}

void handler(int signum) {
  eflag = 1;
}

int main(void) {
  if (signal(SIGINT, handler) == SIG_ERR) {
    /* Handle error */
  }
  info = (char*)malloc(MAXLINE);
  if (info == NULL) {
    /* Handle error */
  }

  while (!eflag) {
    /* Main loop program code */

    log_message();

    /* More program code */
  }

  log_message();
  free(info);
  info = NULL;

  return 0;
}

Implementation Details

POSIX

The following table from the the Open Group Base Specifications [Open Group 2004] defines a set of functions that are asynchronous-signal-safe. Applications may invoke these functions, without restriction, from a signal handler.

Asynchronous-Signal-Safe Functions

`_Exit()`	`_exit()`	`abort()`	`accept()`
`access()`	`aio_error()`	`aio_return()`	`aio_suspend()`
`alarm()`	`bind()`	`cfgetispeed()`	`cfgetospeed()`
`cfsetispeed()`	`cfsetospeed()`	`chdir()`	`chmod()`
`chown()`	`clock_gettime()`	`close()`	`connect()`
`creat()`	`dup()`	`dup2()`	`execle()`
`execve()`	`fchmod()`	`fchown()`	`fcntl()`
`fdatasync()`	`fork()`	`fpathconf()`	`fstat()`
`fsync()`	`ftruncate()`	`getegid()`	`geteuid()`
`getgid()`	`getgroups()`	`getpeername()`	`getpgrp()`
`getpid()`	`getppid()`	`getsockname()`	`getsockopt()`
`getuid()`	`kill()`	`link()`	`listen()`
`lseek()`	`lstat()`	`mkdir()`	`mkfifo()`
`open()`	`pathconf()`	`pause()`	`pipe()`
`poll()`	`posix_trace_event()`	`pselect()`	`raise()`
`read()`	`readlink()`	`recv()`	`recvfrom()`
`recvmsg()`	`rename()`	`rmdir()`	`select()`
`sem_post()`	`send()`	`sendmsg()`	`sendto()`
`setgid()`	`setpgid()`	`setsid()`	`setsockopt()`
`setuid()`	`shutdown()`	`sigaction()`	`sigaddset()`
`sigdelset()`	`sigemptyset()`	`sigfillset()`	`sigismember()`
`sleep()`	`signal()`	`sigpause()`	`sigpending()`
`sigprocmask()`	`sigqueue()`	`sigset()`	`sigsuspend()`
`sockatmark()`	`socket()`	`socketpair()`	`stat()`
`symlink()`	`sysconf()`	`tcdrain()`	`tcflow()`
`tcflush()`	`tcgetattr()`	`tcgetpgrp()`	`tcsendbreak()`
`tcsetattr()`	`tcsetpgrp()`	`time()`	`timer_getoverrun()`
`timer_gettime()`	`timer_settime()`	`times()`	`umask()`
`uname()`	`unlink()`	`utime()`	`wait()`
`waitpid()`	`write()`

All functions not listed in this table are considered to be unsafe with respect to signals. In the presence of signals, all functions defined by IEEE standard 1003.1-2001 behave as defined when called from or interrupted by a signal handler, with a single exception: when a signal interrupts an unsafe function and the signal handler calls an unsafe function, the behavior is undefined.

Note that although raise() is on the list of asynchronous-safe functions, it should not be called within a signal handler if the signal occurs as a result of abort() or raise() function.

Section 7.14.1.1, para. 4, of the C standard [ISO/IEC 9899:2011] states:

If the signal occurs as the result of calling the abort or raise function, the signal handler shall not call the raise function.

(See also undefined behavior 131 of Annex J.)

OpenBSD

The OpenBSD signal() man page identifies functions that are asynchronous-signal safe. Applications may consequently invoke them, without restriction, from a signal handler.

The OpenBSD signal() manual page lists a few additional functions that are asynchronous-safe in OpenBSD but "probably not on other systems," including snprintf(), vsnprintf(), and syslog_r() (but only when the syslog_data struct is initialized as a local variable).

...

Risk Assessment

Invoking functions that are not asynchronous-safe from within a signal handler may result in privilege escalation and other attacks.

...

Space shortcuts

Page tree

Versions Compared

Old Version 106

New Version 107

Key

Implementation Details

POSIX

Noncompliant Code Example

Compliant Solution

Compliant Solution (POSIX)

OpenBSD

Compliant Solution

Noncompliant Code Example

Compliant Solution

Compliant Solution (POSIX)

Compliant Solution

Implementation Details

POSIX

OpenBSD

Risk Assessment