getdate(3)

✨ getdate — bestie edition ✨

okay so this is getdate(3) from the Linux man-pages, and it's actually so useful — it turns a lil string like "Tuesday" into an actual broken-down time struct. The library here is the Standard C library (libc, -lc), so it's already sitting on your machine waiting for you 💖

---

🌸 NAME 🌸

getdate, getdate_r — convert a date-plus-time string to broken-down time. that's it, that's the whole job, and they ate 🫶

---

🎀 LIBRARY 🎀

Standard C library (libc, -lc)

---

💅 SYNOPSIS 💅

#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

int getdate_r(const char *restrict string, struct tm *restrict res);

⭐ Feature Test Macro Requirements for glibc

(if you wanna know how feature test macros work in general, peep feature_test_macros(7))

• getdate(): _XOPEN_SOURCE >= 500
• getdate_r(): _GNU_SOURCE

not me needing a whole macro just to unlock the function bestie 😭 that's just how POSIX do

---

🦋 DESCRIPTION 🦋

okay so getdate() takes a string representation of a date and time, chillin in the buffer pointed to by string, and converts it into a broken-down time. The broken-down time gets stored in a tm structure, and a pointer to that structure is what you get back as the function result. heads up though: this tm structure lives in static storage, so the next time you call getdate() it gets lowkey overwritten. no cap. copy it if you need it 💀

Now, and this is the part that makes getdate() different from strptime(3) — strptime(3) has a format argument, getdate() does not. Instead it uses the formats it finds in the file whose full pathname is sitting in the environment variable DATEMSK. The first line in that file that matches the input string is the one that gets used for the conversion. first match wins, periodt ✨

The matching is done case insensitively. Superfluous whitespace — whether it's in the pattern or in the string being converted — is just ignored. we love a chill parser 💅

The conversion specifications a pattern can contain are the ones given for strptime(3). Plus POSIX.1-2001 specifies one more:

• %Z — Timezone name. This is not implemented in glibc. yeah, sorry bestie, it's just not 🥲

When %Z is given, the structure containing the broken-down time is initialized with values corresponding to the current time in the given timezone. Otherwise, the structure is initialized to the broken-down time corresponding to the current local time (as by a call to localtime(3)).

Now the fill-in-the-blanks rules, and they're giving main character energy:

• When only the day of the week is given, the day is taken to be the first such day on or after today.
• When only the month is given (and no year), the month is taken to be the first such month equal to or after the current month. If no day is given, it's the first day of the month.
• When no hour, minute, and second are given, the current hour, minute, and second are taken.
• If no date is given, but we know the hour, then that hour is taken to be the first such hour equal to or after the current hour.

And then we have getdate_r() — a GNU extension that's the reentrant version of getdate(), and honestly it's the responsible one 🧚 Instead of using a global variable to report errors and a static buffer to return the broken-down time, it returns errors via the function result value, and returns the resulting broken-down time in the caller-allocated buffer pointed to by the argument res. so you bring your own buffer, you get your own error code, no globals, no drama 🌈

---

🔥 RETURN VALUE 🔥

When successful, getdate() returns a pointer to a struct tm. Otherwise it returns NULL and sets the global variable getdate_err to one of the error numbers shown below. Changes to errno are unspecified — so don't go reading errno for answers, bestie, read getdate_err 🙈

On success getdate_r() returns 0; on error it returns one of the error numbers shown below.

---

💀 ERRORS 💀

The following errors are returned via getdate_err (for getdate()) or as the function result (for getdate_r()):

1. The DATEMSK environment variable is not defined, or its value is an empty string.
2. The template file specified by DATEMSK cannot be opened for reading.
3. Failed to get file status information.
4. The template file is not a regular file.
5. An error was encountered while reading the template file.
6. Memory allocation failed (not enough memory available).
7. There is no line in the file that matches the input.
8. Invalid input specification.

memorize these, iykyk 👑

---

🌈 ENVIRONMENT 🌈

• DATEMSK — File containing format patterns.
• TZ
• LC_TIME

TZ and LC_TIME are variables used by strptime(3).

---

👑 ATTRIBUTES 👑

For an explanation of the terms used in this section, see attributes(7).

• getdate() — Thread safety: MT-Unsafe race:getdate env locale
• getdate_r() — Thread safety: MT-Safe env locale

see that? getdate_r() said MT-Safe, it's the icon, it's the moment 💅

---

⭐ VERSIONS ⭐

The POSIX.1 specification for strptime(3) contains conversion specifications using the %E or %O modifier, while such specifications are not given for getdate(). In glibc, getdate() is implemented using strptime(3), so that precisely the same conversions are supported by both. cute little implementation detail fr fr ✨

---

🎀 STANDARDS 🎀

POSIX.1-2008.

---

🌸 HISTORY 🌸

POSIX.1-2001.

---

🦋 EXAMPLES 🦋

The program below calls getdate() for each of its command-line arguments, and for each call displays the values in the fields of the returned tm structure. And here's a whole shell session showing it in action:

$ TFILE=$PWD/tfile
$ echo '%A' > $TFILE       # Full name of the day of the week
$ echo '%T' >> $TFILE      # Time (HH:MM:SS)
$ echo '%F' >> $TFILE      # ISO date (YYYY-MM-DD)
$ date
$ export DATEMSK=$TFILE
$ ./a.out Tuesday '2009-12-28' '12:22:33'
Sun Sep  7 06:03:36 CEST 2008
Call 1 ("Tuesday") succeeded:
    tm_sec   = 36
    tm_min   = 3
    tm_hour  = 6
    tm_mday  = 9
    tm_mon   = 8
    tm_year  = 108
    tm_wday  = 2
    tm_yday  = 252
    tm_isdst = 1
Call 2 ("2009-12-28") succeeded:
    tm_sec   = 36
    tm_min   = 3
    tm_hour  = 6
    tm_mday  = 28
    tm_mon   = 11
    tm_year  = 109
    tm_wday  = 1
    tm_yday  = 361
    tm_isdst = 0
Call 3 ("12:22:33") succeeded:
    tm_sec   = 33
    tm_min   = 22
    tm_hour  = 12
    tm_mday  = 7
    tm_mon   = 8
    tm_year  = 108
    tm_wday  = 0
    tm_yday  = 250
    tm_isdst = 1

🧚 Program source

#define _GNU_SOURCE
#include <stdio.h>
#include <stdlib.h>
#include <time.h>

int
main(int argc, char *argv[])
{
    struct tm *tmp;

    for (size_t j = 1; j < argc; j++) {
        tmp = getdate(argv[j]);

        if (tmp == NULL) {
            printf("Call %zu failed; getdate_err = %d\n",
                   j, getdate_err);
            continue;
        }

        printf("Call %zu (\"%s\") succeeded:\n", j, argv[j]);
        printf("    tm_sec   = %d\n", tmp->tm_sec);
        printf("    tm_min   = %d\n", tmp->tm_min);
        printf("    tm_hour  = %d\n", tmp->tm_hour);
        printf("    tm_mday  = %d\n", tmp->tm_mday);
        printf("    tm_mon   = %d\n", tmp->tm_mon);
        printf("    tm_year  = %d\n", tmp->tm_year);
        printf("    tm_wday  = %d\n", tmp->tm_wday);
        printf("    tm_yday  = %d\n", tmp->tm_yday);
        printf("    tm_isdst = %d\n", tmp->tm_isdst);
    }

    exit(EXIT_SUCCESS);
}

---

🫶 SEE ALSO 🫶

time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

---

okay that's the whole page bestie, go parse some dates 💖 this one's from Linux man-pages 6.20, dated 2026-02-08, and it's a getdate(3) moment. slay ✨👑