r24780: More work allowing libutil to be used by external users.
[kai/samba.git] / source4 / lib / util / time.h
1 /* 
2    Unix SMB/CIFS implementation.
3    time utility functions
4    
5    This program is free software; you can redistribute it and/or modify
6    it under the terms of the GNU General Public License as published by
7    the Free Software Foundation; either version 3 of the License, or
8    (at your option) any later version.
9    
10    This program is distributed in the hope that it will be useful,
11    but WITHOUT ANY WARRANTY; without even the implied warranty of
12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13    GNU General Public License for more details.
14    
15    You should have received a copy of the GNU General Public License
16    along with this program.  If not, see <http://www.gnu.org/licenses/>.
17 */
18
19 #ifndef _SAMBA_TIME_H_
20 #define _SAMBA_TIME_H_
21
22 /* 64 bit time (100 nanosec) 1601 - cifs6.txt, section 3.5, page 30, 4 byte aligned */
23 typedef uint64_t NTTIME;
24
25 /**
26  External access to time_t_min and time_t_max.
27 **/
28 _PUBLIC_ time_t get_time_t_max(void);
29
30 /**
31 a gettimeofday wrapper
32 **/
33 _PUBLIC_ void GetTimeOfDay(struct timeval *tval);
34
35 /**
36 interpret an 8 byte "filetime" structure to a time_t
37 It's originally in "100ns units since jan 1st 1601"
38 **/
39 _PUBLIC_ time_t nt_time_to_unix(NTTIME nt);
40
41 /**
42 put a 8 byte filetime from a time_t
43 This takes GMT as input
44 **/
45 _PUBLIC_ void unix_to_nt_time(NTTIME *nt, time_t t);
46
47 /**
48 check if it's a null unix time
49 **/
50 _PUBLIC_ bool null_time(time_t t);
51
52 /**
53 check if it's a null NTTIME
54 **/
55 _PUBLIC_ bool null_nttime(NTTIME t);
56
57 /**
58 put a dos date into a buffer (time/date format)
59 This takes GMT time and puts local time in the buffer
60 **/
61 _PUBLIC_ void push_dos_date(uint8_t *buf, int offset, time_t unixdate, int zone_offset);
62
63 /**
64 put a dos date into a buffer (date/time format)
65 This takes GMT time and puts local time in the buffer
66 **/
67 _PUBLIC_ void push_dos_date2(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
68
69 /**
70 put a dos 32 bit "unix like" date into a buffer. This routine takes
71 GMT and converts it to LOCAL time before putting it (most SMBs assume
72 localtime for this sort of date)
73 **/
74 _PUBLIC_ void push_dos_date3(uint8_t *buf,int offset,time_t unixdate, int zone_offset);
75
76 /**
77   create a unix date (int GMT) from a dos date (which is actually in
78   localtime)
79 **/
80 _PUBLIC_ time_t pull_dos_date(const uint8_t *date_ptr, int zone_offset);
81
82 /**
83 like make_unix_date() but the words are reversed
84 **/
85 _PUBLIC_ time_t pull_dos_date2(const uint8_t *date_ptr, int zone_offset);
86
87 /**
88   create a unix GMT date from a dos date in 32 bit "unix like" format
89   these generally arrive as localtimes, with corresponding DST
90 **/
91 _PUBLIC_ time_t pull_dos_date3(const uint8_t *date_ptr, int zone_offset);
92
93 /**
94 return a HTTP/1.0 time string
95 **/
96 _PUBLIC_ char *http_timestring(TALLOC_CTX *mem_ctx, time_t t);
97
98 /**
99  Return the date and time as a string
100 **/
101 _PUBLIC_ char *timestring(TALLOC_CTX *mem_ctx, time_t t);
102
103 /**
104   return a talloced string representing a NTTIME for human consumption
105 */
106 _PUBLIC_ const char *nt_time_string(TALLOC_CTX *mem_ctx, NTTIME nt);
107
108 /**
109   put a NTTIME into a packet
110 */
111 _PUBLIC_ void push_nttime(uint8_t *base, uint16_t offset, NTTIME t);
112
113 /**
114   pull a NTTIME from a packet
115 */
116 _PUBLIC_ NTTIME pull_nttime(uint8_t *base, uint16_t offset);
117
118 /**
119   parse a nttime as a large integer in a string and return a NTTIME
120 */
121 _PUBLIC_ NTTIME nttime_from_string(const char *s);
122
123 /**
124   return (tv1 - tv2) in microseconds
125 */
126 _PUBLIC_ int64_t usec_time_diff(struct timeval *tv1, struct timeval *tv2);
127
128 /**
129   return a zero timeval
130 */
131 _PUBLIC_ struct timeval timeval_zero(void);
132
133 /**
134   return true if a timeval is zero
135 */
136 _PUBLIC_ bool timeval_is_zero(const struct timeval *tv);
137
138 /**
139   return a timeval for the current time
140 */
141 _PUBLIC_ struct timeval timeval_current(void);
142
143 /**
144   return a timeval struct with the given elements
145 */
146 _PUBLIC_ struct timeval timeval_set(uint32_t secs, uint32_t usecs);
147
148 /**
149   return a timeval ofs microseconds after tv
150 */
151 _PUBLIC_ struct timeval timeval_add(const struct timeval *tv,
152                            uint32_t secs, uint32_t usecs);
153
154 /**
155   return the sum of two timeval structures
156 */
157 struct timeval timeval_sum(const struct timeval *tv1,
158                            const struct timeval *tv2);
159
160 /**
161   return a timeval secs/usecs into the future
162 */
163 _PUBLIC_ struct timeval timeval_current_ofs(uint32_t secs, uint32_t usecs);
164
165 /**
166   compare two timeval structures. 
167   Return -1 if tv1 < tv2
168   Return 0 if tv1 == tv2
169   Return 1 if tv1 > tv2
170 */
171 _PUBLIC_ int timeval_compare(const struct timeval *tv1, const struct timeval *tv2);
172
173 /**
174   return true if a timer is in the past
175 */
176 _PUBLIC_ bool timeval_expired(const struct timeval *tv);
177
178 /**
179   return the number of seconds elapsed between two times
180 */
181 _PUBLIC_ double timeval_elapsed2(const struct timeval *tv1, const struct timeval *tv2);
182
183 /**
184   return the number of seconds elapsed since a given time
185 */
186 _PUBLIC_ double timeval_elapsed(const struct timeval *tv);
187
188 /**
189   return the lesser of two timevals
190 */
191 _PUBLIC_ struct timeval timeval_min(const struct timeval *tv1,
192                            const struct timeval *tv2);
193
194 /**
195   return the greater of two timevals
196 */
197 _PUBLIC_ struct timeval timeval_max(const struct timeval *tv1,
198                            const struct timeval *tv2);
199
200 /**
201   return the difference between two timevals as a timeval
202   if tv1 comes after tv2, then return a zero timeval
203   (this is *tv2 - *tv1)
204 */
205 _PUBLIC_ struct timeval timeval_until(const struct timeval *tv1,
206                              const struct timeval *tv2);
207
208 /**
209   convert a timeval to a NTTIME
210 */
211 _PUBLIC_ NTTIME timeval_to_nttime(const struct timeval *tv);
212
213 /**
214   convert a NTTIME to a timeval
215 */
216 _PUBLIC_ void nttime_to_timeval(struct timeval *tv, NTTIME t);
217
218 /**
219   return the UTC offset in seconds west of UTC, or 0 if it cannot be determined
220  */
221 _PUBLIC_ int get_time_zone(time_t t);
222
223
224
225 #endif /* _SAMBA_TIME_H_ */