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