utimensat(2) System Calls Manual utimensat(2) NAVN utimensat, futimens - aendr filtidsstempler med nanosekund praecision BIBLIOTEK C-standardbibliotek (libc, -lc) SYNOPSIS #include /* Definition af AT_*-konstanter */ #include 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 For glibc 2.10: _ATFILE_SOURCE futimens(): Siden glibc 2.10: _POSIX_C_SOURCE >= 200809L For glibc 2.10: _GNU_SOURCE BESKRIVELSE utimensat() og futimens() opdaterer tidsstemplerne for en fil med nanosekund praecision. Dette er i kontrast til den historiske utime(2) og utimes(2), der kun tillader sekund og mikrosekund praecision, respektivt, nar filtidsstempler angives. Med utimensat() er filen angivet via stinavnet i sti. Med futimens() er filen hvis tidsstempler skal opdateres angivet via en aben fildeskriptor, fd. For begge kald, er de nye filtidsstempler angivet i tabellen times: times[0] angiver den nye >>sidst tilgaet<< (atime); times[1] angiver den >>sidst aendret<< (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 storste vaerdi understottet af filsystemet, der ikke er hojere end det angivne tidspunkt. Hvis feltet tv_nsec for en af timespec-strukturerne har den specielle vaerdi UTIME_NOW, sa er det tilsvarende filtidsstempel angivet til den aktuelle tid. Hvis feltet tv_nsec for en af timespec-strukturerne har den specielle vaerdi UTIME_OMIT, sa efterlades det tilsvarende filtidsstempel uaendret. I begge disse tilfaede bliver vaerdien for det tilsvarende tv_sec-felt ignoreret. Hvis times er NULL, sa angives begge tidsstempler til den aktuelle tid. Statusaendringstidspunktet (ctime) vil blive angivet til den aktuelle tid, selv om andre tidsstempler ikke aendrer sig. Rettighedskrav For at angive begge filtidsstempler til den aktuelle tid (dvs., times er NULL, eller begge tv_nsec-fetler angiver UTIME_NOW), enten: o kalderen skal have skriveadgang til filen; o kalderens effektive bruger-id skal matche ejeren af filen; eller o kalderen skal have passene privilegier. For at lave en aendring 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 gaelde. Hvis begge tv_nsec-felter er angivet som UTIME_OMIT, sa udfores der ingen tjek for filejerskab eller rettighed og filtidsstemplerne bliver ikke aendret, men andre fejlbetingelser kan stadig registreres. utimensat() detaljer Hvis sti er relativ, sa fortolkes det som standard relativt til mappen refereret til af den abne fildeskriptor, dirfd (frem for relativt til den nuvaerende arbejdsmappe for den kaldende proces, som det gores af utimes(2) for et relativt stinavn). Se openat(2) for en forklaring af hvorfor dette kan vaere nyttigt. Hvis sti er relativ og dirfd er den specielle vaerdi AT_FDCWD, sa fortolkes sti relativt til den nuvaerende arbejsmapppe for den kaldende proces (som utimes(2)). Hvis sti er foraeldet, sa ignoreres dirfd. Argumentet flag er en bit-maske oprettet af ORing together zero eller flere af de folgende vaerdier defineret i : AT_EMPTY_PATH (siden Linux 5.8) Hvis sti er en tom streng, arbejd pa filen refereret til af dirfd (der kan vaere indhentet via open(2) O_PATH-flaget). I dette tilfaelde kan dirfd referere til enhver filtype, ikke kun en mappe. Hvis dirfd er AT_FDCWD fungerer kaldet pa den nuvaerende 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, sa opdater tidsstemplerne for henvisningen, frem for filen hvortil der refereres. RETURVAERDI 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-vaerdier 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 vaerdi i flag. EINVAL Ugyldig vaerdi i et af tv_nsec-felterne (vaerdi uden for interval [0, 999,999,999], og ikke UTIME_NOW eller UTIME_OMIT); eller en ugyldig vaerdi 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 modt 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 praefikskomponenterne for sti er ikke en mappe. EPERM Kalderen forsogte at aendre en eller begge tidsstempler til en vaerdi anderledes end den nuvaerende tid, eller til at aendre en af tidsstemplerne til den nuvaerende tid, mens det andet tidsstempel efterlades uaendret (dvs. times er ikke NULL; intet tv_nsec-felt er UTIME_NOW, og intet tv_nsec-felt er UTIME_OMIT) og enten: o kalderens effektive bruger-id matcher ikke filejeren og kalderen er ikke privilegeret (Linux: har ikke kapaciteten CAP_FOWNER); eller, o filen er markeret tilfoj-kun eller uforanderlig (se chattr(1)). EROFS Filen er pa et skrivebeskyttet filsystem. ESRCH (utimensat()) Sogetilladelse er naegtet for en af praefikskomponenterne i sti. ATTRIBUTTER For en forklaring pa betingelserne i dette afsnit, se attributes(7). +------------------------------------------+-----------------+---------+ |Graenseflade | Attribut | Vaerdi | +------------------------------------------+-----------------+---------+ |utimensat(), futimens() | Tradsikkerhed | MT-Safe | +------------------------------------------+-----------------+---------+ VERSIONER ABI-forskelle for C-bibliotek/kerne Pa Linux er futimens() en biblioteksfunktion implementeret oven pa systemkaldet utimensat(). For at understotte dette implementerer Linux-systemkaldet utimensat() en funktion uden for standarden: hvis sti er NULL, sa aendrer 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); Bemaerk dog, at glibc-omslaget for utimensat() ikke tillader at sende NULL som vaerdien for sti: omslagsfunktionen returnerer i dette tilfaelde 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() gor futimesat(2) foraeldet. Pa Linux kan tidsstempler ikke aendret for en fil, der er markeret uforanderlig, og den eneste aendring tilladt for filer markeret tilfoj-kun er at angive tidsstemplerne til den aktuelle tid. (Dette er konsistent med den historiske opforsel for utime(2) og utimes(2) pa Linux). Hvis begge tv_nsec-felter er angivet som UTIME_OMIT, sa lykkes Linux-implementeringen af utimensat() selv om filen er refereret til af dirfd og sti ikke findes. FEJL Flere fejl plager utimensat() og futimens() for Linux 2.6.26. Disse fejl er enten manglende overholdelse af POSIX.1-kladdespecifikationen eller inkonsistens med historisk Linux-opforsel. o POSIX.1 nagiver at hvis et af tv_nsec-felterne har vaerdien UTIME_NOW eller UTIME_OMIT, sa skal vaerdien for det tilsvarende tv_sec-felt ignoreres. I stedet er det kraevet at vaerdien af tv_sec-feltet er 0 (eller at fejlen EINVAL folger). o Diverse fejl betyder i forhold til rettighedskontrol at i tilfaeldet hvor begge tv_nsec-felter er angivet til UTIME_NOW, sa behandles det ikke altid som at angive times som NULL, og tilfaeldet hvor en tv_nsec-vaerdi er UTIME_NOW og den anden er UTIME_OMIT behandles ikke pa samme made som at angive times som en tekstsoger til en strukturtabel indeholdende arbitraere tidsvaerdier. Som et resutlat, i nogle tilfaelde: a) filtidsstempler kan opdateres af en proces, der ikke burde have rettighed til at udfore opdateringer; b) filstempler kan ikke opdateres af en proces, der burde have rettighed til at udfore opdateirnger; og c) den forkerte errno-vaerdi returneres i tilfaelde af en fejl. o 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 OGSA chattr(1), touch(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), timespec(3), inode(7), path_resolution(7), symlink(7) OVERSAETTELSE Oversaettere af denne manual til dansk Joe Hansen Denne oversaettelse er gratis dokumentation; laes GNU General Public License version 3 eller nyere for ophavsretbetingelser. Der er INGEN ANSVAR. Hvis du stoder pa fejl i oversaettelsen af denne vejledning, skal du sende en besked til . Linux man-pages 6.17 29. oktober 2025 utimensat(2)