Loading

NOM

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

SYNOPSIS

       #include <sys/stat.h>

       int utimensat(int dirfd, const char *pathname,
                     const struct timespec times[2], int flags);

       int futimens(int fd, const struct timespec times[2]);

   Exigences de  macros  de  test  de  fonctionnalités  pour  la  glibc  (voir
   feature_test_macros(7)) :

       utimensat() : _ATFILE_SOURCE
       futimens() :   _GNU_SOURCE   /*   Changera   probablement   quand   les
       modifications de POSIX.1-2008 seront incorporés dans la glibc */

       utimensat() et futimens() mettent à jour les horodatages  d’un  fichier
       avec une précision d’une nanoseconde. Ceci 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  fournit
       dans  pathname.  Avec  futimens(), le fichier dont les horodatages doit
       ê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 : times[0] 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 un horodatage en secondes et
       nanosecondes depuis Epoch (1er janvier 1970,  00:00:00  UTC)  dans  une
       structure de la forme suivante :

           struct timespec {
               time_t tv_sec;        /* secondes     */
               long   tv_nsec;       /* nanosecondes */
           };

       L’horodatage  mis  à  jour pour le fichier est configuré à 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.

   Droits daccè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 :

       1. soit que l’utilisateur ait les droits d’écriture sur le fichier ;

       2. soit   que  l’identifiant  effectif  de  l’appelant  corresponde  au
          propriétaire du fichier ;

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

       Pour  pouvoir  effectuer  d’autres  changement  que  de   définir   les
       horodatage  à l’heure actuelle (c’est-à-dire quand times n’est pas NULL
       et que les deux champs tv_nsec ne valent pas UTIME_NOW et que les  deux
       champs  tv_nsec ne valent pas non plus 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 ceci 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 un chemin absolu, dirfd est ignoré.

       Le champ flags est un champ de bits qui peut être nul  ou  inclure  les
       constantes suivantes, définies dans <fcntl.h> :

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

VALEUR RENVOYÉE

       S’ils réussissent les appels utimensat() et futimens() renvoient  zéro,
       sinon ils renvoient -1 et remplissent errno avec le code d’erreur.

ERREURS

       EACCES times est 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é (Linux : n’a ni la capacité CAP_FOWNER,  ni  la
                capacité CAP_DAC_OVERRIDE) ; ou
              * le fichier est marqué comme étant immuable (voir chattr(1)).

       EBADF  (futimens()) fd n’est pas un descripteur de fichier valable.

       EBADF  (utimensat())  pathname  est un chemin 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  vallant  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 composant 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
              horodatage  en  l’heure  actuelle et en ne changeant pas l’autre
              horodatage (c’est-à-dire times n’est pas NULL, les  deux  champs
              tv_nsec  ne  valent  pas UTIME_NOW et les deux champs tv_nsec ne
              valent pas 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é (Linux : n’a pas la capacité CAP_FOWNER).
              * 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.

VERSIONS

       utimensat()  a  été  ajouté  à Linux dans le noyau 2.6.22 ; la glibc le
       gère depuis la version 2.6.

       La prise en charge de futimens() est apparu dans la glibc 2.6.

CONFORMITÉ

       futimens() et utimensat() sont spécifiés dans 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 fichier  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)

       Sous Linux, futimens() est une fonction de bibliothèque  implémentée  à
       l’aide  de  l’appel  système  utimensat().  Pour  ceci, 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);

BOGUES

       Plusieurs bogues affectent utimensat() et  futimens()  sur  les  noyaux
       antérieurs  à  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 nul (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 daccs 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 daccs du descripteur de fichier permet lcriture.

VOIR AUSSI

       chattr(1),  futimesat(2),  openat(2),  stat(2),  utimes(2), futimes(3),
       path_resolution(7), symlink(7)

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été  traduite  par Alain Portal <aportal AT
       univ-montp2  DOT   fr>   en   2008,   et   mise   à   disposition   sur
       http://manpagesfr.free.fr/.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».