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

NAME

6       explain_ftime - explain ftime(3) errors
7

SYNOPSIS

9       #include <libexplain/ftime.h>
10       const char *explain_ftime(struct timeb *tp);
11       const char *explain_errno_ftime(int errnum, struct timeb *tp);
12       void explain_message_ftime(char *message, int message_size, struct
13       timeb *tp);
14       void explain_message_errno_ftime(char *message, int message_size, int
15       errnum, struct timeb *tp);
16

DESCRIPTION

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

SEE ALSO

169       ftime(3)
170               return date and time
171
172       explain_ftime_or_die(3)
173               return date and time and report errors
174
176       libexplain version 0.40
177       Copyright (C) 2009 Peter Miller
178
179
180
181                                                              explain_ftime(3)
Impressum