plucky (2) utimensat.2.gz

Provided by: manpages-fr-dev_4.25.1-1_all bug

NOM

       utimensat, futimens - Modifier les horodatages d'un fichier avec une précision d'une nanoseconde

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <fcntl.h>          /* Définition des constantes AT_* */
       #include <sys/stat.h>

       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 fonctionnalités 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  à  jour  les  horodatages  d'un  fichier  avec  une précision d'une
       nanoseconde. Cela change de l'appel historique ou de utimes(2) qui  permettent  seulement  une  précision
       d'une seconde et d'une microseconde respectivement pour l'établissement des horodatages de fichier.

       Avec  utimensat(),  le  fichier  est indiqué à l'aide du chemin fourni dans pathname. Avec futimens(), le
       fichier dont les horodatages doivent être mis à jour est indiqué par un descripteur  de  fichier  ouvert,
       fd.

       Pour  les deux appels, les nouveaux horodatages de fichier sont indiqués dans le tableau times[0] : times
       indique l'horodatage du dernier accès (atime) ; times[1] indique l'horodatage de la dernière modification
       (mtime).  Chaque  élément  de  times indique une date par un nombre de secondes et de nanosecondes depuis
       l'époque POSIX (1er janvier 1970 à 00:00:00 UTC). Cette information  est  transmise  dans  une  structure
       timespec(3).

       Les horodatages de fichier mis à jour sont configurés à la valeur la plus importante gérée par le système
       de fichiers et qui n'est pas supérieure à l'horodatage fourni.

       Si le champ tv_nsec  d'une  des  structures  timespec  prend  la  valeur  particulière  UTIME_NOW,  alors
       l'horodatage  correspondant  du  fichier  est  défini  à  l'heure actuelle. Si le champ tv_nsec d'une des
       structures timespec prend la valeur particulière UTIME_OMIT, alors l'horodatage correspondant du  fichier
       reste inchangé. Dans ces deux cas, la valeur du champ tv_sec est ignoré.

       Si times est NULL, les deux horodatages sont définis à l'heure actuelle.

       L'heure  du  changement d'état (ctime) sera  réglée à l'heure actuelle, même si les autres horodatages ne
       sont pas vraiment modifiés.

   Droits d'accès nécessaires
       Pour définir les deux horodatages à l'heure actuelle (c'est-à-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'écriture sur le fichier ;

       -  soit que l'identifiant effectif de l'appelant corresponde au propriétaire du fichier ;

       -  ou bien que le processus appelant ait les privilèges nécessaires.

       Pour  pouvoir  effectuer  d'autres  changements  que  de  définir  les  horodatages  à  l'heure  actuelle
       (c'est-à-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 vérification n'est effectuée sur le propriétaire ou
       les permissions et les horodatages ne sont  pas  modifiés,  mais  les  autres  situations  d'erreur  sont
       toujours détectées.

   Spécificités de utimensat()
       Si  le  chemin  donné  dans  pathname est relatif, il est par défaut interprété par rapport au répertoire
       référencé par le descripteur de fichier ouvert dirfd (plutôt que par rapport  au  répertoire  courant  du
       processus,  comme  pour  utimes(2) pour les chemins relatifs). Consultez openat(2) pour avoir les raisons
       pour lesquelles cela peut être utile.

       Si pathname est un chemin relatif, et si  dirfd  a  la  valeur  spéciale  AT_FDCWD,  alors  pathname  est
       interprété par rapport au répertoire courant du processus appelant, comme dans utimes(2).

       Si pathname est absolu, alors dirfd est ignoré.

       Le  paramètre flags est un masque de bits créé par un OU binaire entre zéro ou plus des valeurs suivantes
       définies dans <fcntl.h> :

       AT_EMPTY_PATH (depuis Linux 5.8)
              Si pathname est une chaîne vide, opérer sur le fichier auquel dirfd fait référence (qui peut avoir
              été obtenu en utilisant le paramètre O_PATH de open(2)). Dans ce cas, dirfd peut faire référence à
              tout type de fichier, pas seulement à un répertoire. Si dirfd est AT_FDCWD, l'appel opère  sur  le
              répertoire  de  travail  en  cours. Ce paramètre est spécifique à Linux ; définir _GNU_SOURCE pour
              obtenir sa définition.

       AT_SYMLINK_NOFOLLOW
              Si pathname indique un lien symbolique, alors mettre à jour l'horodatage du lien,  plutôt  que  du
              fichier pointé.

VALEUR RENVOYÉE

       S'ils  réussissent,  les appels utimensat() et futimens() renvoient zéro, sinon ils renvoient -1 et errno
       est défini 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  propriétaire  du fichier, l'appelant n'a pas la
              permission d'écriture sur le fichier et l'appelant n'est pas privilégié (sous Linux :  n'a  ni  la
              capacité CAP_FOWNER, ni la capacité 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 à
              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 été rencontrés en parcourant pathname.

       ENAMETOOLONG
              (utimensat()) pathname est trop long.

       ENOENT (utimensat())  Un  élément  du  chemin  d'accès pathname ne correspond pas à un répertoire ou à un
              fichier existant, ou pathname est une chaîne vide.

       ENOTDIR
              (utimensat()) pathname est un chemin relatif, mais dirfd n'est ni AT_FDCWD, ni un  descripteur  de
              fichier  correspondant  à un répertoire ; ou l'un des composants au début de pathname n'est pas un
              répertoire.

       EPERM  L'appelant a essayé 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-à-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 propriétaire du fichier
                 et l'appelant n'est pas privilégié (sous Linux : n'a pas la capacité CAP_FOWNER) ; ou,

              -  le fichier est marqué comme n'acceptant que des ajouts ou est immuable (voir chattr(1)).

       EROFS  Le fichier se trouve sur un système de fichiers en lecture seule.

       ESRCH  (utimensat()) Un élément au début du chemin d'accès pathname ne permet pas le parcours.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌───────────────────────────────────────────────────────────────────────┬──────────────────────┬─────────┐
       │InterfaceAttributValeur  │
       ├───────────────────────────────────────────────────────────────────────┼──────────────────────┼─────────┤
       │utimensat(), futimens()                                                │ Sécurité des threads │ MT-Safe │
       └───────────────────────────────────────────────────────────────────────┴──────────────────────┴─────────┘

VERSIONS

   Différences entre la bibliothèque C et l'ABI du noyau
       Sous Linux, futimens() est  une  fonction  de  bibliothèque  implémentée  à  l'aide  de  l'appel  système
       utimensat(). Pour cela, l'appel système utimensat() de Linux implémente une fonctionnalité non standard :
       si pathname est NULL, alors l'appel modifie les horodatages du fichier correspondant  au  descripteur  de
       fichier   dirfd   (qui  peut  correspondre  à  n'importe  quel  type  de  fichier).  En  utilisant  cette
       fonctionnalité, l'appel futimens(fd, times) est implémenté comme ceci :

           utimensat(fd, NULL, times, 0);

       Notez néanmoins 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) obsolète.

       Sous  Linux, les horodatages ne peuvent pas être modifiés pour un fichier marqué comme étant immuable, et
       la seule modification autorisée pour les  fichiers  n'autorisant  que  des  ajouts  est  de  définir  les
       horodatages  à  l'heure  actuelle.  C'est  cohérent  avec  le  comportement  historique de utime(2) et de
       utimes(2) sous Linux

       Si les deux champs tv_nsec valent UTIME_OMIT, alors l'implémenation de  utimensat()  dans  Linux  réussit
       même si le fichier référencé 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
       conformités avec le brouillon de la spécification POSIX.1, soit des  incohérences  avec  le  comportement
       historique de Linux.

       -  POSIX.1 spécifie que si un des champs tv_nsec prend la valeur UTIME_NOW ou UTIME_OMIT, alors la valeur
          du champs tv_sec correspondant doit être ignorée. À la place, la valeur  du  champ  tv_sec  doit  être
          nulle (ou une erreur EINVAL sera produite).

       -  Ces  bogues  indiquent  que  pour  ce qui est de la vérification des droits, le cas où les deux champs
          tv_nsec ne valent pas UTIME_NOW n'est pas toujours traité de la même façon que lorsque times est NULL,
          et  le cas où une des valeurs tv_nsec vaut UTIME_NOW et l'autre vaut UTIME_OMIT n'est pas traité de la
          même façon 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 être mis à jour par
          un processus qui ne devrait pas avoir le droit de faire ces mises  à  jour ;  b)  des  horodatages  de
          fichier ne puissent pas être mis à jour par un processus qui devrait avoir le droit de faire ces mises
          à jour ; et c) la mauvaise valeur d'errno puisse être renvoyée en cas d'erreur.

       -  POSIX.1 indique qu'un processus qui a les droits d'accès en écriture 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 à jour  les  deux  horodatages  à  l'heure  actuelle.
          Cependant,  futimens()  vérifie  à  la  place  si  le  mode  d'accès  du descripteur de fichier permet
          l'écriture.

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   française   de   cette   page   de   manuel   a   été   créée   par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,   Stéphan   Rafin   <stephan.rafin@laposte.net>,   Thierry   Vignaud
       <tvignaud@mandriva.com>,  François  Micaux,  Alain Portal <aportal@univ-montp2.fr>, Jean-Philippe Guérard
       <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-luc.coulon@wanadoo.fr>,   Julien   Cristau
       <jcristau@debian.org>,      Thomas      Huriaux      <thomas.huriaux@gmail.com>,     Nicolas     François
       <nicolas.francois@centraliens.net>,    Florentin    Duneau    <fduneau@gmail.com>,     Simon     Paillard
       <simon.paillard@resel.enst-bretagne.fr>,     Denis    Barbier    <barbier@debian.org>,    David    Prévot
       <david@tilapin.org> et Jean-Pierre Giraud <jean-pierregiraud@neuf.fr>

       Cette traduction est une documentation libre ; veuillez vous reporter à la  GNU  General  Public  License
       version 3   ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩   concernant   les  conditions  de  copie  et  de
       distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel,  veuillez  envoyer  un  message  à
       ⟨debian-l10n-french@lists.debian.org⟩.