lib/sigpipe-die.h

   1 /* Report a SIGPIPE signal and exit.
   2    Copyright (C) 2008-2020 Free Software Foundation, Inc.
   3
   4    This program is free software: you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 3 of the License, or
   7    (at your option) any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2008.  */
  18
  19 /* SIGPIPE is the signal sent to a process calling write() on a pipe with no
  20    readers.  Together with the signal, the write() call is terminated with
  21    return value -1, errno = EPIPE.  Note that SIGPIPE is a *synchronous*
  22    signal: it occurs only during write(), without delay (unless blocked).
  23
  24    The default reaction on SIGPIPE, namely terminating the process without
  25    an error message, is suitable for programs which only produce output to
  26    standard output and don't have side effects.
  27
  28    When a program has side effects, other than writing to standard output, the
  29    suitable behaviour is either
  30      (a) to exit with an error message
  31    or - in certain cases, for example when writing to subprocesses -
  32      (b) to continue the operation without writing to the pipe/socket with
  33          no readers.
  34
  35    This file provides support for (a).
  36    For (b), the program needs to know which of the output file descriptors
  37    has no readers.  This is usually implemented by blocking the SIGPIPE signal
  38    and handling an EPIPE error indicator in all affected library calls
  39    (write(), send(), fwrite(), fflush(), fclose(), etc.).  */
  40
  41 #ifndef _SIGPIPE_DIE_H
  42 #define _SIGPIPE_DIE_H
  43
  44 #ifdef __cplusplus
  45 extern "C" {
  46 #endif
  47
  48
  49 /* Emit an error message indicating a SIGPIPE signal, and terminate the
  50    process with an error code.  */
  51 /*extern*/ _Noreturn void sigpipe_die (void);
  52
  53 /* Install a SIGPIPE handler that invokes PREPARE_DIE and then emits an
  54    error message and exits.  PREPARE_DIE may be NULL, meaning a no-op.  */
  55 extern void install_sigpipe_die_handler (void (*prepare_die) (void));
  56
  57
  58 #ifdef __cplusplus
  59 }
  60 #endif
  61
  62
  63 #endif /* _SIGPIPE_DIE_H */