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

NAME

6       explain_setenv - explain setenv(3) errors
7

SYNOPSIS

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

DESCRIPTION

20       These  functions may be used to obtain explanations for errors returned
21       by the setenv(3) system call.
22
23   explain_setenv
24       const char *explain_setenv(const char *name, const char *value, int
25       overwrite);
26
27       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
32       The errno global variable will be used to obtain the error value to  be
33       decoded.
34
35       name    The  original  name,  exactly as passed to the setenv(3) system
36               call.
37
38       value   The original value, exactly as passed to the  setenv(3)  system
39               call.
40
41       overwrite
42               The original overwrite, exactly as passed to the setenv(3) sys‐
43               tem call.
44
45       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
52       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
55       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
64       The   above   code   example   is   available   pre‐packaged   as   the
65       explain_setenv_or_die(3) function.
66
67   explain_errno_setenv
68       const char *explain_errno_setenv(int errnum, const char *name, const
69       char *value, int overwrite);
70
71       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
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       name    The original name, exactly as passed to  the  setenv(3)  system
83               call.
84
85       value   The  original  value, exactly as passed to the setenv(3) system
86               call.
87
88       overwrite
89               The original overwrite, exactly as passed to the setenv(3) sys‐
90               tem call.
91
92       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
99       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
102       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
112       The   above   code   example   is   available   pre‐packaged   as   the
113       explain_setenv_or_die(3) function.
114
115   explain_message_setenv
116       void explain_message_setenv(char *message, int message_size, const char
117       *name, const char *value, int overwrite);
118
119       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
124       The  errno global variable will be used to obtain the error value to be
125       decoded.
126
127       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
131       message_size
132               The size in bytes  of  the  location  in  which  to  store  the
133               returned message.
134
135       name    The  original  name,  exactly as passed to the setenv(3) system
136               call.
137
138       value   The original value, exactly as passed to the  setenv(3)  system
139               call.
140
141       overwrite
142               The original overwrite, exactly as passed to the setenv(3) sys‐
143               tem call.
144
145       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
156       The   above   code   example   is   available   pre‐packaged   as   the
157       explain_setenv_or_die(3) function.
158
159   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
163       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
168       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
172       message_size
173               The  size  in  bytes  of  the  location  in  which to store the
174               returned message.
175
176       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
182       name    The original name, exactly as passed to  the  setenv(3)  system
183               call.
184
185       value   The  original  value, exactly as passed to the setenv(3) system
186               call.
187
188       overwrite
189               The original overwrite, exactly as passed to the setenv(3) sys‐
190               tem call.
191
192       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
204       The   above   code   example   is   available   pre‐packaged   as   the
205       explain_setenv_or_die(3) function.
206

SEE ALSO

208       setenv(3)
209               change or add an environment variable
210
211       explain_setenv_or_die(3)
212               change or add an environment variable and report errors
213
215       libexplain version 0.40
216       Copyright (C) 2010 Peter Miller
217
218
219
220                                                             explain_setenv(3)
Impressum