os.O_SHLOCK and os.O_EXLOCK are not available on Linux

[Sworddragon]

BPO	23105
Nosy	@vsajip, @bitdancer, @matrixise
Files	issue23105.diff

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = <Date 2016-09-11.14:17:07.932>
created_at = <Date 2014-12-23.14:38:55.389>
labels = ['easy', 'type-bug', 'docs']
title = 'os.O_SHLOCK and os.O_EXLOCK are not available on Linux'
updated_at = <Date 2016-09-11.14:17:07.929>
user = 'https://bugs.python.org/Sworddragon'

bugs.python.org fields:

activity = <Date 2016-09-11.14:17:07.929>
actor = 'python-dev'
assignee = 'docs@python'
closed = True
closed_date = <Date 2016-09-11.14:17:07.932>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2014-12-23.14:38:55.389>
creator = 'Sworddragon'
dependencies = []
files = ['44032']
hgrepos = []
issue_num = 23105
keywords = ['patch', 'easy']
message_count = 12.0
messages = ['233048', '233050', '233051', '272090', '272091', '272093', '272097', '272108', '272112', '272136', '273650', '275796']
nosy_count = 6.0
nosy_names = ['vinay.sajip', 'r.david.murray', 'docs@python', 'Sworddragon', 'python-dev', 'matrixise']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue23105'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6']

[Sworddragon]

From the documentation:

"
os.O_DSYNC
os.O_RSYNC
os.O_SYNC
os.O_NDELAY
os.O_NONBLOCK
os.O_NOCTTY
os.O_SHLOCK
os.O_EXLOCK
os.O_CLOEXEC

These constants are only available on Unix.

"

But os.O_SHLOCK and os.O_EXLOCK are not available on my system (Linux 3.16.7-ckt1 x86_64):

sworddragon@ubuntu:~$ python3
Python 3.4.2 (default, Dec  4 2014, 09:34:20) 
[GCC 4.9.2] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import os
>>> os.O_SHLOCK
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'O_SHLOCK'
>>> os.O_EXLOCK
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: 'module' object has no attribute 'O_EXLOCK'
>>> exit()

[bitdancer]

The documentation says "Some of them are not available on all platforms. For descriptions of their availability and use, consult the open(2) manual page on Unix or the MSDN on Windows.". The important bit there being "consult the open(2) manual page on Unix" for availability.

That said, since the options are grouped and labeled with per-platform availability...but with a slightly different meaning of the word platform...I think the docs could be clarified. Do you have a suggestion for rewording that sentence to make it clearer?

[Sworddragon]

I have missed the first part of the documentation and am not sure if something needs really to be changed. But if you think so maybe comments like "These constants are only available on Unix." could be extended by the word "commonly" like "These constants are commonly only available on Unix.".

[matrixise]

If you read the documentation from glibc-2.24, these options are only available on BSD and not on Linux.

"""
The remaining operating modes are BSD extensions. They exist only on some systems. On other systems, these macros are not defined.

Macro: int O_SHLOCK
Acquire a shared lock on the file, as with flock. See File Locks.

If O_CREAT is specified, the locking is done atomically when creating the file. You are guaranteed that no other process will get the lock on the new file first.

Macro: int O_EXLOCK
Acquire an exclusive lock on the file, as with flock. See File Locks. This is atomic like O_SHLOCK.
"""

With my fedora 24, and glibc 2.23 I don't find any reference to these macros.

[matrixise]

Link to the documentation of glibc:

http://www.gnu.org/software/libc/manual/html_node/Open_002dtime-Flags.html

[matrixise]

I am working on it.

[matrixise]

patch for 3.6 with the comment of Sworddragon.

[Sworddragon]

If we decide to word it this way eventually the sentence for "Windows only" needs to be updated too. Not sure about the other sentences as they sound a bit if they would guarantee what they say. Maybe somebody else knows more.

[matrixise]

Which sentence with "Windows only" ?

Thanks

[Sworddragon]

Maybe it sounded a bit confusing but this text was not to be meant as a direct match against the documentation.

[vsajip]

The existing docs have a section "These constants are GNU extensions and not present if they are not defined by the C library."

There could be a corresponding section for BSD extensions to which O_EXLOCK and O_SHLOCK are moved, or the word "GNU" can removed from the existing section and these two flags moved to it. How does that sound? My preference would be for the latter.

[python-dev]

New changeset 5ca4c545dfe4 by Vinay Sajip in branch '2.7':
Issue bpo-23105: Updated documentation on open() flag constants.
https://hg.python.org/cpython/rev/5ca4c545dfe4

New changeset f1427491a8a5 by Vinay Sajip in branch '3.5':
Issue bpo-23105: Updated documentation on open() flag constants.
https://hg.python.org/cpython/rev/f1427491a8a5

New changeset 64610bcd326f by Vinay Sajip in branch 'default':
Closes bpo-23105: Merged update from 3.5.
https://hg.python.org/cpython/rev/64610bcd326f