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

NAME

6       explain_mmap - explain mmap(2) errors
7

SYNOPSIS

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

DESCRIPTION

21       These functions may be used to obtain explanations for errors  returned
22       by the mmap(2) system call.
23
24   explain_mmap
25       const char *explain_mmap(void *data, size_t data_size, int prot, int
26       flags, int fildes, off_t offset);
27
28       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
33       The  errno global variable will be used to obtain the error value to be
34       decoded.
35
36       data    The original data, exactly as  passed  to  the  mmap(2)  system
37               call.
38
39       data_size
40               The original data_size, exactly as passed to the mmap(2) system
41               call.
42
43       prot    The original prot, exactly as  passed  to  the  mmap(2)  system
44               call.
45
46       flags   The  original  flags,  exactly  as passed to the mmap(2) system
47               call.
48
49       fildes  The original fildes, exactly as passed to  the  mmap(2)  system
50               call.
51
52       offset  The  original  offset,  exactly as passed to the mmap(2) system
53               call.
54
55       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
62       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
65       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
76       The   above   code   example   is   available   pre‐packaged   as   the
77       explain_mmap_or_die(3) function.
78
79   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
83       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
88       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
94       data    The  original  data,  exactly  as  passed to the mmap(2) system
95               call.
96
97       data_size
98               The original data_size, exactly as passed to the mmap(2) system
99               call.
100
101       prot    The  original  prot,  exactly  as  passed to the mmap(2) system
102               call.
103
104       flags   The original flags, exactly as passed  to  the  mmap(2)  system
105               call.
106
107       fildes  The  original  fildes,  exactly as passed to the mmap(2) system
108               call.
109
110       offset  The original offset, exactly as passed to  the  mmap(2)  system
111               call.
112
113       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
120       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
123       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
135       The   above   code   example   is   available   pre‐packaged   as   the
136       explain_mmap_or_die(3) function.
137
138   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
142       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
147       The errno global variable will be used to obtain the error value to  be
148       decoded.
149
150       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
154       message_size
155               The  size  in  bytes  of  the  location  in  which to store the
156               returned message.
157
158       data    The original data, exactly as  passed  to  the  mmap(2)  system
159               call.
160
161       data_size
162               The original data_size, exactly as passed to the mmap(2) system
163               call.
164
165       prot    The original prot, exactly as  passed  to  the  mmap(2)  system
166               call.
167
168       flags   The  original  flags,  exactly  as passed to the mmap(2) system
169               call.
170
171       fildes  The original fildes, exactly as passed to  the  mmap(2)  system
172               call.
173
174       offset  The  original  offset,  exactly as passed to the mmap(2) system
175               call.
176
177       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
190       The   above   code   example   is   available   pre‐packaged   as   the
191       explain_mmap_or_die(3) function.
192
193   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
198       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
203       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
207       message_size
208               The  size  in  bytes  of  the  location  in  which to store the
209               returned message.
210
211       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
217       data    The original data, exactly as  passed  to  the  mmap(2)  system
218               call.
219
220       data_size
221               The original data_size, exactly as passed to the mmap(2) system
222               call.
223
224       prot    The original prot, exactly as  passed  to  the  mmap(2)  system
225               call.
226
227       flags   The  original  flags,  exactly  as passed to the mmap(2) system
228               call.
229
230       fildes  The original fildes, exactly as passed to  the  mmap(2)  system
231               call.
232
233       offset  The  original  offset,  exactly as passed to the mmap(2) system
234               call.
235
236       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
250       The   above   code   example   is   available   pre‐packaged   as   the
251       explain_mmap_or_die(3) function.
252

SEE ALSO

254       mmap(2) map file or device into memory
255
256       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
263
264
265                                                               explain_mmap(3)
Impressum