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