.\"  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 zurckgegeben wird.
Diese tm-Struktur kann in statischem Speicher liegen, so da sie beim
nchsten 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 vollstndiger Pfadname
in der Umgebungsvariable
.B DATEMSK
angegeben ist.
Die erste Zeile in dieser Datei, die auf die angegebene Zeichenkette
pat, wird fr die bersetzung verwendet.

Dabei wird nicht zwischen Gro- und Kleinbuchstaben unterschieden.
berflssige 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 Rckgabewert 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 ausschlielich 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 spteren entspricht.
.SH "RCKGABEWERT"
Wenn die Funktion erfolgreich war, gibt sie einen Zeiger zu einem
.B "struct tm"
zurck.
Ansonsten wird NULL zurckgegeben und die globale Variable
.B getdate_err
gesetzt.
nderungen an
.I errno
sind nicht spezifiziert.  Die folgenden Werte fr
.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 regulre Datei.
.TP
.B 5
Es ist ein Lesefehler aufgetreten.
.TP
.B 6
Es ist nicht ausreichend Speicher verfgbar.
.TP
.B 7
Keine Zeile in der Datei pat zur Zeichenkette.
.TP
.B 8
Ungltige Eingabe wie z.B. 31 Februar oder eine Zeit die sich nicht
als time_t dargestellen lt (Sekunden seit 01.01.1970 00:00:00 UTC)
.SH BEMERKUNGEN
Da
.B getdate() 
nicht reentrant ist, da
.B getdate_err
verwendt wird sowie ein statischer Speicherplatz als Rckgabewert
genommen wird, bietet die glibc eine Thread-sichere Variante.
Die Funktionalitt ist die gleiche.  Das Ergebnis wird ein einem
Puffer zurckgegeben, auf den
.I res
zeigt.
Im Fall eines Fehlers, ist der Rckgabewert nicht-null mit den
gleichen Werten wie oben fr
.I getdate_err
angegeben.
.LP
Die Spezifikation POSIX 1003.1-2001 fr
.B strptime()
enthlt bersetzungs-Spezifikationen, die die Modifizierer
.B %E
und
.B %O
verwenden, whrend solche Spezifikationen nicht fr
.B getdate()
angegeben sind.
Die Implementierung von
.B getdate()
der glibc verwendet
.BR strptime() ,
so da automatisch genau die gleiche bersetzung von beiden
untersttzt wird.
.LP
Die glibc-Implementierung untersttzt die bersetzungs-Spezifikation
.B %Z
nicht.
.SH UMGEBUNG
.TP
.B DATEMSK 
Datei, die Format-Muster enthlt.
.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).