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

NAME

6       explain_setreuid - explain setreuid(2) errors
7

SYNOPSIS

9       #include <libexplain/setreuid.h>
10       const char *explain_setreuid(uid_t ruid, uid_t euid);
11       const char *explain_errno_setreuid(int errnum, uid_t ruid, uid_t euid);
12       void explain_message_setreuid(char *message, int message_size, uid_t
13       ruid, uid_t euid);
14       void explain_message_errno_setreuid(char *message, int message_size,
15       int errnum, uid_t ruid, uid_t euid);
16

DESCRIPTION

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

SEE ALSO

188       setreuid(2)
189               set the real and effective user ID
190
191       explain_setreuid_or_die(3)
192               set the real and effective user ID and report errors
193
195       libexplain version 1.4
196       Copyright (C) 2012 Peter Miller
197
198
199
200                                                           explain_setreuid(3)
Impressum