What are O_RDWR and O_CREAT and why does Perldoc assume I know this already?

Cody Fendant has asked for the wisdom of the Perl Monks concerning the following question:

I'm just doing a quick and dirty database thing using DB_File and reading up on it, http://perldoc.perl.org/DB_File.html gives examples of flags which can be attached to the tie() function:

tie %A, "DB_File", undef, O_CREAT|O_RDWR, 0666, $DB_HASH ;
[download]

Now I know what the 0666 is that's how would do it with dbmopen() but I don't know what those flags are. Obviously they mean "create" and "read-write" etc?

Where do these flags come from, where are they documented? How come they can be used as well as Unix permissions like 0666?

Comment on What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? Select or Download Code

Replies are listed 'Best First'.
Re: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by soonix (Chancellor) on Feb 06, 2015 at 06:45 UTC
They are documented in the Unix/Linux man page for open(2) → open (this links to the man page, not the perl function open). The examples for DB_File seem to include Fcntl, which makes them available in Perl. Oh, just remembered Perl sysopen uses the same constants and mentions Fcntl.	[reply]
Re^2: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by Cody Fendant (Hermit) on Feb 06, 2015 at 10:27 UTC
Thanks! That really helps. So who do I write to to get that link/reference included in the perldoc? Seems like it would be useful.	[reply]
Re^3: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by Corion (Patriarch) on Feb 06, 2015 at 10:29 UTC
`corelist DB_File` [download] claims that it was first released with Perl 5 and that it is maintained with Perl itself. So the approach to get a documentation change would be to use `perlbug` and send the proposed documentation change (preferrably as a patch) in the bug report to perl5-porters.	[reply] [d/l] [select]
Re^4: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by Anonymous Monk on Feb 06, 2015 at 10:50 UTC
Re: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by QM (Parson) on Feb 06, 2015 at 10:29 UTC
You can guess that DB_File sits at top of a dependency tree. And you've seen that things from lower down bubble up, without complete explanation or reference (which happens from time to time, we hope appropriately). Searching for "O_CREAT O_RDWR", the first result for me has this blurb on the first page: O_RDONLY Open for reading only. O_WRONLY Open for writing only. O_RDWR Open for reading and writing. The result is undefined if this flag is applied to a FIFO. As to why this is required, as well as file permissions: File permissions relate to *who* can read, write, or execute, not *when* to allow it. But a process may only need read access, or only write access, or something more complicated. Just because a user can write to a file, doesn't mean every process needs write access. Process read/write access should always be limited to what is needed in the immediate future, without churning. This prevents a once-in-a-thousand error (that the unit tests missed), wiping out the file system. If you think the documentation of DB_File should have links for this (or perhaps say that they come from Fcntl), raise a bug on DB_File. -QM -- Quantum Mechanics: The dreams stuff is made of	[reply]
Re: What are O_RDWR and O_CREAT and why does Perldoc assume I know this already? by locked_user sundialsvc4 (Abbot) on Feb 06, 2015 at 13:04 UTC
When writing documentation, it’s very easy indeed to assume that the reader knows what you are talking about ... and thus to “de-rail the Gentle Reader” even by a single unfamiliar word, exactly as just happened here. So, I think it’s a great idea to improve that documentation and/or to add a new topic. How, exactly, might this be done?