GETDATE(3)

BEZEICHNUNG
getdate - Berechnet aus einer Zeichenkette eine struct tm

ÜBERSICHT
#define _XOPEN_SOURCE
#define _XOPEN_SOURCE_EXTENDED
#include <time.h>

struct tm *getdate (const char *string);

extern int getdate_err;

#define _GNU_SOURCE
#include <time.h>

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

BESCHREIBUNG
Die Funktion getdate() übersetzt die Zeichenkette, auf die string zeigt, in eine Struktur tm, die zurückgegeben wird. Diese tm-Struktur kann in statischem Speicher liegen, so dass sie beim nächsten Aufruf überschrieben wird. Im Gegensatz zu strptime(3), (die ein Argument format hat), verwendet getdate() die Formate, die es in der Datei findet, dessen vollständiger Pfadname in der Umgebungsvariable DATEMSK angegeben ist. Die erste Zeile in dieser Datei, die auf die angegebene Zeichenkette passt, wird für die Übersetzung verwendet. Dabei wird nicht zwischen Groß- und Kleinbuchstaben unterschieden. Überflüssige Leerzeichen, sowohl in den Mustern in der Datei als auch in der Zeichenkette, die konvertiert werden soll, werden ignoriert. Die Übersetzungs-Spezifikationen, die ein Muster enthalten darf, entsprechen den bei strptime(3) angegebenen. Eine weitere Spezifikation, die akzeptiert wird, ist:

%Z  Name der Zeitzone

Wenn %Z verwendet wird, wird der Rückgabewert mit der heruntergebrochenen Zeit der aktuellen Zeit in der derzeitigen Zeitzone initialisiert,. Ansonsten wird er mit der heruntergebrochenen Zeit der aktuellen lokalen Zeit initialisiert.

Wenn nur ein Wochentag angegeben wurde, wird er als erster solcher Tag nach dem heutigen Tag angesehen.

Wenn ausschließlich der Monat angegeben wird (und kein Jahr), wird der erste gleichnamige Monat genommen, der dem aktuellen Monat entspricht oder einem nachfolgenden. Wenn kein Tag angegeben wird, wird der erste Tag des Monats angenommen.

Wenn keine Stunde, Minute und Sekunde angegeben wird, werden die aktuelle Stunde, Minute und Sekunden genommen.

Wenn kein Datum angegeben wird, jedoch die Stunde bekannt ist, dann wird die Stunde genommen, die der aktuellen oder einer späteren entspricht.

RÜCKGABEWERT
Wenn die Funktion erfolgreich war, gibt sie einen Zeiger zu einem struct tm zurück. Ansonsten wird NULL zurückgegeben und die globale Variable getdate_err gesetzt. Änderungen an errno sind nicht spezifiziert. Die folgenden Werte für getdate_err sind definiert:

1   Die Umgebungsvariable DATEMSK ist NULL oder nicht definiert.

2   Die Datei konnte nicht gelesen werden.

3   Der Dateistatus konnte nicht ermittelt werden.

4   Die Datei ist keine reguläre Datei.

5   Es ist ein Lesefehler aufgetreten.

6   Es ist nicht ausreichend Speicher verfügbar.

7   Keine Zeile in der Datei passt zur Zeichenkette.

8   Ungültige Eingabe wie z.B. 31 Februar oder eine Zeit die sich nicht als time_t dargestellen lässt (Sekunden seit 01.01.1970 00:00:00 UTC)

BEMERKUNGEN
Da getdate() nicht reentrant ist, da getdate_err verwendet sowie ein statischer Speicherplatz als Rückgabewert genommen wird, bietet die glibc eine Thread-sichere Variante. Die Funktionalität ist die gleiche. Das Ergebnis wird ein einem Puffer zurückgegeben, auf den res zeigt. Im Fall eines Fehlers, ist der Rückgabewert nicht-null mit den gleichen Werten wie oben für getdate_err angegeben.

Die Spezifikation POSIX 1003.1-2001 für strptime() enthält Übersetzungs-Spezifikationen, die die Modifizierer %E und %O verwenden, während solche Spezifikationen nicht für getdate() angegeben sind. Die Implementierung von getdate() der glibc verwendet strptime(), so dass automatisch genau die gleiche Übersetzung von beiden unterstützt wird.

Die glibc-Implementierung unterstÜtzt die Übersetzungs-Spezifikation %Z nicht.

UMGEBUNG

DATEMSK
    Datei, die Format-Muster enthält.

TZ, LC_TIME
    Variablen, die von strptime() verwendet werden.

BEISPIEL
Dieses Beispiel verdeutlicht die Anwendung, es ist nicht in der originalen Manpage enthalten.
#!/bin/sh
#
# sample script to create a file wirh possible
# date representations
#
cat >.date <<EOF
%m
%A %B %d, %Y, %H:%M:%S
%A
%B
%m/%d/%y %I %p
%d, %m, %Y %H:%M
at %A the %dst of %B in %Y
run job at %I %p, %B %dnd
&A den %d. %B %Y %H.%M Uhr
EOF
DATEMSK=.date
export DATEMSK
#include <stdio.h>
#include <time.h>
void daterr(int err)
{
  switch(err) {
    case 1:  printf ("The DATEMSK environment variable is null or undefined.);break;
    case 2:  printf ("The template file cannot be opened for reading.);break;
    case 3:  printf ("Failed to get file status information.);break;
    case 4:  printf ("The template file is not a regular file.);break;
    case 5:  printf ("An error is encountered while reading the template file.);break;
    case 6:  printf ("Memory allocation failed (not enough memory available.);break;
    case 7:  printf ("There is no line in the template that matches the input.);break;
    case 8:  printf ("Invalid input specification);break;
    default: printf ("unknown error);
  }
  exit(1);
}
int main()
{
  struct tm *tm;
  char buf[512];
  tm = getdate ("11/27/86");
  if (getdate_err != 0) daterr (getdate_err);
  strftime (buf, sizeof (buf)/sizeof (buf[0]), "%a %Y %H:%M:%S,tm);
  printf ("%s", buf);
}

KONFORM ZU
ISO 9899, POSIX 1003.1-2001

SIEHE AUCH
localtime(3), strftime(3), strptime(3), time(3).