1.\"	$NetBSD: parse_time.3,v 1.1.1.2 2011/04/14 14:09:30 elric Exp $
2.\"
3.\" Copyright (c) 2004 Kungliga Tekniska Högskolan
4.\" (Royal Institute of Technology, Stockholm, Sweden).
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\"
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\"
14.\" 2. Redistributions in binary form must reproduce the above copyright
15.\"    notice, this list of conditions and the following disclaimer in the
16.\"    documentation and/or other materials provided with the distribution.
17.\"
18.\" 3. Neither the name of the Institute nor the names of its contributors
19.\"    may be used to endorse or promote products derived from this software
20.\"    without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\" Id
34.\"
35.Dd October 31, 2004
36.Dt PARSE_TIME 3
37.Os
38.Sh NAME
39.Nm parse_time ,
40.Nm print_time_table ,
41.Nm unparse_time ,
42.Nm unparse_time_approx ,
43.Nd parse and unparse time intervals
44.Sh LIBRARY
45The roken library (libroken, -lroken)
46.Sh SYNOPSIS
47.Fd #include <parse_time.h>
48.Ft int
49.Fn parse_time "const char *timespec" "const char *def_unit"
50.Ft void
51.Fn print_time_table "FILE *f"
52.Ft size_t
53.Fn unparse_time "int seconds" "char *buf" "size_t len"
54.Ft size_t
55.Fn unparse_time_approx "int seconds" "char *buf" "size_t len"
56.Sh DESCRIPTION
57The
58.Fn parse_time
59function converts a the period of time specified in
60into a number of seconds.
61The
62.Fa timespec
63can be any number of
64.Aq number unit
65pairs separated by comma and whitespace. The number can be
66negative. Number without explicit units are taken as being
67.Fa def_unit .
68.Pp
69The
70.Fn unparse_time
71and
72.Fn unparse_time_approx
73does the opposite of
74.Fn parse_time ,
75that is they take a number of seconds and express that as human
76readable string.
77.Fa unparse_time
78produces an exact time, while
79.Fa unparse_time_approx
80restricts the result to only include one units.
81.Pp
82.Fn print_time_table
83prints a descriptive list of available units on the passed file
84descriptor.
85.Pp
86The possible units include:
87.Bl -tag -width "month" -compact -offset indent
88.It Li second , s
89.It Li minute , m
90.It Li hour , h
91.It day
92.It week
93seven days
94.It month
9530 days
96.It year
97365 days
98.El
99.Pp
100Units names can be arbitrarily abbreviated (as long as they are
101unique).
102.Sh RETURN VALUES
103.Fn parse_time
104returns the number of seconds that represents the expression in
105.Fa timespec
106or -1 on error.
107.Fn unparse_time
108and
109.Fn unparse_time_approx
110return the number of characters written to
111.Fa buf .
112if the return value is greater than or equal to the
113.Fa len
114argument, the string was too short and some of the printed characters
115were discarded.
116.Sh EXAMPLES
117.Bd -literal
118#include <stdio.h>
119#include <parse_time.h>
120
121int
122main(int argc, char **argv)
123{
124    int i;
125    int result;
126    char buf[128];
127    print_time_table(stdout);
128    for (i = 1; i < argc; i++) {
129	result = parse_time(argv[i], "second");
130	if(result == -1) {
131	    fprintf(stderr, "%s: parse error\\n", argv[i]);
132	    continue;
133	}
134	printf("--\\n");
135	printf("parse_time = %d\\n", result);
136	unparse_time(result, buf, sizeof(buf));
137	printf("unparse_time = %s\\n", buf);
138	unparse_time_approx(result, buf, sizeof(buf));
139	printf("unparse_time_approx = %s\\n", buf);
140    }
141    return 0;
142}
143.Ed
144.Bd -literal
145$ ./a.out "1 minute 30 seconds" "90 s" "1 y -1 s"
1461   year = 365 days
1471  month = 30 days
1481   week = 7 days
1491    day = 24 hours
1501   hour = 60 minutes
1511 minute = 60 seconds
1521 second
153--
154parse_time = 90
155unparse_time = 1 minute 30 seconds
156unparse_time_approx = 1 minute
157--
158parse_time = 90
159unparse_time = 1 minute 30 seconds
160unparse_time_approx = 1 minute
161--
162parse_time = 31535999
163unparse_time = 12 months 4 days 23 hours 59 minutes 59 seconds
164unparse_time_approx = 12 months
165.Ed
166.Sh BUGS
167Since
168.Fn parse_time
169returns -1 on error there is no way to parse "minus one second".
170Currently "s" at the end of units is ignored. This is a hack for
171English plural forms. If these functions are ever localised, this
172scheme will have to change.
173.\".Sh SEE ALSO
174.\".Xr parse_bytes 3
175.\".Xr parse_units 3
176