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

NAME

6       explain_unsetenv - explain unsetenv(3) errors
7

SYNOPSIS

9       #include <libexplain/unsetenv.h>
10       const char *explain_unsetenv(const char *name);
11       const char *explain_errno_unsetenv(int errnum, const char *name);
12       void explain_message_unsetenv(char *message, int message_size, const
13       char *name);
14       void explain_message_errno_unsetenv(char *message, int message_size,
15       int errnum, const char *name);
16

DESCRIPTION

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

SEE ALSO

174       unsetenv(3)
175               change or add an environment variable
176
177       explain_unsetenv_or_die(3)
178               change or add an environment variable and report errors
179
181       libexplain version 0.40
182       Copyright (C) 2010 Peter Miller
183
184
185
186                                                           explain_unsetenv(3)
Impressum