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

NAME

6       explain_truncate - explain truncate(2) errors
7

SYNOPSIS

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

DESCRIPTION

19       These functions may be used to obtain explanations for errors  returned
20       by the truncate(2) system call.
21
22   explain_truncate
23       const char *explain_truncate(const char *pathname, long long length);
24
25       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
30       The errno global variable will be used to obtain the error value to  be
31       decoded.
32
33       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
41       pathname
42               The original pathname, exactly as  passed  to  the  truncate(2)
43               system call.
44
45       length  The  original length, exactly as passed to the truncate(2) sys‐
46               tem call.
47
48       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
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   explain_errno_truncate
59       const  char  *explain_errno_truncate(int  errnum, const char *pathname,
60       long long length);
61
62       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
67       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
76       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
82       pathname
83               The original pathname, exactly as  passed  to  the  truncate(2)
84               system call.
85
86       length  The  original length, exactly as passed to the truncate(2) sys‐
87               tem call.
88
89       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
96       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
99   explain_message_truncate
100       void  explain_message_truncate(char  *message,  int message_size, const
101       char *pathname, long long length);
102
103       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
109       The errno global variable will be used to obtain the error value to  be
110       decoded.
111
112       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
122       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
126       message_size
127               The size in bytes  of  the  location  in  which  to  store  the
128               returned message.
129
130       pathname
131               The  original  pathname,  exactly  as passed to the truncate(2)
132               system call.
133
134       length  The original length, exactly as passed to the truncate(2)  sys‐
135               tem call.
136
137   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
141       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
147       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
159       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
163       message_size
164               The  size  in  bytes  of  the  location  in  which to store the
165               returned message.
166
167       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
173       pathname
174               The original pathname, exactly as  passed  to  the  truncate(2)
175               system call.
176
177       length  The  original length, exactly as passed to the truncate(2) sys‐
178               tem call.
179

SEE ALSO

181       truncate(2)
182               truncate a file to a specified length
183
184       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
191
192
193                                                           explain_truncate(3)
Impressum