timerfd_create(2) System Calls Manual timerfd_create(2) NAVN timerfd_create, timerfd_settime, timerfd_gettime - stopure der paminder via fildeskriptorer BIBLIOTEK Standard C library (libc, -lc) SYNOPSIS #include int timerfd_create(int clockid, int flag); int timerfd_settime(int fd, int flag, const struct itimerspec *ny_vaerdi, struct itimerspec *_Nullable gl_vaerdi); int timerfd_gettime(int fd, struct itimerspec *nuv_vaerdi); BESKRIVELSE Disse systemkald opretter og fungerer pa et stopur, der leverer pamindelser om udlob for stopure via en fildeskriptor. De tilbyder et alternativ til brugen af setitimer(2) eller timer_create(2), med den fordel at fildeskriptoren kan overvages af select(2), poll(2) og epoll(7). Brugen af disse tre systemkald er analog til brugen af timer_create(2), timer_settime(2) og timer_gettime(2). (Der er ingen analog for timer_getoverrun(2) da den funktionalitet tilbydes af read(2), som beskrevet nedenfor). timerfd_create() timerfd_create() opretter et nyt stopurobjekt og returnerer en fildeskriptor, der referer til det stopur. Argumentet clockid angiver uret, der bruges til at markere status for stopuret, og skal vaere en af de folgende: CLOCK_REALTIME Et realtids ur, der kan angives for hele systemet. CLOCK_MONOTONIC Et monotont stigende ur, der ikke kan indstilles og som maler tid fra et uangivet punkt i fortiden, der ikke aendrer sig efter systemets opstartstidspunkt. CLOCK_BOOTTIME (siden Linux 3.15) Som CLOCK_MONOTONIC, er dette et monotont stigende ur. Hvor CLOCK_MONOTONIC ikke maler tiden mens et system er i dvale, sa inkluderer CLOCK_BOOTTIME tiden hvor systemet er i dvale. Dette er nyttigt for programmer, der skal vaere dvale-opmaerksomme. CLOCK_REALTIME er ikke egnet for sadanne programmer, da uret pavirkes af diskontinuerlige aendringer til systemuret. CLOCK_REALTIME_ALARM (siden Linux 3.11) Dette ur er som CLOCK_REALTIME, men vil vaekke systemet, hvis det er i dvale. Kalderen skal have funktionaliteten CAP_WAKE_ALARM for at angive et stopur mod dette ur. CLOCK_BOOTTIME_ALARM (siden Linux 3.11) Dette ur er som CLOCK_BOOTTIME, men vil vaekke systemet, hvis det er i dvale. Kalderen skal have funktionaliteten CAP_WAKE_ALARM for at kunne angive et stopur mod dette ur. Se clock_getres(2) for yderligere detaljer om ovenstaende ure. Den nuvaerende vaerdi af hver af disse ure kan indhentes via clock_gettime(2). Startende med Linux 2.6.27 kan de folgende vaerdier blive bit-vis ORed i flag for at aendre opforelsen for timerfd_create(): TFD_NONBLOCK Angiv filstatusflaget O_NONBLOCK pa den abne filbeskrivelse (se open(2)) refereret til af den nye fildeskriptor. Brug af dette flag forhindrer ekstra kald til fcntl(2) for at opna det samme resultat. TFD_CLOEXEC Angiv flaget close-on-exec (FD_CLOEXEC) pa den nye fildeskriptor. Se beskrivelsen af flaget O_CLOEXEC i open(2) for arsagerne til hvorfor dette kan vaere nyttigt. I Linuxversioner op til og inklusive 2.6.26 skal flag vaere angivet som nul. timerfd_settime() timerfd_settime() bevaebner (starter) eller afvaebner (stopper) stopuret refereret til af fildeskriptoren fd. Arguementet ny_vaerdi angiver det oprindelige udlob og interval for stopuret. Strukturen itimerspec brugt for dette argument er beskrevet i itimerspec(3type). new_value.it_value angiver det oprindelige udlob for stopuret, i sekunder og nanosekunder. Angivelse af et af felterne i new_value.it_value til en vaerdi anderledes end nul bevaebner stopuret. Angivelse af begge felter i new_value.it_value til nul afvaebner stopuret. Angivelse af et eller begge felter i new_value.it_interval til vaerdier forskellige fra nul angiver perioden, i sekunder og nanosekunder, for gentagne stopursudlob efter det oprindelige udlob. Hvis begge felter i new_value.it_interval er nul, sa udlober stopuret bare en gang, pa tidspunktet angivet af new_value.it_value. Som standard fortolkes den oprindelige udlobstid angivet i ny_vaerdi relativ til den nuvaerende tid pa stopurets ur pa tidspunktet for kaldet (dvs. new_value.it_value angiver en tid relativ til den nuvaerende vaerdi for uret angivet af clockid). Et absolut tidsudlob kan vaelges via argumentet flag. Argumentet flag er en bit-maske, der kan inkludere de folgende vaerdier: TFD_TIMER_ABSTIME Fortolk new_value.it_value som en absolut vaerdi pa stopurets ur. Stopuret vil udlobe nar vaerdien af stopurets ur nar vaerdien angivet i new_value.it_value. TFD_TIMER_CANCEL_ON_SET Hvis dette flag er angivet med TFD_TIMER_ABSTIME og uret for dette stopur er CLOCK_REALTIME eller CLOCK_REALTIME_ALARM, sa marker dette stopur som om det kan afbestilles hvis realtidsuret har en diskontinuerlig aendring (settimeofday(2), clock_settime(2) eller lignende). Nar sadanne aendringer opstar vil en nuvaerende eller fremtidig read(2) fra fildeskriptoren fejle med fejlbeskeden ECANCELED. Hvis argumentet gl_vaerdi ikke er NULL, sa bruges strukturen itimerspec der peges pa til at returnere indstillingen for stopuret, der var gyldig pa tidspunktet for kaldet; se beskrivelsen af timerfd_gettime() der folger. timerfd_gettime() timerfd_gettime() returnerer, i nuv_vaerdi, en itimerspec-struktur der indheolder den nuvaerende indstilling for stopuret refereret til af fildeskriptoren fd. Feltet it_value returnerer tidsintervallet indtil stopuret naeste gang udlober. Hvis begge felter for denne struktur er nul, sa er stopuret afvaebnet. Dette felt indeholder en relativ vaerdi, uanset om flaget TFD_TIMER_ABSTIME var angivet da stopuret blev indstillet. Feltet it_interval returnerer intervallet for stopuret. Hvis begge felter for denne struktur er nul, sa er stopuret sat til at udlob bare en gang, pa tidspunktet angivet af curr_value.it_value. Operationer pa et stopurs fildeskriptor Fildeskriptoren returneres af timerfd_create() understotter de folgende yderligere operationer: read(2) Hvis stopuret allerede er udlobet en eller flere gange siden dets indstillinger sidst blev aendret via timerfd_settime(), eller siden den sidste succesfulde read(2), sa returnerer mellemlageret angivet til read(2) et ej underskrevet 8-byte heltal (uint64_t) indeholdende antallet af udlob, der er opstaet. (Den returnerede vaerdi er i vaert-byteraekkefolge--det vil sige, byte-standardraekkefolgen for heltal pa vaertsmaskinen). Hvis intet stopurudlob er sket pa tidspunktet for read(2), sa blokerer kaldet enten det naeste stopursudlob eller fejler med den folgende fejlbesked EAGAIN hvis fildeskriptoren er gjort ikkeblokerende (via brugen af fcntl(2) F_SETFL-operationen til at angive flaget O_NONBLOCK). En read(2) fejler med fejlbeskeden EINVAL hvis storrelsen for det angivne mellemlager er mindre end 8 byte. Hvis det associerede ur er enten CLOCK_REALTIME eller CLOCK_REALTIME_ALARM, er stopuret absolut (TFD_TIMER_ABSTIME) og flaget TFD_TIMER_CANCEL_ON_SET var angivet da timerfd_settime() blev kaldet, sa fejler read(2) med fejlbeskeden ECANCELED hvis realtidsuret har en diskontinuerlig aendring. (Dette gor det muligt for det laesende program at registrere sadanne diskontinuerlige aendringer til uret). Hvis det associerede ur er enten CLOCK_REALTIME eller CLOCK_REALTIME_ALARM, er stopuret absolut (TFD_TIMER_ABSTIME) og flaget TFD_TIMER_CANCEL_ON_SET ikke var angivet da timerfd_settime() blev kaldt, sa kan en diskontinuerlig negativ aendring til uret (f.eks. clock_settime(2)) fa read(2) til at fjerne blokering, men returnere en vaerdi pa 0 (dvs. ingen byte laest), hvis ur-aendringen opstar efter tiden udlob, men for read(2) pa fildeskriptoren. poll(2) select(2) (og lignende) Fildeskriptoren kan laeses (argumentet select(2) readfds; flaget poll(2) POLLIN) hvis en ellere flere stopursudlob er opstaet. Fildeskriptoren understotter ogsa de andre fil-deskriptor multiplexing-API'er: pselect(2), ppoll(2) og epoll(7). ioctl(2) Den folgende timerfd-specifikke kommando er understottet: TFD_IOC_SET_TICKS (siden Linux 3.17) Juster antallet af stopursudlob der er opstaet. Argumentet er en peger til et 8-byte heltal forskellige fra nul (uint64_t*) indeholdende det nye antal udlob. Nar antallet er angivet, vil en eventuel tjener pa stopuret blive vaekket. Det eneste formal med denne kommando er at gendanne udlobene til tjekpunkt/gendannelse. Denne operation er kun tilgaengelig hvis kernen blev konfigureret med tilvalget CONFIG_CHECKPOINT_RESTORE. close(2) Nar fildeskriptoren ikke laengere er kraevet, sa bor den lukkes. Nar alle fildeskriptorer associeret med det samme stopursobjekt er blevet lukket, sa afvaebnes stopuret og dets ressurcer frigives af kernen. fork(2)-semantik Efter en fork(2) arver underprocessen en kopi af fildeskriptoren oprettet af timerfd_create(). Fildeskriptoren refererer til det samme underliggende stopursobjekt som den tilsvarende fildeskriptor i overprocessen, og read(2)'er i underprocessen vil returnere information om udlob for stopuret. execve(2)-semantik En fildeskriptor oprettet af timerfd_create() bevares pa tvaers af execve(2), og fortsaetter med at oprette stopursudlob hvis stopuret var bevaebnet. RETURVAERDI Ved succes, returnerer timerfd_create() en ny fildeskriptor. Ved fejl, returneres -1 og errno angives for at indikere fejlen. timerfd_settime() og timerfd_gettime() returnerer 0 ved succes; ved fejl returnerer de -1, og angiver errno for at indikere fejlen. FEJL timerfd_create() kan fejle med de folgende fejlbeskeder: EINVAL clockid er ikke gyldig. EINVAL flag er ugyldig; eller, i Linux 2.6.26 eller tidligere, flag er forskellig fra nul. EMFILE Begraensningen per proces for antallet af abne fildeskriptorer er blevet naet. ENFILE Systemets begraensning pa det samlede antal abne filer er naet. ENODEV Kunne ikke montere (intern) anonym iknude-enhed. ENOMEM Der var utilstraekkelige kernehukommelse til at oprette stopuret. EPERM clockid var CLOCK_REALTIME_ALARM eller CLOCK_BOOTTIME_ALARM men kalderen havde ikke funktionaliteten CAP_WAKE_ALARM. timerfd_settime() og timerfd_gettime() kan fejle med de folgende fejl: EBADF fd er ikke en gyldig filbeskrivelse. EFAULT ny_vaerdi, gl_vaerdi eller nuv_vaerdi er ikke en gyldig peger. EINVAL fd er ikke en gyldig timerfd-fildeskriptor. timerfd_settime() kan ogsa fejl med de folgende fejl: ECANCELED Se NOTER. EINVAL ny_vaerdi er ikke korrekt initialiseret (en af tv_nsec falder udenfor intervallet nul til 999.999.999). EINVAL flag er ugyldig. STANDARDER Linux. HISTORIK Linux 2.6.25, glibc 2.8. NOTER Hvis vi antager det folgende scenarie for CLOCK_REALTIME- eller CLOCK_REALTIME_ALARM-stopuret, der blev oprettet med timerfd_create(): (1) Stopuret er blevet startet (timerfd_settime()) med TFD_TIMER_ABSTIME- og TFD_TIMER_CANCEL_ON_SET-flagene; (2) En ej fortsaettende aendring (f.eks. settimeofday(2)) er efterfolgende lavet pa CLOCK_REALTIME-uret; og (3) kalderen kaldte igen timerfd_settime() for at bevaebne stopuret (uden forst at lave en read(2) pa fildeskriptoren). I dette tilfaelde sker der det folgende: o timerfd_settime() returnerer -1 med errno angivet til ECANCELED. (Dette gor det muligt for kalderen at vide at det tidligere stopur var pavirket af en ej fortsaettende aendring til uret). o Stopuret er bevaebnet med succes med indstillingerne angivet i det andet timerfd_settime()-kald. (Dette var sandsynligvis et implementeringsuheld, men vil ikke blive rettet nu, i tilfaelde af at der er programmer, der afhaenger af denne opforelse). FEJL I ojeblikket understotter timerfd_create() faerre typer af ur-id'er end timer_create(2). EKSEMPLER Det folgende program opretter et stopur og overvager sa dets status. Programmet accepterer op til tre kommandolinjeargumenter. Det forste argument angiver antallet af sekunder for et oprindelige udlob for stopuret. Det andet argument angiver intervallet for stopuret, i sekunder. Det tredje argument angiver antallet af gange programmet bor tillade at stopuret udlober for afslutning. Det andet og det tredje kommandolinjeargument er valgfrie. Den folgende skalsession demonstrerer brugen af programmet: $ a.out 3 1 100 0.000: timer started 3.000: read: 1; total=1 4.000: read: 1; total=2 ^Z # tast control-Z for at suspendere programmet [1]+ Stopped ./timerfd3_demo 3 1 100 $ fg # Genoptag afvikling efter nogle fa sekunder a.out 3 1 100 9.660: read: 5; total=7 10.000: read: 1; total=8 11.000: read: 1; total=9 ^C # tast control-C for at suspendere programmet Programkilde #include #include #include #include #include #include #include #include static void print_elapsed_time(void) { int secs, nsecs; static int first_call = 1; struct timespec curr; static struct timespec start; if (first_call) { first_call = 0; if (clock_gettime(CLOCK_MONOTONIC, &start) == -1) err(EXIT_FAILURE, "clock_gettime"); } if (clock_gettime(CLOCK_MONOTONIC, &curr) == -1) err(EXIT_FAILURE, "clock_gettime"); secs = curr.tv_sec - start.tv_sec; nsecs = curr.tv_nsec - start.tv_nsec; if (nsecs < 0) { secs--; nsecs += 1000000000; } printf("%d.%03d:\t", secs, (nsecs + 500000) / 1000000); } int main(int argc, char *argv[]) { int fd; ssize_t s; uint64_t expir, tot_expir, max_expir; struct timespec now; struct itimerspec new_value; if (argc != 2 && argc != 4) { fprintf(stderr, "%s init-secs [interval-secs max-num-expir]\n", argv[0]); exit(EXIT_FAILURE); } if (clock_gettime(CLOCK_REALTIME, &now) == -1) err(EXIT_FAILURE, "clock_gettime"); /* Opret et CLOCK_REALTIME-absolut stopur med oprindelig udlob og interval som angivet pa kommandolinjen. */ new_value.it_value.tv_sec = now.tv_sec + atoi(argv[1]); new_value.it_value.tv_nsec = now.tv_nsec; if (argc == 2) { new_value.it_interval.tv_sec = 0; max_expir = 1; } else { new_value.it_interval.tv_sec = atoi(argv[2]); max_expir = atoi(argv[3]); } new_value.it_interval.tv_nsec = 0; fd = timerfd_create(CLOCK_REALTIME, 0); if (fd == -1) err(EXIT_FAILURE, "timerfd_create"); if (timerfd_settime(fd, TFD_TIMER_ABSTIME, &new_value, NULL) == -1) err(EXIT_FAILURE, "timerfd_settime"); print_elapsed_time(); printf("timer started\n"); for (tot_expir = 0; tot_expir < max_expir;) { s = read(fd, &expir, sizeof(uint64_t)); if (s != sizeof(uint64_t)) err(EXIT_FAILURE, "read"); tot_expir += expir; print_elapsed_time(); printf("read: %" PRIu64 "; total=%" PRIu64 "\n", expir, tot_expir); } exit(EXIT_SUCCESS); } SE OGSA eventfd(2), poll(2), read(2), select(2), setitimer(2), signalfd(2), timer_create(2), timer_gettime(2), timer_settime(2), timespec(3), epoll(7), time(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 8. februar 2026 timerfd_create(2)