1explain_mmap(3) Library Functions Manual explain_mmap(3)
2
6 explain_mmap - explain mmap(2) errors
7
9 #include <libexplain/mmap.h>
10 const char *explain_mmap(void *data, size_t data_size, int prot, int
11 flags, int fildes, off_t offset);
12 const char *explain_errno_mmap(int errnum, void *data, size_t
13 data_size, int prot, int flags, int fildes, off_t offset);
14 void explain_message_mmap(char *message, int message_size, void *data,
15 size_t data_size, int prot, int flags, int fildes, off_t offset);
16 void explain_message_errno_mmap(char *message, int message_size, int
17 errnum, void *data, size_t data_size, int prot, int flags, int fildes,
18 off_t offset);
19
21 These functions may be used to obtain explanations for errors returned
22 by the mmap(2) system call.
23 explain_mmap
25 const char *explain_mmap(void *data, size_t data_size, int prot, int
26 flags, int fildes, off_t offset);
27 The explain_mmap function is used to obtain an explanation of an error
29 returned by the mmap(2) system call. The least the message will contain
30 is the value of strerror(errno), but usually it will do much better,
31 and indicate the underlying cause in more detail.
32 The errno global variable will be used to obtain the error value to be
34 decoded.
35 data The original data, exactly as passed to the mmap(2) system
37 call.
38 data_size
40 The original data_size, exactly as passed to the mmap(2) system
41 call.
42 prot The original prot, exactly as passed to the mmap(2) system
44 call.
45 flags The original flags, exactly as passed to the mmap(2) system
47 call.
48 fildes The original fildes, exactly as passed to the mmap(2) system
50 call.
51 offset The original offset, exactly as passed to the mmap(2) system
53 call.
54 Returns:
56 The message explaining the error. This message buffer is shared
57 by all libexplain functions which do not supply a buffer in
58 their argument list. This will be overwritten by the next call
59 to any libexplain function which shares this buffer, including
60 other threads.
61 Note: This function is not thread safe, because it shares a return buf‐
63 fer across all threads, and many other functions in this library.
64 Example: This function is intended to be used in a fashion similar to
66 the following example:
67 void *result = mmap(data, data_size, prot, flags, fildes, off‐
68 set);
69 if (!result)
70 {
71 fprintf(stderr, "%s\n", explain_mmap(data, data_size, prot,
72 flags, fildes, offset));
73 exit(EXIT_FAILURE);
74 }
75 The above code example is available pre‐packaged as the
77 explain_mmap_or_die(3) function.
78 explain_errno_mmap
80 const char *explain_errno_mmap(int errnum, void *data, size_t
81 data_size, int prot, int flags, int fildes, off_t offset);
82 The explain_errno_mmap function is used to obtain an explanation of an
84 error returned by the mmap(2) system call. The least the message will
85 contain is the value of strerror(errno), but usually it will do much
86 better, and indicate the underlying cause in more detail.
87 errnum The error value to be decoded, usually obtained from the errno
89 global variable just before this function is called. This is
90 necessary if you need to call any code between the system call
91 to be explained and this function, because many libc functions
92 will alter the value of errno.
93 data The original data, exactly as passed to the mmap(2) system
95 call.
96 data_size
98 The original data_size, exactly as passed to the mmap(2) system
99 call.
100 prot The original prot, exactly as passed to the mmap(2) system
102 call.
103 flags The original flags, exactly as passed to the mmap(2) system
105 call.
106 fildes The original fildes, exactly as passed to the mmap(2) system
108 call.
109 offset The original offset, exactly as passed to the mmap(2) system
111 call.
112 Returns:
114 The message explaining the error. This message buffer is shared
115 by all libexplain functions which do not supply a buffer in
116 their argument list. This will be overwritten by the next call
117 to any libexplain function which shares this buffer, including
118 other threads.
119 Note: This function is not thread safe, because it shares a return buf‐
121 fer across all threads, and many other functions in this library.
122 Example: This function is intended to be used in a fashion similar to
124 the following example:
125 void *result = mmap(data, data_size, prot, flags, fildes, off‐
126 set);
127 if (!result)
128 {
129 int err = errno;
130 fprintf(stderr, "%s\n", explain_errno_mmap(err, data,
131 data_size, prot, flags, fildes, offset));
132 exit(EXIT_FAILURE);
133 }
134 The above code example is available pre‐packaged as the
136 explain_mmap_or_die(3) function.
137 explain_message_mmap
139 void explain_message_mmap(char *message, int message_size, void *data,
140 size_t data_size, int prot, int flags, int fildes, off_t offset);
141 The explain_message_mmap function is used to obtain an explanation of
143 an error returned by the mmap(2) system call. The least the message
144 will contain is the value of strerror(errno), but usually it will do
145 much better, and indicate the underlying cause in more detail.
146 The errno global variable will be used to obtain the error value to be
148 decoded.
149 message The location in which to store the returned message. If a suit‐
151 able message return buffer is supplied, this function is thread
152 safe.
153 message_size
155 The size in bytes of the location in which to store the
156 returned message.
157 data The original data, exactly as passed to the mmap(2) system
159 call.
160 data_size
162 The original data_size, exactly as passed to the mmap(2) system
163 call.
164 prot The original prot, exactly as passed to the mmap(2) system
166 call.
167 flags The original flags, exactly as passed to the mmap(2) system
169 call.
170 fildes The original fildes, exactly as passed to the mmap(2) system
172 call.
173 offset The original offset, exactly as passed to the mmap(2) system
175 call.
176 Example: This function is intended to be used in a fashion similar to
178 the following example:
179 void *result = mmap(data, data_size, prot, flags, fildes, off‐
180 set);
181 if (!result)
182 {
183 char message[3000];
184 explain_message_mmap(message, sizeof(message), data,
185 data_size, prot, flags, fildes, offset);
186 fprintf(stderr, "%s\n", message);
187 exit(EXIT_FAILURE);
188 }
189 The above code example is available pre‐packaged as the
191 explain_mmap_or_die(3) function.
192 explain_message_errno_mmap
194 void explain_message_errno_mmap(char *message, int message_size, int
195 errnum, void *data, size_t data_size, int prot, int flags, int fildes,
196 off_t offset);
197 The explain_message_errno_mmap function is used to obtain an explana‐
199 tion of an error returned by the mmap(2) system call. The least the
200 message will contain is the value of strerror(errno), but usually it
201 will do much better, and indicate the underlying cause in more detail.
202 message The location in which to store the returned message. If a suit‐
204 able message return buffer is supplied, this function is thread
205 safe.
206 message_size
208 The size in bytes of the location in which to store the
209 returned message.
210 errnum The error value to be decoded, usually obtained from the errno
212 global variable just before this function is called. This is
213 necessary if you need to call any code between the system call
214 to be explained and this function, because many libc functions
215 will alter the value of errno.
216 data The original data, exactly as passed to the mmap(2) system
218 call.
219 data_size
221 The original data_size, exactly as passed to the mmap(2) system
222 call.
223 prot The original prot, exactly as passed to the mmap(2) system
225 call.
226 flags The original flags, exactly as passed to the mmap(2) system
228 call.
229 fildes The original fildes, exactly as passed to the mmap(2) system
231 call.
232 offset The original offset, exactly as passed to the mmap(2) system
234 call.
235 Example: This function is intended to be used in a fashion similar to
237 the following example:
238 void *result = mmap(data, data_size, prot, flags, fildes, off‐
239 set);
240 if (!result)
241 {
242 int err = errno;
243 char message[3000];
244 explain_message_errno_mmap(message, sizeof(message), err,
245 data, data_size, prot, flags, fildes, offset);
246 fprintf(stderr, "%s\n", message);
247 exit(EXIT_FAILURE);
248 }
249 The above code example is available pre‐packaged as the
251 explain_mmap_or_die(3) function.
252
254 mmap(2) map file or device into memory
255 explain_mmap_or_die(3)
257 map file or device into memory and report errors
258
260 libexplain version 0.40
261 Copyright (C) 2010 Peter Miller
262 explain_mmap(3)