lib/libc/sys/abort2.2

   1 .\" Copyright (c) 2005 Wojciech A. Koszek <dunstan@FreeBSD.czest.pl>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD$
  26 .\"
  27 .Dd September 30, 2006
  28 .Dt ABORT2 2
  29 .Os
  30 .Sh NAME
  31 .Nm abort2
  32 .Nd "abort process with diagnostics"
  33 .Sh LIBRARY
  34 .Lb libc
  35 .Sh SYNOPSIS
  36 .In stdlib.h
  37 .Ft void
  38 .Fn abort2 "const char *why" "int nargs" "void **args"
  39 .Sh DESCRIPTION
  40 The
  41 .Fn abort2
  42 system call causes the process to be killed and the specified diagnostic
  43 message (with arguments) to be delivered by the kernel to the
  44 .Xr syslogd 8
  45 daemon.
  46 .Pp
  47 The
  48 .Fa why
  49 argument points to a
  50 .Dv NUL- Ns
  51 terminated string specifying a reason of the program's termination
  52 (maximum 128 characters long).
  53 The
  54 .Fa args
  55 array contains pointers which will be logged numerically
  56 (with the kernel's
  57 .Ql %p
  58 .Xr printf 9
  59 format).
  60 The
  61 .Fa nargs
  62 argument specifies the number of pointers in
  63 .Fa args
  64 (maximum 16).
  65 .Pp
  66 The
  67 .Fn abort2
  68 system call
  69 is intended for use in situations where continuation of a process
  70 is impossible or for other definitive reasons is unwanted, and normal
  71 diagnostic channels cannot be trusted to deliver the message.
  72 .Sh RETURN VALUES
  73 The
  74 .Fn abort2
  75 function
  76 never returns.
  77 .Pp
  78 The process is killed with
  79 .Dv SIGABRT
  80 unless the arguments to
  81 .Fn abort2
  82 are invalid, in which case
  83 .Dv SIGKILL
  84 is used.
  85 .Sh EXAMPLES
  86 .Bd -literal -compact
  87 #include <stdlib.h>
  88
  89 if (weight_kg > max_load) {
  90         void *ptrs[3];
  91
  92         ptrs[0] = (void *)(intptr_t)weight_kg;
  93         ptrs[1] = (void *)(intptr_t)max_load;
  94         ptrs[2] = haystack;
  95         abort2("Camel overloaded", 3, ptrs);
  96 }
  97 .Ed
  98 .Sh SEE ALSO
  99 .Xr abort 3 ,
 100 .Xr exit 3
 101 .Sh HISTORY
 102 The
 103 .Fn abort2
 104 system call first appeared in
 105 .Fx 7.0 .
 106 .Sh AUTHORS
 107 .An -nosplit
 108 The
 109 .Fn abort2
 110 system call was designed by
 111 .An "Poul-Henning Kamp" Aq phk@FreeBSD.org .
 112 It was implemented by
 113 .An "Wojciech A. Koszek" Aq dunstan@freebsd.czest.pl .