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

NAME

6       explain_setgrent - explain setgrent(3) errors
7

SYNOPSIS

9       #include <libexplain/setgrent.h>
10       const char *explain_setgrent(void);
11       const char *explain_errno_setgrent(int errnum, void);
12       void explain_message_setgrent(char *message, int message_size, void);
13       void explain_message_errno_setgrent(char *message, int message_size,
14       int errnum, void);
15

DESCRIPTION

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

SEE ALSO

168       setgrent(3)
169               rewind to the start of the group database
170
171       explain_setgrent_or_die(3)
172               rewind to the start of the group database and report errors
173
175       libexplain version 1.4
176       Copyright (C) 2013 Peter Miller
177
178
179
180                                                           explain_setgrent(3)
Impressum