1explain_truncate(3) Library Functions Manual explain_truncate(3)
2
6 explain_truncate - explain truncate(2) errors
7
9 #include <libexplain/truncate.h>
10 const char *explain_truncate(const char *pathname, long long length);
11 const char *explain_errno_truncate(int errnum, const char *pathname,
12 long long length);
13 void explain_message_truncate(char *message, int message_size, const
14 char *pathname, long long length);
15 void explain_message_errno_truncate(char *message, int message_size,
16 int errnum, const char *pathname, long long length);
17
19 These functions may be used to obtain explanations for errors returned
20 by the truncate(2) system call.
21 explain_truncate
23 const char *explain_truncate(const char *pathname, long long length);
24 The explain_truncate function is used to obtain an explanation of an
26 error returned by the truncate(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 This function is intended to be used in a fashion similar to the fol‐
34 lowing example:
35 if (truncate(pathname, length) < 0)
36 {
37 fprintf(stderr, "%s\n", explain_truncate(pathname, length));
38 exit(EXIT_FAILURE);
39 }
40 pathname
42 The original pathname, exactly as passed to the truncate(2)
43 system call.
44 length The original length, exactly as passed to the truncate(2) sys‐
46 tem call.
47 Returns:
49 The message explaining the error. This message buffer is
50 shared by all libexplain functions which do not supply a buffer
51 in their argument list. This will be overwritten by the next
52 call to any libexplain function which shares this buffer,
53 including other threads.
54 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 explain_errno_truncate
59 const char *explain_errno_truncate(int errnum, const char *pathname,
60 long long length);
61 The explain_errno_truncate function is used to obtain an explanation of
63 an error returned by the truncate(2) system call. The least the mes‐
64 sage will contain is the value of strerror(errnum), but usually it will
65 do much better, and indicate the underlying cause in more detail.
66 This function is intended to be used in a fashion similar to the fol‐
68 lowing example:
69 if (truncate(pathname, length) < 0)
70 {
71 int err = errno;
72 fprintf(stderr, "%s\n", explain_errno_truncate(err, pathname, length));
73 exit(EXIT_FAILURE);
74 }
75 errnum The error value to be decoded, usually obtained from the errno
77 global variable just before this function is called. This is
78 necessary if you need to call any code between the system call
79 to be explained and this function, because many libc functions
80 will alter the value of errno.
81 pathname
83 The original pathname, exactly as passed to the truncate(2)
84 system call.
85 length The original length, exactly as passed to the truncate(2) sys‐
87 tem call.
88 Returns:
90 The message explaining the error. This message buffer is
91 shared by all libexplain functions which do not supply a buffer
92 in their argument list. This will be overwritten by the next
93 call to any libexplain function which shares this buffer,
94 including other threads.
95 Note: This function is not thread safe, because it shares a return buf‐
97 fer across all threads, and many other functions in this library.
98 explain_message_truncate
100 void explain_message_truncate(char *message, int message_size, const
101 char *pathname, long long length);
102 The explain_message_truncate function may be used to obtain an expla‐
104 nation of an error returned by the truncate(2) system call. The least
105 the message will contain is the value of strerror(errno), but usually
106 it will do much better, and indicate the underlying cause in more
107 detail.
108 The errno global variable will be used to obtain the error value to be
110 decoded.
111 This function is intended to be used in a fashion similar to the fol‐
113 lowing example:
114 if (truncate(pathname, length) < 0)
115 {
116 char message[3000];
117 explain_message_truncate(message, sizeof(message), pathname, length);
118 fprintf(stderr, "%s\n", message);
119 exit(EXIT_FAILURE);
120 }
121 message The location in which to store the returned message. If a
123 suitable message return buffer is supplied, this function is
124 thread safe.
125 message_size
127 The size in bytes of the location in which to store the
128 returned message.
129 pathname
131 The original pathname, exactly as passed to the truncate(2)
132 system call.
133 length The original length, exactly as passed to the truncate(2) sys‐
135 tem call.
136 explain_message_errno_truncate
138 void explain_message_errno_truncate(char *message, int message_size,
139 int errnum, const char *pathname, long long length);
140 The explain_message_errno_truncate function may be used to obtain an
142 explanation of an error returned by the truncate(2) system call. The
143 least the message will contain is the value of strerror(errnum), but
144 usually it will do much better, and indicate the underlying cause in
145 more detail.
146 This function is intended to be used in a fashion similar to the fol‐
148 lowing example:
149 if (truncate(pathname, length) < 0)
150 {
151 int err = errno;
152 char message[3000];
153 explain_message_errno_truncate(message, sizeof(message), err,
154 pathname, length);
155 fprintf(stderr, "%s\n", message);
156 exit(EXIT_FAILURE);
157 }
158 message The location in which to store the returned message. If a
160 suitable message return buffer is supplied, this function is
161 thread safe.
162 message_size
164 The size in bytes of the location in which to store the
165 returned message.
166 errnum The error value to be decoded, usually obtained from the errno
168 global variable just before this function is called. This is
169 necessary if you need to call any code between the system call
170 to be explained and this function, because many libc functions
171 will alter the value of errno.
172 pathname
174 The original pathname, exactly as passed to the truncate(2)
175 system call.
176 length The original length, exactly as passed to the truncate(2) sys‐
178 tem call.
179
181 truncate(2)
182 truncate a file to a specified length
183 explain_truncate_or_die(3)
185 truncate a file to a specified length and report errors
186
188 libexplain version 1.4
189 Copyright (C) 2008 Peter Miller
190 explain_truncate(3)