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

NAME

6       explain_stime - explain stime(2) errors
7

SYNOPSIS

9       #include <libexplain/stime.h>
10       const char *explain_stime(time_t *t);
11       const char *explain_errno_stime(int errnum, time_t *t);
12       void explain_message_stime(char *message, int message_size, time_t *t);
13       void explain_message_errno_stime(char *message, int message_size, int
14       errnum, time_t *t);
15

DESCRIPTION

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

SEE ALSO

167       stime(2)
168               set system time
169
170       explain_stime_or_die(3)
171               set system time and report errors
172
174       libexplain version 0.40
175       Copyright (C) 2009 Peter Miller
176
177
178
179                                                              explain_stime(3)
Impressum