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

NAME

6       explain_creat - explain creat(2) errors
7

SYNOPSIS

9       #include <libexplain/creat.h>
10       const char *explain_creat(const char *pathname, int mode);
11       const  char  *explain_errno_creat(int errnum, const char *pathname, int
12       mode);
13       void explain_message_creat(char *message, int message_size, const  char
14       *pathname, int mode);
15       void  explain_message_errno_creat(char  *message, int message_size, int
16       errnum, const char *pathname, int mode);
17

DESCRIPTION

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

SEE ALSO

180       creat(2)
181               open and possibly create a file or device
182
183       explain_creat_or_die(3)
184               create and open a file and report errors
185
187       libexplain version 1.4
188       Copyright (C) 2008 Peter Miller
189
190
191
192                                                              explain_creat(3)
Impressum