Re: [PATCH man-pages v1] fcntl.2: update manpage with verbiage about open file description locks

[Michael Kerrisk (man-pages)]

Hi Jeff,

Thanks for your reply. Comments below.

On 04/30/2014 02:15 PM, Jeff Layton wrote:
> On Wed, 30 Apr 2014 12:50:23 +0200
> "Michael Kerrisk (man-pages)" <mtk.manpages@xxxxxxxxx> wrote:

[...]

>> #      The record locks described above are associated with the  process
>> #      (unlike  the  open file description locks described below).  This
>> #      has some unfortunate consequences:
>>
>> #      *  If a process holding a lock on a file closes any file descripâ
>> #         tor  referring to the file, then all of the process's locks on
>> #         the file are released, no matter which  file  descriptor  they
>> #         were  obtained  via.  This is bad: it means that a process can
> 
> "were obtained via" is a little awkward. How about "regardless of which
> file descriptor on which they were obtained".

Yeah, it is clumsy. I fixed, and also otherwise made the text more 
precise/concise:

       *  If a process closes any file descriptor referring to a file,
          then  all  of the process's locks on that file are released,
          regardless of the file descriptor(s) on which the locks were
          obtained.
 

[...]

>>   ERRORS
>>   [...]
>>
>> #      EINVAL cmd is  F_OFD_SETLK,  F_OFD_SETLKW,  or  F_OFD_GETLK,  and
>> #             l_pid was not specified as zero.
>>
> 
> The kernel will also return -EINVAL if it doesn't recognize the cmd
> value being passed in. It may be worth mentioning that as well as
> that's the best mechanism to tell whether the kernel actually supports
> OFD locks.

Good point. I added that error case under ERRORS, and added this text to
the top of the page:

       Certain  of  the operations below are supported only since a parâ
       ticular Linux kernel version.  The preferred method  of  checking
       whether  the  host  kernel  supports a aprticular operation is to
       invoke fcntl() with the desired cmd value and then  test  whether
       the  call failed with EINVAL, indicating that the kernel does not
       recognize this value.

==

And getting back to the missed piece:

>>>> The "EACCES or EAGAIN" thing comes from POSIX, because different
>>>> implementations of tradition record locks returned one of these errors.
>>>> So, portable applications using traditional locks must handle either
>>>> possibility. However, that argument doesn't apply for these new locks.
>>>> Surely, we just want to say "set errno to EAGAIN" for this case?
>
> Ahh good catch. I fixed that in the glibc doc but I missed it here.
> Yes, we should be clear that this OFD locks will get back EAGAIN in
> this situation. Can you fix it, or would you prefer I respin the
> patch?

No problem. I fixed it.

Thanks for checking over my revisions!

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-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/