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

NAME

6       explain_setresuid - explain setresuid(2) errors
7

SYNOPSIS

9       #include <libexplain/setresuid.h>
10       const char *explain_setresuid(uid_t ruid, uid_t euid, uid_t suid);
11       const char *explain_errno_setresuid(int errnum, uid_t ruid, uid_t euid,
12       uid_t suid);
13       void explain_message_setresuid(char *message, int message_size, uid_t
14       ruid, uid_t euid, uid_t suid);
15       void explain_message_errno_setresuid(char *message, int message_size,
16       int errnum, uid_t ruid, uid_t euid, uid_t suid);
17

DESCRIPTION

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

SEE ALSO

203       setresuid(2)
204               set real, effective and saved user ID
205
206       explain_setresuid_or_die(3)
207               set real, effective and saved user ID and report errors
208
210       libexplain version 1.4
211       Copyright (C) 2012 Peter Miller
212
213
214
215                                                          explain_setresuid(3)
Impressum