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

NAME

6       explain_setregid - explain setregid(2) errors
7

SYNOPSIS

9       #include <libexplain/setregid.h>
10       const char *explain_setregid(gid_t rgid, gid_t egid);
11       const char *explain_errno_setregid(int errnum, gid_t rgid, gid_t egid);
12       void explain_message_setregid(char *message, int message_size, gid_t
13       rgid, gid_t egid);
14       void explain_message_errno_setregid(char *message, int message_size,
15       int errnum, gid_t rgid, gid_t egid);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the setregid(2) system call.
20
21   explain_setregid
22       const char *explain_setregid(gid_t rgid, gid_t egid);
23
24       The explain_setregid function is used to obtain an  explanation  of  an
25       error  returned  by  the setregid(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       rgid    The original rgid, exactly as passed to the setregid(2)  system
33               call.
34
35       egid    The  original egid, exactly as passed to the setregid(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 (setregid(rgid, egid) < 0)
51              {
52                  fprintf(stderr, "%s\n", explain_setregid(rgid, egid));
53                  exit(EXIT_FAILURE);
54              }
55
56       The   above   code   example   is   available   pre-packaged   as   the
57       explain_setregid_or_die(3) function.
58
59   explain_errno_setregid
60       const char *explain_errno_setregid(int errnum, gid_t rgid, gid_t egid);
61
62       The explain_errno_setregid function is used to obtain an explanation of
63       an error returned by the setregid(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       rgid    The original rgid, exactly as passed to the setregid(2)  system
74               call.
75
76       egid    The  original egid, exactly as passed to the setregid(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 (setregid(rgid, egid) < 0)
92              {
93                  int err = errno;
94                  fprintf(stderr, "%s\n", explain_errno_setregid(err, rgid,
95                  egid));
96                  exit(EXIT_FAILURE);
97              }
98
99       The   above   code   example   is   available   pre-packaged   as   the
100       explain_setregid_or_die(3) function.
101
102   explain_message_setregid
103       void explain_message_setregid(char *message, int message_size, gid_t
104       rgid, gid_t egid);
105
106       The  explain_message_setregid function is used to obtain an explanation
107       of an error returned by the setregid(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       rgid    The original rgid, exactly as passed to the setregid(2)  system
123               call.
124
125       egid    The  original egid, exactly as passed to the setregid(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 (setregid(rgid, egid) < 0)
131              {
132                  char message[3000];
133                  explain_message_setregid(message, sizeof(message), rgid,
134                  egid);
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_setregid_or_die(3) function.
141
142   explain_message_errno_setregid
143       void explain_message_errno_setregid(char *message, int message_size,
144       int errnum, gid_t rgid, gid_t egid);
145
146       The explain_message_errno_setregid function is used to obtain an expla‐
147       nation  of an error returned by the setregid(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       rgid    The  original rgid, exactly as passed to the setregid(2) system
167               call.
168
169       egid    The original egid, exactly as passed to the setregid(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 (setregid(rgid, egid) < 0)
175              {
176                  int err = errno;
177                  char message[3000];
178                  explain_message_errno_setregid(message, sizeof(message),
179                  err, rgid, egid);
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_setregid_or_die(3) function.
186

SEE ALSO

188       setregid(2)
189               set real and/or effective group ID
190
191       explain_setregid_or_die(3)
192               set real and/or effective group ID and report errors
193
195       libexplain version 1.4
196       Copyright (C) 2012 Peter Miller
197
198
199
200                                                           explain_setregid(3)
Impressum