Provided by: manpages-fr-dev_3.32d0.2p4-1_all bug

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    (consultez
   feature_test_macros(7)) :

       utimensat():
           Depuis la glibc 2.10 :
               _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
           Avant la glibc 2.10 :
               _ATFILE_SOURCE
       futimens():
           Depuis la glibc 2.10 :
                  _XOPEN_SOURCE >= 700 || _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. 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 une date
       par  un nombre de secondes et de nanosecondes depuis l'époque (1er janvier 1970 à 00:00:00
       UTC). Cette information est transmise 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 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 :

       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 (consultez 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 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 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 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),  futimesat(2),  openat(2),  stat(2), utimes(2), futimes(3), path_resolution(7),
       symlink(7)

COLOPHON

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

TRADUCTION

       Depuis   2010,   cette   traduction   est   maintenue   à   l'aide   de    l'outil    po4a
       <URL:http://po4a.alioth.debian.org/>  par  l'équipe  de  traduction francophone au sein du
       projet perkamon <URL:http://perkamon.alioth.debian.org/>.

       Alain Portal <URL:http://manpagesfr.free.fr/> (2008).

       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> ».