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

NAME

6       explain_realloc - explain realloc(3) errors
7

SYNOPSIS

9       #include <libexplain/realloc.h>
10       const char *explain_realloc(void *ptr, size_t size);
11       const char *explain_errno_realloc(int errnum, void *ptr, size_t size);
12       void  explain_message_realloc(char  *message,  int  message_size,  void
13       *ptr, size_t size);
14       void explain_message_errno_realloc(char *message, int message_size, int
15       errnum, void *ptr, size_t size);
16

DESCRIPTION

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

SEE ALSO

189       realloc(3)
190               Allocate and free dynamic memory
191
192       explain_realloc_or_die(3)
193               Allocate and free dynamic memory and report errors
194
196       libexplain version 0.40
197       Copyright (C) 2009 Peter Miller
198
199
200
201                                                            explain_realloc(3)
Impressum