utimensat(2) may/must confusion

utimensat(2) may/must confusion

[enh]

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.

i'm not sure why the kernel says "must", but even if they fix that, it
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.)

 --elliott
--
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

Re: utimensat(2) may/must confusion

[Michael Kerrisk (man-pages)]

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

Re: utimensat(2) may/must confusion

[enh]

On Sun, Jan 18, 2015 at 2:49 AM, Michael Kerrisk (man-pages)
<mtk.manpages-Re5JQEeQqe8AvxtiuMwx3w@public.gmane.org> wrote:
> 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?

sgtm. anyone who tries to use that man page without carefully reading
the NOTES and BUGS sections is going to have a bad time anyway. (plus
i suspect that one day this will migrate to the BUGS section :-) )

thanks!
--
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