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

NOM

       utimensat,  futimens  -  Modifier les horodatages d'un fichier avec une
       precision 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 fonctionnalites  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 a jour les horodatages d'un fichier
       avec une precision d'une nanoseconde. Ceci 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 fournit
       dans pathname. Avec futimens(), le fichier dont  les  horodatages  doit
       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 : times[0] 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  (1er janvier  1970
       a 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  a  jour pour le fichier est configure 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.

   Droits d'acc`es n'ecessaires
       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 :

       1. soit que l'utilisateur ait les droits d'ecriture sur le fichier ;

       2. soit   que  l'identifiant  effectif  de  l'appelant  corresponde  au
          proprietaire du fichier ;

       3. ou que le processus appelant ait les privileges necessaires.

       Pour  pouvoir  effectuer  d'autres  changement  que  de   definir   les
       horodatage  a l'heure actuelle (c'est-a-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 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.

   Sp'ecificit'es 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 ceci 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 un chemin absolu, dirfd est ignore.

       Le  champ  flags  est un champ de bits qui peut etre nul ou inclure les
       constantes suivantes, definies dans <fcntl.h> :

       AT_SYMLINK_NOFOLLOW
              Si pathname indique un lien  symbolique,  alors  mettre  a  jour
              l'horodatage du lien, plutot que le fichier pointe.

VALEUR RENVOY'EE

       S'ils  reussissent les appels utimensat() et futimens() renvoient zero,
       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 proprietaire du fichier, l'appelant n'a pas
                la permission d'ecriture sur le fichier  et  l'appelant  n'est
                pas  privilegie  (Linux : n'a ni la capacite CAP_FOWNER, ni la
                capacite CAP_DAC_OVERRIDE) ; ou
              * le  fichier  est  marque  comme  etant   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  a  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 ete rencontres en
              parcourant pathname.

       ENAMETOOLONG
              (utimensat()) pathname est trop long.

       ENOENT (utimensat())  Un  element  du  chemin   d'acces   pathname   ne
              correspond pas un repertoire ou aun 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 et en ne changeant pas l'autre
              horodatage (c'est-a-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 proprietaire du fichier et l'appelant n'est
                pas privilegie (Linux : n'a pas la capacite CAP_FOWNER).
              * 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.

VERSIONS

       utimensat()  a  ete  ajoute  a Linux dans le noyau 2.6.22 ; la glibc le
       gere depuis la version 2.6.

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

CONFORMIT'E

       futimens() et utimensat() sont specifies dans 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 fichier  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)

       Sous Linux, futimens() est une fonction de bibliotheque  implementee  a
       l'aide  de  l'appel  systeme  utimensat().  Pour  ceci, 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);

BOGUES

       Plusieurs bogues affectent utimensat() et  futimens()  sur  les  noyaux
       anterieurs  a  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 nul (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'acc`es 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'acc`es du descripteur de fichier permet l''ecriture.

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       etre       trouvees      a      l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis 2010, cette traduction est maintenue a l'aide  de  l'outil  po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   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  ecrivant  a
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir acces a la version anglaise de ce document
       en utilisant la commande << man -L C <section> <page_de_man> >>.

Linux                          13 decembre 2009                   UTIMENSAT(2)