explain_getgrouplist(3)

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

NAME

6       explain_getgrouplist - explain getgrouplist(3) errors
7

SYNOPSIS

9       #include <libexplain/getgrouplist.h>
10       const char *explain_getgrouplist(const char *user, gid_t group, gid_t
11       *groups, int *ngroups);
12       const char *explain_errno_getgrouplist(int errnum, const char *user,
13       gid_t group, gid_t *groups, int *ngroups);
14       void explain_message_getgrouplist(char *message, int message_size,
15       const char *user, gid_t group, gid_t *groups, int *ngroups);
16       void explain_message_errno_getgrouplist(char *message, int mes‐
17       sage_size, int errnum, const char *user, gid_t group, gid_t *groups,
18       int *ngroups);
19

DESCRIPTION

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

COPYRIGHT

236       libexplain version 1.4
237       Copyright (C) 2013 Peter Miller
238
239
240
241                                                       explain_getgrouplist(3)

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

COPYRIGHT