1explain_calloc(3) Library Functions Manual explain_calloc(3)
2
3
4
6 explain_calloc - explain calloc(3) errors
7
9 #include <libexplain/calloc.h>
10 const char *explain_calloc(size_t nmemb, size_t size);
11 const char *explain_errno_calloc(int errnum, size_t nmemb, size_t
12 size);
13 void explain_message_calloc(char *message, int message_size, size_t
14 nmemb, size_t size);
15 void explain_message_errno_calloc(char *message, int message_size, int
16 errnum, size_t nmemb, size_t size);
17
19 These functions may be used to obtain explanations for errors returned
20 by the calloc(3) system call.
21
22 explain_calloc
23 const char *explain_calloc(size_t nmemb, size_t size);
24
25 The explain_calloc function is used to obtain an explanation of an
26 error returned by the calloc(3) system call. The least the message will
27 contain is the value of strerror(errno), but usually it will do much
28 better, and indicate the underlying cause in more detail.
29
30 The errno global variable will be used to obtain the error value to be
31 decoded.
32
33 nmemb The original nmemb, exactly as passed to the calloc(3) system
34 call.
35
36 size The original size, exactly as passed to the calloc(3) system
37 call.
38
39 Returns:
40 The message explaining the error. This message buffer is shared
41 by all libexplain functions which do not supply a buffer in
42 their argument list. This will be overwritten by the next call
43 to any libexplain function which shares this buffer, including
44 other threads.
45
46 Note: This function is not thread safe, because it shares a return buf‐
47 fer across all threads, and many other functions in this library.
48
49 Example: This function is intended to be used in a fashion similar to
50 the following example:
51 errno = 0;
52 void *result = calloc(nmemb, size);
53 if (!result && errno != 0)
54 {
55 fprintf(stderr, "%s\n", explain_calloc(nmemb, size));
56 exit(EXIT_FAILURE);
57 }
58
59 The above code example is available pre-packaged as the explain_cal‐
60 loc_or_die(3) function.
61
62 explain_errno_calloc
63 const char *explain_errno_calloc(int errnum, size_t nmemb, size_t
64 size);
65
66 The explain_errno_calloc function is used to obtain an explanation of
67 an error returned by the calloc(3) system call. The least the message
68 will contain is the value of strerror(errno), but usually it will do
69 much better, and indicate the underlying cause in more detail.
70
71 errnum The error value to be decoded, usually obtained from the errno
72 global variable just before this function is called. This is
73 necessary if you need to call any code between the system call
74 to be explained and this function, because many libc functions
75 will alter the value of errno.
76
77 nmemb The original nmemb, exactly as passed to the calloc(3) system
78 call.
79
80 size The original size, exactly as passed to the calloc(3) system
81 call.
82
83 Returns:
84 The message explaining the error. This message buffer is shared
85 by all libexplain functions which do not supply a buffer in
86 their argument list. This will be overwritten by the next call
87 to any libexplain function which shares this buffer, including
88 other threads.
89
90 Note: This function is not thread safe, because it shares a return buf‐
91 fer across all threads, and many other functions in this library.
92
93 Example: This function is intended to be used in a fashion similar to
94 the following example:
95 errno = 0;
96 void *result = calloc(nmemb, size);
97 if (!result && errno != 0)
98 {
99 int err = errno;
100 fprintf(stderr, "%s\n", explain_errno_calloc(err, nmemb,
101 size));
102 exit(EXIT_FAILURE);
103 }
104
105 The above code example is available pre-packaged as the explain_cal‐
106 loc_or_die(3) function.
107
108 explain_message_calloc
109 void explain_message_calloc(char *message, int message_size, size_t
110 nmemb, size_t size);
111
112 The explain_message_calloc function is used to obtain an explanation of
113 an error returned by the calloc(3) system call. The least the message
114 will contain is the value of strerror(errno), but usually it will do
115 much better, and indicate the underlying cause in more detail.
116
117 The errno global variable will be used to obtain the error value to be
118 decoded.
119
120 message The location in which to store the returned message. If a suit‐
121 able message return buffer is supplied, this function is thread
122 safe.
123
124 message_size
125 The size in bytes of the location in which to store the
126 returned message.
127
128 nmemb The original nmemb, exactly as passed to the calloc(3) system
129 call.
130
131 size The original size, exactly as passed to the calloc(3) system
132 call.
133
134 Example: This function is intended to be used in a fashion similar to
135 the following example:
136 errno = 0;
137 void *result = calloc(nmemb, size);
138 if (!result && errno != 0)
139 {
140 char message[3000];
141 explain_message_calloc(message, sizeof(message), nmemb,
142 size);
143 fprintf(stderr, "%s\n", message);
144 exit(EXIT_FAILURE);
145 }
146
147 The above code example is available pre-packaged as the explain_cal‐
148 loc_or_die(3) function.
149
150 explain_message_errno_calloc
151 void explain_message_errno_calloc(char *message, int message_size, int
152 errnum, size_t nmemb, size_t size);
153
154 The explain_message_errno_calloc function is used to obtain an explana‐
155 tion of an error returned by the calloc(3) system call. The least the
156 message will contain is the value of strerror(errno), but usually it
157 will do much better, and indicate the underlying cause in more detail.
158
159 message The location in which to store the returned message. If a suit‐
160 able message return buffer is supplied, this function is thread
161 safe.
162
163 message_size
164 The size in bytes of the location in which to store the
165 returned message.
166
167 errnum The error value to be decoded, usually obtained from the errno
168 global variable just before this function is called. This is
169 necessary if you need to call any code between the system call
170 to be explained and this function, because many libc functions
171 will alter the value of errno.
172
173 nmemb The original nmemb, exactly as passed to the calloc(3) system
174 call.
175
176 size The original size, exactly as passed to the calloc(3) system
177 call.
178
179 Example: This function is intended to be used in a fashion similar to
180 the following example:
181 errno = 0;
182 void *result = calloc(nmemb, size);
183 if (!result && errno != 0)
184 {
185 int err = errno;
186 char message[3000];
187 explain_message_errno_calloc(message, sizeof(message), err,
188 nmemb, size);
189 fprintf(stderr, "%s\n", message);
190 exit(EXIT_FAILURE);
191 }
192
193 The above code example is available pre-packaged as the explain_cal‐
194 loc_or_die(3) function.
195
197 calloc(3)
198 Allocate and clear memory
199
200 explain_calloc_or_die(3)
201 Allocate and clear memory and report errors
202
204 libexplain version 0.40
205 Copyright (C) 2010 Peter Miller
206
207
208
209 explain_calloc(3)