1explain_kill(3)            Library Functions Manual            explain_kill(3)
2
3
4

NAME

6       explain_kill - explain kill(2) errors
7

SYNOPSIS

9       #include <libexplain/kill.h>
10       const char *explain_kill(pid_t pid, int sig);
11       const char *explain_errno_kill(int errnum, pid_t pid, int sig);
12       void explain_message_kill(char *message, int message_size, pid_t pid,
13       int sig);
14       void explain_message_errno_kill(char *message, int message_size, int
15       errnum, pid_t pid, int sig);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the kill(2) system call.
20
21   explain_kill
22       const char *explain_kill(pid_t pid, int sig);
23
24       The explain_kill function is used to obtain an explanation of an  error
25       returned by the kill(2) system call. The least the message will contain
26       is the value of strerror(errno), but usually it will  do  much  better,
27       and indicate the underlying cause in more detail.
28
29       The  errno global variable will be used to obtain the error value to be
30       decoded.
31
32       pid     The original pid, exactly as passed to the kill(2) system call.
33
34       sig     The original sig, exactly as passed to the kill(2) system call.
35
36       Returns:
37               The message explaining the error. This message buffer is shared
38               by  all  libexplain  functions  which do not supply a buffer in
39               their argument list.  This will be overwritten by the next call
40               to  any libexplain function which shares this buffer, including
41               other threads.
42
43       Note: This function is not thread safe, because it shares a return buf‐
44       fer across all threads, and many other functions in this library.
45
46       Example:  This  function is intended to be used in a fashion similar to
47       the following example:
48              if (kill(pid, sig) < 0)
49              {
50                  fprintf(stderr, "%s\n", explain_kill(pid, sig));
51                  exit(EXIT_FAILURE);
52              }
53
54       The   above   code   example   is   available   pre‐packaged   as   the
55       explain_kill_or_die(3) function.
56
57   explain_errno_kill
58       const char *explain_errno_kill(int errnum, pid_t pid, int sig);
59
60       The  explain_errno_kill function is used to obtain an explanation of an
61       error returned by the kill(2) system call. The least the  message  will
62       contain  is  the  value of strerror(errno), but usually it will do much
63       better, and indicate the underlying cause in more detail.
64
65       errnum  The error value to be decoded, usually obtained from the  errno
66               global  variable  just  before this function is called. This is
67               necessary if you need to call any code between the system  call
68               to  be explained and this function, because many libc functions
69               will alter the value of errno.
70
71       pid     The original pid, exactly as passed to the kill(2) system call.
72
73       sig     The original sig, exactly as passed to the kill(2) system call.
74
75       Returns:
76               The message explaining the error. This message buffer is shared
77               by  all  libexplain  functions  which do not supply a buffer in
78               their argument list.  This will be overwritten by the next call
79               to  any libexplain function which shares this buffer, including
80               other threads.
81
82       Note: This function is not thread safe, because it shares a return buf‐
83       fer across all threads, and many other functions in this library.
84
85       Example:  This  function is intended to be used in a fashion similar to
86       the following example:
87              if (kill(pid, sig) < 0)
88              {
89                  int err = errno;
90                  fprintf(stderr, "%s\n", explain_errno_kill(err, pid, sig));
91                  exit(EXIT_FAILURE);
92              }
93
94       The   above   code   example   is   available   pre‐packaged   as   the
95       explain_kill_or_die(3) function.
96
97   explain_message_kill
98       void explain_message_kill(char *message, int message_size, pid_t pid,
99       int sig);
100
101       The explain_message_kill function is used to obtain an  explanation  of
102       an  error  returned  by  the kill(2) system call. The least the message
103       will contain is the value of strerror(errno), but usually  it  will  do
104       much better, and indicate the underlying cause in more detail.
105
106       The  errno global variable will be used to obtain the error value to be
107       decoded.
108
109       message The location in which to store the returned message. If a suit‐
110               able message return buffer is supplied, this function is thread
111               safe.
112
113       message_size
114               The size in bytes  of  the  location  in  which  to  store  the
115               returned message.
116
117       pid     The original pid, exactly as passed to the kill(2) system call.
118
119       sig     The original sig, exactly as passed to the kill(2) system call.
120
121       Example:  This  function is intended to be used in a fashion similar to
122       the following example:
123              if (kill(pid, sig) < 0)
124              {
125                  char message[3000];
126                  explain_message_kill(message, sizeof(message), pid, sig);
127                  fprintf(stderr, "%s\n", message);
128                  exit(EXIT_FAILURE);
129              }
130
131       The   above   code   example   is   available   pre‐packaged   as   the
132       explain_kill_or_die(3) function.
133
134   explain_message_errno_kill
135       void explain_message_errno_kill(char *message, int message_size, int
136       errnum, pid_t pid, int sig);
137
138       The explain_message_errno_kill function is used to obtain  an  explana‐
139       tion  of  an  error  returned by the kill(2) system call. The least the
140       message will contain is the value of strerror(errno),  but  usually  it
141       will do much better, and indicate the underlying cause in more detail.
142
143       message The location in which to store the returned message. If a suit‐
144               able message return buffer is supplied, this function is thread
145               safe.
146
147       message_size
148               The  size  in  bytes  of  the  location  in  which to store the
149               returned message.
150
151       errnum  The error value to be decoded, usually obtained from the  errno
152               global  variable  just  before this function is called. This is
153               necessary if you need to call any code between the system  call
154               to  be explained and this function, because many libc functions
155               will alter the value of errno.
156
157       pid     The original pid, exactly as passed to the kill(2) system call.
158
159       sig     The original sig, exactly as passed to the kill(2) system call.
160
161       Example: This function is intended to be used in a fashion  similar  to
162       the following example:
163              if (kill(pid, sig) < 0)
164              {
165                  int err = errno;
166                  char message[3000];
167                  explain_message_errno_kill(message, sizeof(message), err,
168                  pid, sig);
169                  fprintf(stderr, "%s\n", message);
170                  exit(EXIT_FAILURE);
171              }
172
173       The   above   code   example   is   available   pre‐packaged   as   the
174       explain_kill_or_die(3) function.
175

SEE ALSO

177       kill(2) send signal to a process
178
179       explain_kill_or_die(3)
180               send signal to a process and report errors
181
183       libexplain version 1.4
184       Copyright (C) 2009 Peter Miller
185
186
187
188                                                               explain_kill(3)
Impressum