[Python-Dev] error in doc for fcntl module

[Mike Coleman]

One problem is that API wrappers like this sometimes include extra
functionality.  When I ran across this example, I wondered whether the
Python interface had been enhanced to work like this

    # set these three flags
    rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
    rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_APPEND)
    rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NOATIME)

Something like this might be nice, but after staring at it for another
minute, I realized that the Python interface itself was standard, and
that it was the example itself that was confusing me.  (I've been
programming Unix/POSIX for over 20 years, so perhaps I simply
outsmarted myself, or am an idiot.  Still, I found it confusing.)

One of the many virtues of Python is that it's oriented towards
learning/teaching.  It seems like it would be useful in this case to
have an example that shows best practice (as in Stevens/Rago and other
similar texts), rather than one that will merely usually work on
present systems.

If it makes any difference, I'd be happy to send a patch.  Is there
any reason not to change this?

Mike



On Wed, Jan 7, 2009 at 6:36 PM, Guido van Rossum <guido at python.org> wrote:
> Well my Linux man page says that the only flags supported are
> O_APPEND,  O_ASYNC,  O_DIRECT, O_NOATIME, and O_NONBLOCK; and all of
> those are typically off -- so I'm not sure that it's a mistake or need
> correcting. These APIs should only be used by people who know what
> they're doing anyways; the examples are meant to briefly show the call
> format.
>
> On Wed, Jan 7, 2009 at 1:31 PM, Mike Coleman <tutufan at gmail.com> wrote:
>> In the doc page for the fcntl module, the example below is given.
>> This seems like an error, or at least very misleading, as the normal
>> usage is to get the flags (F_GETFL), set or unset the bits you want to
>> change, then set the flags (F_SETFL).  A reader might think that the
>> example below merely sets O_NDELAY, but it also stomps all of the
>> other bits to zero.
>>
>> If someone can confirm my thinking, this ought to be changed.
>>
>> import struct, fcntl, os
>>
>> f = open(...)
>> rv = fcntl.fcntl(f, fcntl.F_SETFL, os.O_NDELAY)
>
> --
> --Guido van Rossum (home page: http://www.python.org/~guido/)
>