1explain_setenv(3) Library Functions Manual explain_setenv(3)
2
6 explain_setenv - explain setenv(3) errors
7
9 #include <libexplain/setenv.h>
10 const char *explain_setenv(const char *name, const char *value, int
11 overwrite);
12 const char *explain_errno_setenv(int errnum, const char *name, const
13 char *value, int overwrite);
14 void explain_message_setenv(char *message, int message_size, const char
15 *name, const char *value, int overwrite);
16 void explain_message_errno_setenv(char *message, int message_size, int
17 errnum, const char *name, const char *value, int overwrite);
18
20 These functions may be used to obtain explanations for errors returned
21 by the setenv(3) system call.
22 explain_setenv
24 const char *explain_setenv(const char *name, const char *value, int
25 overwrite);
26 The explain_setenv function is used to obtain an explanation of an
28 error returned by the setenv(3) system call. The least the message will
29 contain is the value of strerror(errno), but usually it will do much
30 better, and indicate the underlying cause in more detail.
31 The errno global variable will be used to obtain the error value to be
33 decoded.
34 name The original name, exactly as passed to the setenv(3) system
36 call.
37 value The original value, exactly as passed to the setenv(3) system
39 call.
40 overwrite
42 The original overwrite, exactly as passed to the setenv(3) sys‐
43 tem call.
44 Returns:
46 The message explaining the error. This message buffer is shared
47 by all libexplain functions which do not supply a buffer in
48 their argument list. This will be overwritten by the next call
49 to any libexplain function which shares this buffer, including
50 other threads.
51 Note: This function is not thread safe, because it shares a return buf‐
53 fer across all threads, and many other functions in this library.
54 Example: This function is intended to be used in a fashion similar to
56 the following example:
57 if (setenv(name, value, overwrite) < 0)
58 {
59 fprintf(stderr, "%s\n", explain_setenv(name, value, over‐
60 write));
61 exit(EXIT_FAILURE);
62 }
63 The above code example is available pre‐packaged as the
65 explain_setenv_or_die(3) function.
66 explain_errno_setenv
68 const char *explain_errno_setenv(int errnum, const char *name, const
69 char *value, int overwrite);
70 The explain_errno_setenv function is used to obtain an explanation of
72 an error returned by the setenv(3) system call. The least the message
73 will contain is the value of strerror(errno), but usually it will do
74 much better, and indicate the underlying cause in more detail.
75 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 name The original name, exactly as passed to the setenv(3) system
83 call.
84 value The original value, exactly as passed to the setenv(3) system
86 call.
87 overwrite
89 The original overwrite, exactly as passed to the setenv(3) sys‐
90 tem call.
91 Returns:
93 The message explaining the error. This message buffer is shared
94 by all libexplain functions which do not supply a buffer in
95 their argument list. This will be overwritten by the next call
96 to any libexplain function which shares this buffer, including
97 other threads.
98 Note: This function is not thread safe, because it shares a return buf‐
100 fer across all threads, and many other functions in this library.
101 Example: This function is intended to be used in a fashion similar to
103 the following example:
104 if (setenv(name, value, overwrite) < 0)
105 {
106 int err = errno;
107 fprintf(stderr, "%s\n", explain_errno_setenv(err, name,
108 value, overwrite));
109 exit(EXIT_FAILURE);
110 }
111 The above code example is available pre‐packaged as the
113 explain_setenv_or_die(3) function.
114 explain_message_setenv
116 void explain_message_setenv(char *message, int message_size, const char
117 *name, const char *value, int overwrite);
118 The explain_message_setenv function is used to obtain an explanation of
120 an error returned by the setenv(3) system call. The least the message
121 will contain is the value of strerror(errno), but usually it will do
122 much better, and indicate the underlying cause in more detail.
123 The errno global variable will be used to obtain the error value to be
125 decoded.
126 message The location in which to store the returned message. If a suit‐
128 able message return buffer is supplied, this function is thread
129 safe.
130 message_size
132 The size in bytes of the location in which to store the
133 returned message.
134 name The original name, exactly as passed to the setenv(3) system
136 call.
137 value The original value, exactly as passed to the setenv(3) system
139 call.
140 overwrite
142 The original overwrite, exactly as passed to the setenv(3) sys‐
143 tem call.
144 Example: This function is intended to be used in a fashion similar to
146 the following example:
147 if (setenv(name, value, overwrite) < 0)
148 {
149 char message[3000];
150 explain_message_setenv(message, sizeof(message), name,
151 value, overwrite);
152 fprintf(stderr, "%s\n", message);
153 exit(EXIT_FAILURE);
154 }
155 The above code example is available pre‐packaged as the
157 explain_setenv_or_die(3) function.
158 explain_message_errno_setenv
160 void explain_message_errno_setenv(char *message, int message_size, int
161 errnum, const char *name, const char *value, int overwrite);
162 The explain_message_errno_setenv function is used to obtain an explana‐
164 tion of an error returned by the setenv(3) system call. The least the
165 message will contain is the value of strerror(errno), but usually it
166 will do much better, and indicate the underlying cause in more detail.
167 message The location in which to store the returned message. If a suit‐
169 able message return buffer is supplied, this function is thread
170 safe.
171 message_size
173 The size in bytes of the location in which to store the
174 returned message.
175 errnum The error value to be decoded, usually obtained from the errno
177 global variable just before this function is called. This is
178 necessary if you need to call any code between the system call
179 to be explained and this function, because many libc functions
180 will alter the value of errno.
181 name The original name, exactly as passed to the setenv(3) system
183 call.
184 value The original value, exactly as passed to the setenv(3) system
186 call.
187 overwrite
189 The original overwrite, exactly as passed to the setenv(3) sys‐
190 tem call.
191 Example: This function is intended to be used in a fashion similar to
193 the following example:
194 if (setenv(name, value, overwrite) < 0)
195 {
196 int err = errno;
197 char message[3000];
198 explain_message_errno_setenv(message, sizeof(message), err,
199 name, value, overwrite);
200 fprintf(stderr, "%s\n", message);
201 exit(EXIT_FAILURE);
202 }
203 The above code example is available pre‐packaged as the
205 explain_setenv_or_die(3) function.
206
208 setenv(3)
209 change or add an environment variable
210 explain_setenv_or_die(3)
212 change or add an environment variable and report errors
213
215 libexplain version 1.4
216 Copyright (C) 2010 Peter Miller
217 explain_setenv(3)