1explain_realloc(3) Library Functions Manual explain_realloc(3)
2
6 explain_realloc - explain realloc(3) errors
7
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
18 These functions may be used to obtain explanations for errors returned
19 by the realloc(3) system call.
20 explain_realloc
22 const char *explain_realloc(void *ptr, size_t size);
23 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 The errno global variable will be used to obtain the error value to be
30 decoded.
31 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 The above code example is available pre‐packaged as the explain_real‐
42 loc_or_die(3) function.
43 ptr The original ptr, exactly as passed to the realloc(3) system
45 call.
46 size The original size, exactly as passed to the realloc(3) system
48 call.
49 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 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 explain_errno_realloc
61 const char *explain_errno_realloc(int errnum, void *ptr, size_t size);
62 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 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 The above code example is available pre‐packaged as the explain_real‐
79 loc_or_die(3) function.
80 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 ptr The original ptr, exactly as passed to the realloc(3) system
88 call.
89 size The original size, exactly as passed to the realloc(3) system
91 call.
92 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 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 explain_message_realloc
104 void explain_message_realloc(char *message, int message_size, void
105 *ptr, size_t size);
106 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 The errno global variable will be used to obtain the error value to be
113 decoded.
114 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 The above code example is available pre‐packaged as the explain_real‐
127 loc_or_die(3) function.
128 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 message_size
134 The size in bytes of the location in which to store the
135 returned message.
136 ptr The original ptr, exactly as passed to the realloc(3) system
138 call.
139 size The original size, exactly as passed to the realloc(3) system
141 call.
142 explain_message_errno_realloc
144 void explain_message_errno_realloc(char *message, int message_size, int
145 errnum, void *ptr, size_t size);
146 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 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 The above code example is available pre‐packaged as the explain_real‐
166 loc_or_die(3) function.
167 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 message_size
173 The size in bytes of the location in which to store the
174 returned message.
175 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 ptr The original ptr, exactly as passed to the realloc(3) system
183 call.
184 size The original size, exactly as passed to the realloc(3) system
186 call.
187
189 realloc(3)
190 Allocate and free dynamic memory
191 explain_realloc_or_die(3)
193 Allocate and free dynamic memory and report errors
194
196 libexplain version 1.4
197 Copyright (C) 2009 Peter Miller
198 explain_realloc(3)