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

NAME

6       explain_write - explain write(2) errors
7

SYNOPSIS

9       #include <libexplain/write.h>
10       const   char   *explain_write(int   fildes,   const  void  *data,  long
11       data_size);
12       const char *explain_errno_write(int  errnum,  int  fildes,  const  void
13       *data, long data_size);
14       void explain_message_write(char *message, int message_size, int fildes,
15       const void *data, long data_size);
16       void explain_message_errno_write(char *message, int  message_size,  int
17       errnum, int fildes, const void *data, long data_size);
18

DESCRIPTION

20       These  functions may be used to obtain explanations for write(2) errors
21       .
22
23   explain_write
24       const  char  *explain_write(int  fildes,   const   void   *data,   long
25       data_size);
26
27       The  explain_write  function  may  be  used  to obtain a human readable
28       explanation of what went wrong in a write(2) system  call.   The  least
29       the  message  will contain is the value of strerror(errno), but usually
30       it will do much better, and  indicate  the  underlying  cause  in  more
31       detail.
32
33       The error number will be picked up from the errno global variable.
34
35       This  function  is intended to be used in a fashion similar to the fol‐
36       lowing example:
37              sszie_t n = write(fd, data, data_size);
38              if (n < 0)
39              {
40                  fprintf(stderr, '%s0, explain_read(fd, data, data_size));
41                  exit(EXIT_FAILURE);
42              }
43
44       fildes  The original fildes, exactly as passed to the  write(2)  system
45               call.
46
47       data    The  original  data,  exactly  as passed to the write(2) system
48               call.
49
50       data_size
51               The original data_size, exactly as passed to the write(2)  sys‐
52               tem call.
53
54       Returns:
55               The  message  explaining  the  error.   This  message buffer is
56               shared by all libexplain functions which do not supply a buffer
57               in  their  argument list.  This will be overwritten by the next
58               call to any  libexplain  function  which  shares  this  buffer,
59               including other threads.
60
61       Note: This function is not thread safe, because it shares a return buf‐
62       fer across all threads, and many other functions in this library.
63
64   explain_errno_write
65       const char *explain_errno_write(int  errnum,  int  fildes,  const  void
66       *data, long data_size);
67
68       The explain_errno_write function may be used to obtain a human readable
69       explanation of what went wrong in a write(2) system  call.   The  least
70       the  message will contain is the value of strerror(errnum), but usually
71       it will do much better, and  indicate  the  underlying  cause  in  more
72       detail.
73
74       This  function  is intended to be used in a fashion similar to the fol‐
75       lowing example:
76              sszie_t n = write(fd, data, data_size);
77              if (n < 0)
78              {
79                  int err = errno;
80                  fprintf(stderr, '%s0, explain_errno_read(errnum, fd, data,
81                      data_size));
82                  exit(EXIT_FAILURE);
83              }
84
85       errnum  The error value to be decoded, usually obtain  from  the  errno
86               global  variable  just before this function is called.  This is
87               necessary if you need to call any code between the system  call
88               to  be explained and this function, because many libc functions
89               will alter the value of errno.
90
91       fildes  The orginal fildes, exactly as passed to  the  write(2)  system
92               call.
93
94       data    The  original  data,  exactly  as passed to the write(2) system
95               call.
96
97       data_size
98               The original data_size, exactly as passed to the write(2)  sys‐
99               tem call.
100
101       Returns:
102               The  message  explaining  the  error.   This  message buffer is
103               shared by all libexplain functions which do not supply a buffer
104               in  their  argument list.  This will be overwritten by the next
105               call to any  libexplain  function  which  shares  this  buffer,
106               including other threads.
107
108       Note: This function is not thread safe, because it shares a return buf‐
109       fer across all threads, and many other functions in this library.
110
111   explain_message_write
112       void explain_message_write(char *message, int message_size, int fildes,
113       const void *data, long data_size);
114
115       The  explain_message_write function may be used to obtain a human read‐
116       able explanation of what went wrong in a  write(2)  system  call.   The
117       least  the  message  will  contain is the value of strerror(errno), but
118       usually it will do much better, and indicate the  underlying  cause  in
119       more detail.
120
121       The error number will be picked up from the errno global variable.
122
123       This  function  is intended to be used in a fashion similar to the fol‐
124       lowing example:
125              sszie_t n = write(fd, data, data_size);
126              if (n < 0)
127              {
128                  char message[3000];
129                  explain_message_read(message, sizeof(message), fd, data,
130                      data_size));
131                  fprintf(stderr, '%s0, message);
132                  exit(EXIT_FAILURE);
133              }
134
135       message The location in which to store the returned message.  Because a
136               message  return  buffer  has  been  supplied,  this function is
137               thread safe.
138
139       message_size
140               The size in bytes  of  the  location  in  which  to  store  the
141               returned message.
142
143       fildes  The  original  fildes, exactly as passed to the write(2) system
144               call.
145
146       data    The original data, exactly as passed  to  the  write(2)  system
147               call.
148
149       data_size
150               The  original data_size, exactly as passed to the write(2) sys‐
151               tem call.
152
153       Note: Given a suitably thread safe  buffer,  this  function  is  thread
154       safe.
155
156   explain_message_errno_write
157       void  explain_message_errno_write(char * message, int message_size, int
158       errnum, int fildes, const void *data, long data_size);
159
160       The explain_message_errno_write function may be used to obtain a  human
161       readable explanation of what went wrong in a write(2) system call.  The
162       least the message will contain is the value  of  strerror(errnum),  but
163       usually  it  will  do much better, and indicate the underlying cause in
164       more detail.
165
166       This function is intended to be used in a fashion similar to  the  fol‐
167       lowing example:
168              sszie_t n = write(fd, data, data_size);
169              if (n < 0)
170              {
171                  int err = errno;
172                  char message[3000];
173                  explain_message_errno_read(message, sizeof(message), errno,
174                      fd, data, data_size));
175                  fprintf(stderr, '%s0, message);
176                  exit(EXIT_FAILURE);
177              }
178
179       message The location in which to store the returned message.  Because a
180               message return buffer  has  been  supplied,  this  function  is
181               thread safe.
182
183       message_size
184               The  size  in  bytes  of  the  location  in  which to store the
185               returned message.
186
187       errnum  The error value to be decoded, usually obtain  from  the  errno
188               global  variable  just before this function is called.  This is
189               necessary if you need to call any code between the system  call
190               to  be explained and this function, because many libc functions
191               will alter the value of errno.
192
193       fildes  The original fildes, exactly as passed to the  write(2)  system
194               call.
195
196       data    The  original  data,  exactly  as passed to the write(2) system
197               call.
198
199       data_size
200               The original data_size, exactly as passed to the write(2)  sys‐
201               tem call.
202
203       Note:  Given  a  suitably  thread  safe buffer, this function is thread
204       safe.
205
207       libexplain version 0.40
208       Copyright (C) 2008 Peter Miller
209

AUTHOR

211       Written by Peter Miller <pmiller@opensource.org.au>
212
213
214
215                                                              explain_write(3)
Impressum