getdate(3)

NUME
getdate, getdate_r - convertește un șir de caractere care conține data și ora într-un format de timp defalcat

BIBLIOTECA
Biblioteca C standard (libc, -lc)

SINOPSIS
#include <time.h>

struct tm *getdate(const char *string);

extern int getdate_err;

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

    Cerințe pentru macrocomenzi de testare a caracteristicilor pentru glibc (consultați feature_test_macros(7)):

getdate():
    _XOPEN_SOURCE >= 500

getdate_r():
    _GNU_SOURCE

DESCRIERE
Funcția getdate() convertește o reprezentare sub formă de șir a unei date și ore, conținută în tamponul indicat de string, într-o oră defalcată. Ora defalcată este stocată într-o structură tm, iar un indicator către această structură este returnat ca rezultat al funcției. Această structură tm este alocată în memoria statică și, în consecință, va fi suprascrisă de apeluri ulterioare către getdate().

Spre deosebire de strptime(3) (care are un argument format), getdate() utilizează formatele găsite în fișierul al cărui nume complet este specificat în variabila de mediu DATEMSK. Prima linie din fișier care corespunde șirului de caractere introdus este utilizată pentru conversie.

Potrivirea se face fără a ține cont de majuscule și minuscule. Spațiile albe inutile, fie în model, fie în șirul care urmează să fie convertit, sunt ignorate.

Specificațiile de conversie pe care le poate conține un model sunt cele date pentru strptime(3). O altă specificație de conversie este specificată în POSIX.1-2001:

%Z  Numele fusului orar. Acest lucru nu este implementat în glibc.

Când se specifică %Z, structura care conține ora defalcată este inițializată cu valori corespunzătoare orei curente în fusul orar specificat. În caz contrar, structura este inițializată cu ora defalcată corespunzătoare orei locale curente (ca urmare a apelului la localtime(3)).

Când se specifică doar ziua săptămânii, se consideră că ziua respectivă este prima zi de acest fel din ziua de azi sau din zilele următoare.

Când se specifică doar luna (și nu anul), se consideră că luna este prima lună egală cu sau ulterioară lunii curente. Dacă nu se specifică ziua, se consideră că este prima zi a lunii.

Când nu sunt specificate ora, minutul și secunda, se iau ora, minutul și secunda curente.

Dacă nu este specificată data, dar cunoaștem ora, atunci acea oră este considerată prima oră egală sau ulterioară orei curente.

getdate_r() este o extensie GNU care oferă o versiune reentrantă a getdate(). În loc să utilizeze o variabilă globală pentru a raporta erorile și un tampon static pentru a returna timpul defalcat, aceasta returnează erorile prin valoarea rezultatului funcției și returnează timpul defalcat rezultat în tamponul alocat de apelant, indicat de argumentul res.

VALOAREA RETURNATĂ
Când are succes, getdate() returnează un indicator către o structură struct tm. În caz contrar, returnează NULL și definește variabila globală getdate_err la unul dintre numerele de eroare prezentate mai jos. Modificările aduse errno sunt nespecificate.

În caz de succes, getdate_r() returnează 0; în caz de eroare, returnează unul dintre numerele de eroare prezentate mai jos.

ERORI-IEȘIRE
Următoarele erori sunt returnate prin getdate_err (pentru getdate()) sau ca rezultat al funcției (pentru getdate_r()):

1   Variabila de mediu DATEMSK nu este definită sau valoarea sa este un șir gol.

2   Fișierul şablon specificat de DATEMSK nu poate fi deschis pentru citire.

3   Nu s-au putut obține informații despre starea fișierului.

4   Fișierul șablon nu este un fișier obișnuit.

5   A apărut o eroare la citirea fișierului șablon.

6   Alocarea memoriei a eșuat (memorie insuficientă disponibilă).

7   Nu există nicio linie în fișier care să corespundă cu intrarea.

8   Specificație de intrare nevalidă.

MEDIU

DATEMSK
    Fișier care conține modele de format.

TZ
LC_TIME
    Variabilele utilizate de strptime(3).

ATRIBUTE
Pentru o explicație a termenilor folosiți în această secțiune, a se vedea attributes(7).
Interfață | Atribut | Valoare
getdate() | Siguranța firelor | MT-Unsafe race:getdate env locale
getdate_r() | Siguranța firelor | MT-Safe env locale

VERSIUNI
Specificația POSIX.1 pentru strptime(3) conține specificații de conversie care utilizează modificatorul %E sau %O, în timp ce astfel de specificații nu sunt furnizate pentru getdate(). În glibc, getdate() este implementată utilizând strptime(3), astfel încât ambele să accepte exact aceleași conversii.

STANDARDE
POSIX.1-2008.

ISTORIC
POSIX.1-2001.

EXEMPLE
Programul de mai jos apelează getdate() pentru fiecare dintre argumentele sale din linia de comandă și, pentru fiecare apel, afișează valorile din câmpurile structurii tm returnate. Următoarea sesiune shell demonstrează funcționarea programului:

    $ TFILE=$PWD/tfile
    $ echo '%A' > $TFILE       # Numele complet al zilei săptămânii
    $ echo '%T' >> $TFILE      # Ora (HH:MM:SS)
    $ echo '%F' >> $TFILE      # Data ISO (AAAA-LL-ZZ)
    $ 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

  Sursa programului
    #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);
    }

CONSULTAȚI ȘI
time(2), localtime(3), setlocale(3), strftime(3), strptime(3)

TRADUCERE
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>

Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 (https://www.gnu.org/licenses/gpl-3.0.html) sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.

Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.