1explain_getrusage(3) Library Functions Manual explain_getrusage(3)
2
6 explain_getrusage - explain getrusage(2) errors
7
9 #include <libexplain/getrusage.h>
10 const char *explain_getrusage(int who, struct rusage *usage);
11 const char *explain_errno_getrusage(int errnum, int who, struct rusage
12 *usage);
13 void explain_message_getrusage(char *message, int message_size, int
14 who, struct rusage *usage);
15 void explain_message_errno_getrusage(char *message, int message_size,
16 int errnum, int who, struct rusage *usage);
17
19 These functions may be used to obtain explanations for errors returned
20 by the getrusage(2) system call.
21 explain_getrusage
23 const char *explain_getrusage(int who, struct rusage *usage);
24 The explain_getrusage function is used to obtain an explanation of an
26 error returned by the getrusage(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 The errno global variable will be used to obtain the error value to be
31 decoded.
32 who The original who, exactly as passed to the getrusage(2) system
34 call.
35 usage The original usage, exactly as passed to the getrusage(2) sys‐
37 tem call.
38 Returns:
40 The message explaining the error. This message buffer is shared
41 by all libexplain functions which do not supply a buffer in
42 their argument list. This will be overwritten by the next call
43 to any libexplain function which shares this buffer, including
44 other threads.
45 Note: This function is not thread safe, because it shares a return buf‐
47 fer across all threads, and many other functions in this library.
48 Example: This function is intended to be used in a fashion similar to
50 the following example:
51 if (getrusage(who, usage) < 0)
52 {
53 fprintf(stderr, "%s\n", explain_getrusage(who, usage));
54 exit(EXIT_FAILURE);
55 }
56 The above code example is available pre-packaged as the
58 explain_getrusage_or_die(3) function.
59 explain_errno_getrusage
61 const char *explain_errno_getrusage(int errnum, int who, struct rusage
62 *usage);
63 The explain_errno_getrusage function is used to obtain an explanation
65 of an error returned by the getrusage(2) system call. The least the
66 message will contain is the value of strerror(errno), but usually it
67 will do much better, and indicate the underlying cause in more detail.
68 errnum The error value to be decoded, usually obtained from the errno
70 global variable just before this function is called. This is
71 necessary if you need to call any code between the system call
72 to be explained and this function, because many libc functions
73 will alter the value of errno.
74 who The original who, exactly as passed to the getrusage(2) system
76 call.
77 usage The original usage, exactly as passed to the getrusage(2) sys‐
79 tem call.
80 Returns:
82 The message explaining the error. This message buffer is shared
83 by all libexplain functions which do not supply a buffer in
84 their argument list. This will be overwritten by the next call
85 to any libexplain function which shares this buffer, including
86 other threads.
87 Note: This function is not thread safe, because it shares a return buf‐
89 fer across all threads, and many other functions in this library.
90 Example: This function is intended to be used in a fashion similar to
92 the following example:
93 if (getrusage(who, usage) < 0)
94 {
95 int err = errno;
96 fprintf(stderr, "%s\n", explain_errno_getrusage(err, who,
97 usage));
98 exit(EXIT_FAILURE);
99 }
100 The above code example is available pre-packaged as the
102 explain_getrusage_or_die(3) function.
103 explain_message_getrusage
105 void explain_message_getrusage(char *message, int message_size, int
106 who, struct rusage *usage);
107 The explain_message_getrusage function is used to obtain an explanation
109 of an error returned by the getrusage(2) system call. The least the
110 message will contain is the value of strerror(errno), but usually it
111 will do much better, and indicate the underlying cause in more detail.
112 The errno global variable will be used to obtain the error value to be
114 decoded.
115 message The location in which to store the returned message. If a suit‐
117 able message return buffer is supplied, this function is thread
118 safe.
119 message_size
121 The size in bytes of the location in which to store the
122 returned message.
123 who The original who, exactly as passed to the getrusage(2) system
125 call.
126 usage The original usage, exactly as passed to the getrusage(2) sys‐
128 tem call.
129 Example: This function is intended to be used in a fashion similar to
131 the following example:
132 if (getrusage(who, usage) < 0)
133 {
134 char message[3000];
135 explain_message_getrusage(message, sizeof(message), who,
136 usage);
137 fprintf(stderr, "%s\n", message);
138 exit(EXIT_FAILURE);
139 }
140 The above code example is available pre-packaged as the
142 explain_getrusage_or_die(3) function.
143 explain_message_errno_getrusage
145 void explain_message_errno_getrusage(char *message, int message_size,
146 int errnum, int who, struct rusage *usage);
147 The explain_message_errno_getrusage function is used to obtain an
149 explanation of an error returned by the getrusage(2) system call. The
150 least the message will contain is the value of strerror(errno), but
151 usually it will do much better, and indicate the underlying cause in
152 more detail.
153 message The location in which to store the returned message. If a suit‐
155 able message return buffer is supplied, this function is thread
156 safe.
157 message_size
159 The size in bytes of the location in which to store the
160 returned message.
161 errnum The error value to be decoded, usually obtained from the errno
163 global variable just before this function is called. This is
164 necessary if you need to call any code between the system call
165 to be explained and this function, because many libc functions
166 will alter the value of errno.
167 who The original who, exactly as passed to the getrusage(2) system
169 call.
170 usage The original usage, exactly as passed to the getrusage(2) sys‐
172 tem call.
173 Example: This function is intended to be used in a fashion similar to
175 the following example:
176 if (getrusage(who, usage) < 0)
177 {
178 int err = errno;
179 char message[3000];
180 explain_message_errno_getrusage(message, sizeof(message),
181 err, who, usage);
182 fprintf(stderr, "%s\n", message);
183 exit(EXIT_FAILURE);
184 }
185 The above code example is available pre-packaged as the
187 explain_getrusage_or_die(3) function.
188
190 getrusage(2)
191 get resource usage
192 explain_getrusage_or_die(3)
194 get resource usage and report errors
195
197 libexplain version 1.4
198 Copyright (C) 2013 Peter Miller
199 explain_getrusage(3)