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

NAME

6       explain_setgid - explain setgid(2) errors
7

SYNOPSIS

9       #include <libexplain/setgid.h>
10       const char *explain_setgid(gid_t gid);
11       const char *explain_errno_setgid(int errnum, gid_t gid);
12       void explain_message_setgid(char *message, int message_size, gid_t
13       gid);
14       void explain_message_errno_setgid(char *message, int message_size, int
15       errnum, gid_t gid);
16

DESCRIPTION

18       These  functions may be used to obtain explanations for errors returned
19       by the setgid(2) system call.
20
21   explain_setgid
22       const char *explain_setgid(gid_t gid);
23
24       The explain_setgid function is used to  obtain  an  explanation  of  an
25       error returned by the setgid(2) system call. The least the message will
26       contain is the value of strerror(errno), but usually it  will  do  much
27       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       gid     The original gid, exactly as passed  to  the  setgid(2)  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 (setgid(gid) < 0)
48              {
49                  fprintf(stderr, "%s\n", explain_setgid(gid));
50                  exit(EXIT_FAILURE);
51              }
52
53       The  above  code  example is available pre-packaged as the explain_set‐
54       gid_or_die(3) function.
55
56   explain_errno_setgid
57       const char *explain_errno_setgid(int errnum, gid_t gid);
58
59       The explain_errno_setgid function is used to obtain an  explanation  of
60       an  error  returned by the setgid(2) system call. The least the message
61       will contain is the value of strerror(errno), but usually  it  will  do
62       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       gid     The  original  gid,  exactly  as passed to the setgid(2) 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 (setgid(gid) < 0)
86              {
87                  int err = errno;
88                  fprintf(stderr, "%s\n", explain_errno_setgid(err, gid));
89                  exit(EXIT_FAILURE);
90              }
91
92       The above code example is available pre-packaged  as  the  explain_set‐
93       gid_or_die(3) function.
94
95   explain_message_setgid
96       void explain_message_setgid(char *message, int message_size, gid_t
97       gid);
98
99       The explain_message_setgid function is used to obtain an explanation of
100       an  error  returned by the setgid(2) system call. The least the message
101       will contain is the value of strerror(errno), but usually  it  will  do
102       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       gid     The  original  gid,  exactly  as passed to the setgid(2) system
116               call.
117
118       Example: This function is intended to be used in a fashion  similar  to
119       the following example:
120              if (setgid(gid) < 0)
121              {
122                  char message[3000];
123                  explain_message_setgid(message, sizeof(message), gid);
124                  fprintf(stderr, "%s\n", message);
125                  exit(EXIT_FAILURE);
126              }
127
128       The  above  code  example is available pre-packaged as the explain_set‐
129       gid_or_die(3) function.
130
131   explain_message_errno_setgid
132       void explain_message_errno_setgid(char *message, int message_size, int
133       errnum, gid_t gid);
134
135       The explain_message_errno_setgid function is used to obtain an explana‐
136       tion of an error returned by the setgid(2) system call. The  least  the
137       message  will  contain  is the value of strerror(errno), but usually it
138       will do much better, and indicate the underlying cause in more detail.
139
140       message The location in which to store the returned message. If a suit‐
141               able message return buffer is supplied, this function is thread
142               safe.
143
144       message_size
145               The size in bytes  of  the  location  in  which  to  store  the
146               returned message.
147
148       errnum  The  error value to be decoded, usually obtained from the errno
149               global variable just before this function is  called.  This  is
150               necessary  if you need to call any code between the system call
151               to be explained and this function, because many libc  functions
152               will alter the value of errno.
153
154       gid     The  original  gid,  exactly  as passed to the setgid(2) system
155               call.
156
157       Example: This function is intended to be used in a fashion  similar  to
158       the following example:
159              if (setgid(gid) < 0)
160              {
161                  int err = errno;
162                  char message[3000];
163                  explain_message_errno_setgid(message, sizeof(message), err,
164                  gid);
165                  fprintf(stderr, "%s\n", message);
166                  exit(EXIT_FAILURE);
167              }
168
169       The above code example is available pre-packaged  as  the  explain_set‐
170       gid_or_die(3) function.
171

SEE ALSO

173       setgid(2)
174               set group identity
175
176       explain_setgid_or_die(3)
177               set group identity and report errors
178
180       libexplain version 1.4
181       Copyright (C) 2012 Peter Miller
182
183
184
185                                                             explain_setgid(3)
Impressum