utimensat(2) System Calls Manual utimensat(2) NOM utimensat, futimens - Modifier les horodatages d'un fichier avec une precision d'une nanoseconde BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include /* Definition des constantes AT_* */ #include int utimensat(int dirfd, const char *pathname, const struct timespec times[_Nullable 2], int flags); int futimens(int fd, const struct timespec times[_Nullable 2]); Exigences de macros de test de fonctionnalites pour la glibc (consulter feature_test_macros(7)) : utimensat(): Depuis la glibc 2.10 : _POSIX_C_SOURCE >= 200809L avant la glibc 2.10 : _ATFILE_SOURCE futimens(): Depuis la glibc 2.10 : _POSIX_C_SOURCE >= 200809L Avant la glibc 2.10 : _GNU_SOURCE DESCRIPTION utimensat() et futimens() mettent a jour les horodatages d'un fichier avec une precision d'une nanoseconde. Cela change de l'appel historique ou de utimes(2) qui permettent seulement une precision d'une seconde et d'une microseconde respectivement pour l'etablissement des horodatages de fichier. Avec utimensat(), le fichier est indique a l'aide du chemin fourni dans pathname. Avec futimens(), le fichier dont les horodatages doivent etre mis a jour est indique par un descripteur de fichier ouvert, fd. Pour les deux appels, les nouveaux horodatages de fichier sont indiques dans le tableau times[0] : times indique l'horodatage du dernier acces (atime) ; times[1] indique l'horodatage de la derniere modification (mtime). Chaque element de times indique une date par un nombre de secondes et de nanosecondes depuis l'epoque POSIX (1er janvier 1970 a 00:00:00 UTC). Cette information est transmise dans une structure timespec(3). Les horodatages de fichier mis a jour sont configures a la valeur la plus importante geree par le systeme de fichiers et qui n'est pas superieure a l'horodatage fourni. Si le champ tv_nsec d'une des structures timespec prend la valeur particuliere UTIME_NOW, alors l'horodatage correspondant du fichier est defini a l'heure actuelle. Si le champ tv_nsec d'une des structures timespec prend la valeur particuliere UTIME_OMIT, alors l'horodatage correspondant du fichier reste inchange. Dans ces deux cas, la valeur du champ tv_sec est ignore. Si times est NULL, les deux horodatages sont definis a l'heure actuelle. L'heure du changement d'etat (ctime) sera reglee a l'heure actuelle, meme si les autres horodatages ne sont pas vraiment modifies. Droits d'acces necessaires Pour definir les deux horodatages a l'heure actuelle (c'est-a-dire quand times vaut NULL ou que les deux champs tv_nsec valent UTIME_NOW), il faut : - soit que l'utilisateur ait les droits d'ecriture sur le fichier ; - soit que l'identifiant effectif de l'appelant corresponde au proprietaire du fichier ; - ou bien que le processus appelant ait les privileges necessaires. Pour pouvoir effectuer d'autres changements que de definir les horodatages a l'heure actuelle (c'est-a-dire quand times n'est pas NULL et que ni le champ tv_nsec ne vaut UTIME_NOW, ni le champ tv_nsec ne vaut UTIME_OMIT), les conditions 2 ou 3 ci-dessus s'appliquent. Si les deux champs tv_nsec valent UTIME_OMIT, aucune verification n'est effectuee sur le proprietaire ou les permissions et les horodatages ne sont pas modifies, mais les autres situations d'erreur sont toujours detectees. Specificites de utimensat() Si le chemin donne dans pathname est relatif, il est par defaut interprete par rapport au repertoire reference par le descripteur de fichier ouvert dirfd (plutot que par rapport au repertoire courant du processus, comme pour utimes(2) pour les chemins relatifs). Consultez openat(2) pour avoir les raisons pour lesquelles cela peut etre utile. Si pathname est un chemin relatif, et si dirfd a la valeur speciale AT_FDCWD, alors pathname est interprete par rapport au repertoire courant du processus appelant, comme dans utimes(2). Si pathname est absolu, alors dirfd est ignore. Le parametre flags est un masque de bits cree par un OU binaire entre zero ou plus des valeurs suivantes definies dans : AT_EMPTY_PATH (depuis Linux 5.8) Si pathname est une chaine vide, operer sur le fichier auquel dirfd fait reference (qui peut avoir ete obtenu en utilisant le parametre O_PATH de open(2)). Dans ce cas, dirfd peut faire reference a tout type de fichier, pas seulement a un repertoire. Si dirfd est AT_FDCWD, l'appel opere sur le repertoire de travail en cours. Ce parametre est specifique a Linux ; definir _GNU_SOURCE pour obtenir sa definition. AT_SYMLINK_NOFOLLOW Si pathname indique un lien symbolique, alors mettre a jour l'horodatage du lien, plutot que du fichier pointe. VALEUR RENVOYEE S'ils reussissent, les appels utimensat() et futimens() renvoient zero, sinon ils renvoient -1 et errno est defini pour indiquer l'erreur. ERREURS EACCES times vaut NULL ou les deux champs tv_nsec valent UTIME_NOW et l'identifiant de l'utilisateur effectif de l'appelant ne correspond pas au proprietaire du fichier, l'appelant n'a pas la permission d'ecriture sur le fichier et l'appelant n'est pas privilegie (sous Linux : n'a ni la capacite CAP_FOWNER, ni la capacite CAP_DAC_OVERRIDE). EBADF (futimens()) fd n'est pas un descripteur de fichier valable. EBADF (utimensat()) pathname est relatif, mais dirfd n'est ni AT_FDCWD, ni un descripteur de fichier valable. EFAULT times pointe vers une adresse incorrecte ; ou dirfd valait AT_FDCWD et pathname est NULL ou une adresse incorrecte. EINVAL Valeur incorrecte dans flags. EINVAL Valeur incorrecte dans un des champs tv_nsec (valeur en dehors de l'intervalle allant de 0 a 999 999 999 et ne valant ni UTIME_NOW, ni UTIME_OMIT) ; ou une valeur incorrecte dans un des champs tv_sec. EINVAL pathname est NULL, dirfd ne vaut pas AT_FDCWD et flags contient AT_SYMLINK_NOFOLLOW. ELOOP (utimensat()) Trop de liens symboliques ont ete rencontres en parcourant pathname. ENAMETOOLONG (utimensat()) pathname est trop long. ENOENT (utimensat()) Un element du chemin d'acces pathname ne correspond pas a un repertoire ou a un fichier existant, ou pathname est une chaine vide. ENOTDIR (utimensat()) pathname est un chemin relatif, mais dirfd n'est ni AT_FDCWD, ni un descripteur de fichier correspondant a un repertoire ; ou l'un des composants au debut de pathname n'est pas un repertoire. EPERM L'appelant a essaye de modifier un horodatage (ou les deux) en une valeur autre que l'heure actuelle ou de modifier un des horodatages en l'heure actuelle sans changer l'autre horodatage (c'est-a-dire times n'est pas NULL, aucun des deux champs tv_nsec ne vaut UTIME_NOW et aucun des deux champs tv_nsec ne vaut UTIME_OMIT) et : - l'identifiant d'utilisateur effectif de l'appelant ne correspond pas au proprietaire du fichier et l'appelant n'est pas privilegie (sous Linux : n'a pas la capacite CAP_FOWNER) ; ou, - le fichier est marque comme n'acceptant que des ajouts ou est immuable (voir chattr(1)). EROFS Le fichier se trouve sur un systeme de fichiers en lecture seule. ESRCH (utimensat()) Un element au debut du chemin d'acces pathname ne permet pas le parcours. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +---------------------------------+--------------------------+---------+ |Interface | Attribut | Valeur | +---------------------------------+--------------------------+---------+ |utimensat(), futimens() | Securite des threads | MT-Safe | +---------------------------------+--------------------------+---------+ VERSIONS Differences entre la bibliotheque C et l'ABI du noyau Sous Linux, futimens() est une fonction de bibliotheque implementee a l'aide de l'appel systeme utimensat(). Pour cela, l'appel systeme utimensat() de Linux implemente une fonctionnalite non standard : si pathname est NULL, alors l'appel modifie les horodatages du fichier correspondant au descripteur de fichier dirfd (qui peut correspondre a n'importe quel type de fichier). En utilisant cette fonctionnalite, l'appel futimens(fd, times) est implemente comme ceci : utimensat(fd, NULL, times, 0); Notez neanmoins que l'enveloppe de la glibc pour utimensat() n'autorise pas le passage de NULL comme valeur de pathname : dans ce cas, la fonction d'enveloppe renvoie l'erreur EINVAL. STANDARDS POSIX.1-2008. VERSIONS utimensat() Linux 2.6.22, glibc 2.6. POSIX.1-2008. futimens() glibc 2.6. POSIX.1-2008. NOTES utimensat() rend futimesat(2) obsolete. Sous Linux, les horodatages ne peuvent pas etre modifies pour un fichier marque comme etant immuable, et la seule modification autorisee pour les fichiers n'autorisant que des ajouts est de definir les horodatages a l'heure actuelle. C'est coherent avec le comportement historique de utime(2) et de utimes(2) sous Linux Si les deux champs tv_nsec valent UTIME_OMIT, alors l'implemenation de utimensat() dans Linux reussit meme si le fichier reference par dirfd et pathname n'existe pas. BOGUES Plusieurs bogues affectent utimensat() et futimens() avant Linux 2.6.26. Ces bogues sont soit des non conformites avec le brouillon de la specification POSIX.1, soit des incoherences avec le comportement historique de Linux. - POSIX.1 specifie que si un des champs tv_nsec prend la valeur UTIME_NOW ou UTIME_OMIT, alors la valeur du champs tv_sec correspondant doit etre ignoree. A la place, la valeur du champ tv_sec doit etre nulle (ou une erreur EINVAL sera produite). - Ces bogues indiquent que pour ce qui est de la verification des droits, le cas ou les deux champs tv_nsec ne valent pas UTIME_NOW n'est pas toujours traite de la meme facon que lorsque times est NULL, et le cas ou une des valeurs tv_nsec vaut UTIME_NOW et l'autre vaut UTIME_OMIT n'est pas traite de la meme facon que quand times pointe vers un tableau de structures contenant des valeurs de temps arbitraires. De ce fait, il se peut que : a) des horodatages de fichier puissent etre mis a jour par un processus qui ne devrait pas avoir le droit de faire ces mises a jour ; b) des horodatages de fichier ne puissent pas etre mis a jour par un processus qui devrait avoir le droit de faire ces mises a jour ; et c) la mauvaise valeur d'errno puisse etre renvoyee en cas d'erreur. - POSIX.1 indique qu'un processus qui a les droits d'acces en ecriture pour un fichier peut faire un appel avec times valant NULL ou avec times pointant vers un tableau de structures dans lesquelles les deux champs tv_nsec valent UTIME_NOW pour mettre a jour les deux horodatages a l'heure actuelle. Cependant, futimens() verifie a la place si le mode d'acces du descripteur de fichier permet l'ecriture. VOIR AUSSI chattr(1), touch(1), futimesat(2), openat(2), stat(2), utimes(2), futimes(3), timespec(3), inode(7), path_resolution(7), symlink(7) TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.9.1 2 mai 2024 utimensat(2)