Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
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.27 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)