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

NAME

6       explain_malloc - explain malloc(3) errors
7

SYNOPSIS

9       #include <libexplain/malloc.h>
10       const char *explain_malloc(size_t size);
11       const char *explain_errno_malloc(int errnum, size_t size);
12       void  explain_message_malloc(char  *message,  int  message_size, size_t
13       size);
14       void explain_message_errno_malloc(char *message, int message_size,  int
15       errnum, size_t size);
16

DESCRIPTION

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

SEE ALSO

173       malloc(3)
174               Allocate and free dynamic memory
175
176       explain_malloc_or_die(3)
177               Allocate and free dynamic memory and report errors
178
180       libexplain version 0.40
181       Copyright (C) 2009 Peter Miller
182
183
184
185                                                             explain_malloc(3)
Impressum