PARSE\_TIME(3) Library Functions Manual PARSE\_TIME(3)

# [NAME](#NAME)

`parse_time`, `print_time_table`, `unparse_time`, `unparse_time_approx`, — parse and unparse time intervals

# [LIBRARY](#LIBRARY)

The roken library (libroken, -lroken)

# [SYNOPSIS](#SYNOPSIS)

`#include <parse_time.h>`

`int`  
`parse_time`(`const char *timespec`, `const char *def_unit`);

`void`  
`print_time_table`(`FILE *f`);

`size_t`  
`unparse_time`(`int seconds`, `char *buf`, `size_t len`);

`size_t`  
`unparse_time_approx`(`int seconds`, `char *buf`, `size_t len`);

# [DESCRIPTION](#DESCRIPTION)

The [`parse_time`](#parse_time)() function converts the period of time specified into a number of seconds. The `timespec` can be any number of ⟨number unit⟩ pairs separated by comma and whitespace. The number can be negative. Numbers without explicit units are taken as being `def_unit`.

The [`unparse_time`](#unparse_time)() and [`unparse_time_approx`](#unparse_time_approx)() do the opposite of `parse_time`(), that is they take a number of seconds and express that as human readable strings. `unparse_time` produces an exact time, while `unparse_time_approx` restricts the result to include only one unit.

[`print_time_table`](#print_time_table)() prints a descriptive list of available units on the passed file descriptor.

The possible units include:

[`second`](#second), `s`

 

[`minute`](#minute), `m`

 

[`hour`](#hour), `h`

 

day

 

week

seven days

month

30 days

year

365 days

Units names can be arbitrarily abbreviated (as long as they are unique).

# [RETURN VALUES](#RETURN_VALUES)

`parse_time`() returns the number of seconds that represents the expression in `timespec` or -1 on error. `unparse_time`() and `unparse_time_approx`() return the number of characters written to `buf`. if the return value is greater than or equal to the `len` argument, the string was too short and some of the printed characters were discarded.

# [EXAMPLES](#EXAMPLES)

```
#include <stdio.h>
#include <parse_time.h>

int
main(int argc, char **argv)
{
    int i;
    int result;
    char buf[128];
    print_time_table(stdout);
    for (i = 1; i < argc; i++) {
	result = parse_time(argv[i], "second");
	if(result == -1) {
	    fprintf(stderr, "%s: parse error\n", argv[i]);
	    continue;
	}
	printf("--\n");
	printf("parse_time = %d\n", result);
	unparse_time(result, buf, sizeof(buf));
	printf("unparse_time = %s\n", buf);
	unparse_time_approx(result, buf, sizeof(buf));
	printf("unparse_time_approx = %s\n", buf);
    }
    return 0;
}
```

```
$ ./a.out "1 minute 30 seconds" "90 s" "1 y -1 s"
1   year = 365 days
1  month = 30 days
1   week = 7 days
1    day = 24 hours
1   hour = 60 minutes
1 minute = 60 seconds
1 second
--
parse_time = 90
unparse_time = 1 minute 30 seconds
unparse_time_approx = 1 minute
--
parse_time = 90
unparse_time = 1 minute 30 seconds
unparse_time_approx = 1 minute
--
parse_time = 31535999
unparse_time = 12 months 4 days 23 hours 59 minutes 59 seconds
unparse_time_approx = 12 months
```

# [BUGS](#BUGS)

Since `parse_time`() returns -1 on error there is no way to parse "minus one second". Currently "s" at the end of units is ignored. This is a hack for English plural forms. If these functions are ever localised, this scheme will have to change.

November 17, 2013 HEIMDAL

---

Document: parse_time(3) from heimdal 7.8.0-r52 (Chainguard OS)
Source: https://github.com/heimdal/heimdal