.\"  Copyright (c) 2001 Walter Harms <walter.harms@informatik.uni-oldenburg.de>
.\"
.\"  This program is free software; you can redistribute it and/or modify
.\"  it under the terms of the GNU General Public License as published by
.\"  the Free Software Foundation; version 2 dated June, 1991.
.\"
.\"  This program is distributed in the hope that it will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"
.\"  You should have received a copy of the GNU General Public License
.\"  along with this program;  if not, write to the Free Software
.\"  Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111, USA.
.\"
.\"  2001-12-29: Updated to upstream 2001-12-26 by Martin Schulze <joey@infodrom.org>
.\"
.TH GETDATE 3 "26. Dezember 2001" "" "Bibliotheksfunktionen"
.SH BEZEICHNUNG
getdate \- Berechnet aus einer Zeichenkette eine struct tm
.br
.SH ÜBERSICHT
.B "#define _XOPEN_SOURCE"
.br
.B "#define _XOPEN_SOURCE_EXTENDED
.br
.B "#include <time.h>"
.sp
.BI "struct tm *getdate (const char *" string ");"
.sp
.BI "extern int getdate_err;"
.sp 2
.B "#define _GNU_SOURCE"
.br
.B "#include <time.h>"
.sp
.BI "int getdate_r (const char *" string ", struct tm *" res ");"
.br
.SH BESCHREIBUNG
Die Funktion
.B getdate() 
übersetzt die Zeichenkette, auf die
.I 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
.BR strptime (3),
(die ein Argument
.I format
hat),
verwendet
.B getdate()
die Formate, die es in der Datei findet, dessen vollständiger Pfadname
in der Umgebungsvariable
.B 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
.BR strptime (3)
angegebenen.
Eine weitere Spezifikation, die akzeptiert wird, ist:
.TP
.B %Z
Name der Zeitzone
.LP
Wenn
.B %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.
.LP
Wenn nur ein Wochentag angegeben wurde, wird er als erster solcher Tag
nach dem heutigen Tag angesehen.
.LP
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.
.LP
Wenn keine Stunde, Minute und Sekunde angegeben wird, werden die
aktuelle Stunde, Minute und Sekunden genommen.
.LP
Wenn kein Datum angegeben wird, jedoch die Stunde bekannt ist, dann
wird die Stunde genommen, die der aktuellen oder einer späteren entspricht.
.SH "RÜCKGABEWERT"
Wenn die Funktion erfolgreich war, gibt sie einen Zeiger zu einem
.B "struct tm"
zurück.
Ansonsten wird NULL zurückgegeben und die globale Variable
.B getdate_err
gesetzt.
Änderungen an
.I errno
sind nicht spezifiziert.  Die folgenden Werte für
.B getdate_err
sind definiert:
.TP 4n
.B 1
Die Umgebungsvariable DATEMSK ist NULL oder nicht definiert.
.TP
.B 2
Die Datei konnte nicht gelesen werden.
.TP
.B 3
Der Dateistatus konnte nicht ermittelt werden.
.TP
.B 4
Die Datei ist keine reguläre Datei.
.TP
.B 5
Es ist ein Lesefehler aufgetreten.
.TP
.B 6
Es ist nicht ausreichend Speicher verfügbar.
.TP
.B 7
Keine Zeile in der Datei passt zur Zeichenkette.
.TP
.B 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)
.SH BEMERKUNGEN
Da
.B getdate() 
nicht reentrant ist, da
.B 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
.I res
zeigt.
Im Fall eines Fehlers, ist der Rückgabewert nicht-null mit den
gleichen Werten wie oben für
.I getdate_err
angegeben.
.LP
Die Spezifikation POSIX 1003.1-2001 für
.B strptime()
enthält Übersetzungs-Spezifikationen, die die Modifizierer
.B %E
und
.B %O
verwenden, während solche Spezifikationen nicht für
.B getdate()
angegeben sind.
Die Implementierung von
.B getdate()
der glibc verwendet
.BR strptime() ,
so dass automatisch genau die gleiche Übersetzung von beiden
unterstützt wird.
.LP
Die glibc-Implementierung unterstÜtzt die Übersetzungs-Spezifikation
.B %Z
nicht.
.SH UMGEBUNG
.TP
.B DATEMSK 
Datei, die Format-Muster enthält.
.TP
.BR TZ ", " LC_TIME 
Variablen, die von \fBstrptime()\fP verwendet werden.
.SH BEISPIEL
Dieses Beispiel verdeutlicht die Anwendung, es ist nicht in der
originalen Manpage enthalten.

.nf
#!/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.\n");break;
    case 2:  printf ("The template file cannot be opened for reading.\n");break;
    case 3:  printf ("Failed to get file status information.\n");break;
    case 4:  printf ("The template file is not a regular file.\n");break;
    case 5:  printf ("An error is encountered while reading the template file.\n");break;
    case 6:  printf ("Memory allocation failed (not enough memory available.\n");break;
    case 7:  printf ("There is no line in the template that matches the input.\n");break;
    case 8:  printf ("Invalid input specification\n");break;
    default: printf ("unknown error\n");
  }
  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\n",tm);
  printf ("%s", buf);
}
.fi
.SH "KONFORM ZU"
ISO 9899, POSIX 1003.1-2001
.SH "SIEHE AUCH"
.BR localtime (3),
.BR strftime (3),
.BR strptime (3),
.BR time (3).