---
name: "unparse_time"
section: "3"
platform: "linux"
package: "heimdal-dev"
version: "7.8.git20221117.28daf24+dfsg-9+deb13u1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/unparse_time"
---

# unparse\_time(3)

parse and unparse time intervals

## NAME

**parse\_time**, **print\_time\_table**, **unparse\_time**, **unparse\_time\_approx**, – parse and unparse time intervals

## LIBRARY

The roken library (libroken, -lroken)

## 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

The **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**() and **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**() prints a descriptive list of available units on the passed file descriptor.

The possible units include:

- second, s

  - minute, m

  - 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

**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

```
#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

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.