Re: utimensat(2) may/must confusion

["Michael Kerrisk (man-pages)" <mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org>]

Hello Elliot,


On 01/18/2015 02:54 AM, enh wrote:
> http://man7.org/linux/man-pages/man2/utimensat.2.html
> 
>        If both tv_nsec fields are specified as UTIME_OMIT, then no file
>        ownership or permission checks are performed, and the file timestamps
>        are not modified, but other error conditions may still be detected.
> 
> fs/utimes.c
> 
>                 /* Nothing to do, we must not even check the path.  */
>                 if (tstimes[0].tv_nsec == UTIME_OMIT &&
>                     tstimes[1].tv_nsec == UTIME_OMIT)
>                         return 0;
> 
> if you're intending to match POSIX, the current text is correct. they
> say "If both tv_nsec fields are set to UTIME_OMIT, no ownership or
> permissions check shall be performed for the file, but other error
> conditions may still be detected (including [EACCES] errors related to
> the path prefix)."
> (http://pubs.opengroup.org/onlinepubs/9699919799/functions/futimens.html)
> 
> but as the snippet above shows, the kernel doesn't, and so will
> silently return success even for a non-existent file if both times are
> UTIME_OMIT.

That's an interesting detail. I'm not sure if it was intended, but I 
agree with what you seem to be saying: it doesn't violate the standard.
>
> i'm not sure why the kernel says "must", but even if they fix that, it

Here's my hypothesis. The implementer of the system call was a German 
speaker. The German verb "müssen" can be translated as "must" or 
"to need to". But, while the verb seems like English "must", it's
also a "false friend", as language teachers sometimes say. 
"Wir müessen nicht" might seem like it it means "We must not"
but rather, it means "We need not", which clearly is different.
I suspect that the author of the code and comments made an English
language misstep in the comment. 

(It's not every day that I get to apply my mediocre German to 
man-pages work!)

> would be useful for the man page to mention this subtlety. something
> like "(Note that at present the kernel performs no checks in this
> case, not even that the file exists, and will always return
> success.)". (strictly that's not true because the EFAULT check for the
> struct timespec* will have happened, but it seems less clear to try to
> include that fact.)

I'm reluctant to note that point too prominently, since it's 
obviously not the kind of thing we want to encourage user-space 
programmers to do, but at the bottom of NOTES, I added:

       If  both  tv_nsec  fields  are  specified as UTIME_OMIT, then the
       Linux implementation of utimensat() succeeds  even  if  the  file
       referred to by dirfd and pathname does not exist.

Okay?

Cheers,

Michael

-- 
Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Linux/UNIX System Programming Training: http://man7.org/training/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html