utimensat(2)

NAVN
utimensat, futimens - ændr filtidsstempler med nanosekund præcision

BIBLIOTEK
C-standardbibliotek (libc, -lc)

SYNOPSIS
#include <fcntl.h>            /* Definition af AT_*-konstanter */
#include <sys/stat.h>

int utimensat(int dirfd, const char *sti,
              const struct timespec times[_Nullable 2], int flag);
int futimens(int fd, const struct timespec times[_Nullable 2]);

    Feature Test Macro Requirements for glibc (se feature_test_macros(7)):

utimensat():
    Siden glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Før glibc 2.10:
        _ATFILE_SOURCE

futimens():
    Siden glibc 2.10:
        _POSIX_C_SOURCE >= 200809L
    Før glibc 2.10:
        _GNU_SOURCE

BESKRIVELSE
utimensat() og futimens() opdaterer tidsstemplerne for en fil med nanosekund præcision. Dette er i kontrast til den historiske utime(2) og utimes(2), der kun tillader sekund og mikrosekund præcision, respektivt, når filtidsstempler angives.

Med utimensat() er filen angivet via stinavnet i sti. Med futimens() er filen hvis tidsstempler skal opdateres angivet via en åben fildeskriptor, fd.

For begge kald, er de nye filtidsstempler angivet i tabellen times: times[0] angiver den nye »sidst tilgået« (atime); times[1] angiver den »sidst ændret« (mtime). Hver af elementerne i times angiver et tidspunt som antallet af sekunder og nanosekunder siden Epoch, 1970-01-01 00:00:00 +0000 (UTC). Denne information er formidlet i en timespec(3)-struktur.

Opdaterede filtidsstempler angives til den største værdi understøttet af filsystemet, der ikke er højere end det angivne tidspunkt.

Hvis feltet tv_nsec for en af timespec-strukturerne har den specielle værdi UTIME_NOW, så er det tilsvarende filtidsstempel angivet til den aktuelle tid. Hvis feltet tv_nsec for en af timespec-strukturerne har den specielle værdi UTIME_OMIT, så efterlades det tilsvarende filtidsstempel uændret. I begge disse tilfæde bliver værdien for det tilsvarende tv_sec-felt ignoreret.

Hvis times er NULL, så angives begge tidsstempler til den aktuelle tid.

Statusændringstidspunktet (ctime) vil blive angivet til den aktuelle tid, selv om andre tidsstempler ikke ændrer sig.

  Rettighedskrav
For at angive begge filtidsstempler til den aktuelle tid (dvs., times er NULL, eller begge tv_nsec-fetler angiver UTIME_NOW), enten:

•   kalderen skal have skriveadgang til filen;

•   kalderens effektive bruger-id skal matche ejeren af filen; eller

•   kalderen skal have passene privilegier.

For at lave en ændring udover angivelse af begge tidsstempler til den aktuelle tid (dvs., times er ikke NULL, og intet tv_nsec-felt er UTIME_NOW og intet tv_nsec-felt er UTIME_OMIT), enten betingelse 2 eller 3 ovenfor skal gælde.

Hvis begge tv_nsec-felter er angivet som UTIME_OMIT, så udføres der ingen tjek for filejerskab eller rettighed og filtidsstemplerne bliver ikke ændret, men andre fejlbetingelser kan stadig registreres.

  utimensat() detaljer
Hvis sti er relativ, så fortolkes det som standard relativt til mappen refereret til af den åbne fildeskriptor, dirfd (frem for relativt til den nuværende arbejdsmappe for den kaldende proces, som det gøres af utimes(2) for et relativt stinavn). Se openat(2) for en forklaring af hvorfor dette kan være nyttigt.

Hvis sti er relativ og dirfd er den specielle værdi AT_FDCWD, så fortolkes sti relativt til den nuværende arbejsmapppe for den kaldende proces (som utimes(2)).

Hvis sti er forældet, så ignoreres dirfd.

Argumentet flag er en bit-maske oprettet af ORing together zero eller flere af de følgende værdier defineret i <fcntl.h>:

AT_EMPTY_PATH (siden Linux 5.8)
    Hvis sti er en tom streng, arbejd på filen refereret til af dirfd (der kan være indhentet via open(2) O_PATH-flaget). I dette tilfælde kan dirfd referere til enhver filtype, ikke kun en mappe. Hvis dirfd er AT_FDCWD fungerer kaldet på den nuværende arbejdsmappe. Dette er flag er specifikt for Linux; definer _GNU_SOURCE for at hente dets definition.

AT_SYMLINK_NOFOLLOW
    Hvis sti angiver en symbolsk henvisning, så opdater tidsstemplerne for henvisningen, frem for filen hvortil der refereres.

RETURVÆRDI
Ved succes returnerer utimensat() og futimens() 0. Ved fejl returneres -1 og errno angives for at indikere fejlen.

FEJL

EACCES
    times er NULL, eller begge tv_nsec-værdier er UTIME_NOW, og det effektive bruger-id for kalderen matcher ikke ejeren af filen, kalderen skal ikke have skriveadgang til filen og kalderen er ikke privilegeret (Linux: har hverken kapaciteten CAP_FOWNER eller CAP_DAC_OVERRIDE).

EBADF
    (futimens()) fd er ikke en gyldig fildeskriptor.

EBADF
    utimensat()) sti er relativ men dirfd er ingen AT_FDCWD eller en gyldig fildeskriptor.

EFAULT
    times pegede mod en ugyldig adresse; eller, dirfd var AT_FDCWD, og sti er NULL eller en ugyldig adresse..

EINVAL
    Ugyldig værdi i flag.

EINVAL
    Ugyldig værdi i et af tv_nsec-felterne (værdi uden for interval [0, 999,999,999], og ikke UTIME_NOW eller UTIME_OMIT); eller en ugyldig værdi i et af tv_sec-felterne.

EINVAL
    path er NULL, dirfd er ikke AT_FDCWD, og flag indeholder AT_SYMLINK_NOFOLLOW.

ELOOP
    (utimensat()) For mange symbolske henvisninger blev mødt under opslag af sti.

ENAMETOOLONG
    (utimensat()) sti er for lang.

ENOENT
    (utimensat()) En komponent i sti refererer ikke til en eksisterende mappe eller fil, eller sti er ikke en tom streng.

ENOTDIR
    (utimensat()) sti er relativ, men dirfd er ingen AT_FDCWD eller en fildeskriptor refererende til en mappe; eller, en af præfikskomponenterne for sti er ikke en mappe.

EPERM
    Kalderen forsøgte at ændre en eller begge tidsstempler til en værdi anderledes end den nuværende tid, eller til at ændre en af tidsstemplerne til den nuværende tid, mens det andet tidsstempel efterlades uændret (dvs. times er ikke NULL; intet tv_nsec-felt er UTIME_NOW, og intet tv_nsec-felt er UTIME_OMIT) og enten:

    •   kalderens effektive bruger-id matcher ikke filejeren og kalderen er ikke privilegeret (Linux: har ikke kapaciteten CAP_FOWNER); eller,

    •   filen er markeret tilføj-kun eller uforanderlig (se chattr(1)).

EROFS
    Filen er på et skrivebeskyttet filsystem.

ESRCH
    (utimensat()) Søgetilladelse er nægtet for en af præfikskomponenterne i sti.

ATTRIBUTTER
For en forklaring på betingelserne i dette afsnit, se attributes(7).
Grænseflade | Attribut | Værdi
utimensat(), futimens() | Trådsikkerhed | MT-Safe

VERSIONER

  ABI-forskelle for C-bibliotek/kerne
På Linux er futimens() en biblioteksfunktion implementeret oven på systemkaldet utimensat(). For at understøtte dette implementerer Linux-systemkaldet utimensat() en funktion uden for standarden: hvis sti er NULL, så ændrer kaldet tidstemplerne for filen refereret til af fildeskriptoren dirfd (der kan referere til enhver filtype). Med brug af denne funktion bliver kaldet futimens(fd, times) implementeret som:

    utimensat(fd, NULL, times, 0);

Bemærk dog, at glibc-omslaget for utimensat() ikke tillader at sende NULL som værdien for sti: omslagsfunktionen returnerer i dette tilfælde fejlen EINVAL.

STANDARDER
POSIX.1-2024.

HISTORIK

utimensat()
    Linux 2.6.22, glibc 2.6. POSIX.1-2008.

futimens()
    glibc 2.6. POSIX.1-2008.

NOTER
utimensat() gør futimesat(2) forældet.

På Linux kan tidsstempler ikke ændret for en fil, der er markeret uforanderlig, og den eneste ændring tilladt for filer markeret tilføj-kun er at angive tidsstemplerne til den aktuelle tid. (Dette er konsistent med den historiske opførsel for utime(2) og utimes(2) på Linux).

Hvis begge tv_nsec-felter er angivet som UTIME_OMIT, så lykkes Linux-implementeringen af utimensat() selv om filen er refereret til af dirfd og sti ikke findes.

FEJL
Flere fejl plager utimensat() og futimens() før Linux 2.6.26. Disse fejl er enten manglende overholdelse af POSIX.1-kladdespecifikationen eller inkonsistens med historisk Linux-opførsel.

•   POSIX.1 nagiver at hvis et af tv_nsec-felterne har værdien UTIME_NOW eller UTIME_OMIT, så skal værdien for det tilsvarende tv_sec-felt ignoreres. I stedet er det krævet at værdien af tv_sec-feltet er 0 (eller at fejlen EINVAL følger).

•   Diverse fejl betyder i forhold til rettighedskontrol at i tilfældet hvor begge tv_nsec-felter er angivet til UTIME_NOW, så behandles det ikke altid som at angive times som NULL, og tilfældet hvor en tv_nsec-værdi er UTIME_NOW og den anden er UTIME_OMIT behandles ikke på samme måde som at angive times som en tekstsøger til en strukturtabel indeholdende arbitrære tidsværdier. Som et resutlat, i nogle tilfælde: a) filtidsstempler kan opdateres af en proces, der ikke burde have rettighed til at udføre opdateringer; b) filstempler kan ikke opdateres af en proces, der burde have rettighed til at udføre opdateirnger; og c) den forkerte errno-værdi returneres i tilfælde af en fejl.

•   POSIX.1 siger at en proces, der har skriveadgang til filen kan lave et kald med times som NULL, eller med times pegende til en strukturtabel hvori begge tv_nsec-felter er UTIME_NOW, for at opdatere begge tidsstempler til den aktuelle tid. futimens() tjekker i stedet om adgangstilstanden for fildeskriptoren tillader skrivning.

SE OGSÅ
chattr(1), touch(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), timespec(3), inode(7), path_resolution(7), symlink(7)

OVERSÆTTELSE
Oversættere af denne manual til dansk Joe Hansen <joedalton2@yahoo.dk>

Denne oversættelse er gratis dokumentation; læs GNU General Public License version 3 (https://www.gnu.org/licenses/gpl-3.0.html) eller nyere for ophavsretbetingelser. Der er INGEN ANSVAR.

Hvis du støder på fejl i oversættelsen af ​​denne vejledning, skal du sende en besked til debian-l10n-danish@lists.debian.org.