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

NAME

6       explain_tmpnam - explain tmpnam(3) errors
7

SYNOPSIS

9       #include <libexplain/tmpnam.h>
10       const char *explain_tmpnam(char *pathname);
11       const char *explain_errno_tmpnam(int errnum, char *pathname);
12       void explain_message_tmpnam(char *message, int message_size, char
13       *pathname);
14       void explain_message_errno_tmpnam(char *message, int message_size, int
15       errnum, char *pathname);
16

DESCRIPTION

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

SEE ALSO

182       tmpnam(3)
183               create a name for a temporary file
184
185       explain_tmpnam_or_die(3)
186               create a name for a temporary file and report errors
187
189       libexplain version 1.4
190       Copyright (C) 2010 Peter Miller
191
192
193
194                                                             explain_tmpnam(3)
Impressum