[Python-Dev] error in doc for fcntl module
Guido van Rossum
guido at python.org
Thu Jan 8 18:36:19 CET 2009
Unless documented otherwise, the Python wrappers for system calls are
as low-level as possible, sticking as close to the system call
semantics as possible.
I do think you may be reading too much into the whole thing.
On Thu, Jan 8, 2009 at 9:05 AM, Mike Coleman <tutufan at gmail.com> wrote:
> 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/)
>>
>
--
--Guido van Rossum (home page: http://www.python.org/~guido/)
More information about the Python-Dev
mailing list