gh-142302: Fix mkstemp() documentation: clarify file descriptor inheritance behavior

[raixyzaditya]

Description

Fixes the misleading documentation for tempfile.mkstemp() regarding file descriptor inheritance.

The current documentation states "The file descriptor is not inherited by child processes," which is incomplete and misleading.

What was wrong

The file descriptor created by mkstemp() is inherited by child processes created via fork(). The close-on-exec flag (O_CLOEXEC), when available, only prevents inheritance across exec() calls, not fork() calls.

Changes made

Updated the documentation to accurately describe the inheritance behavior:

• Clarifies that O_CLOEXEC only affects exec() calls
• Notes that the fd is still inherited by forked child processes
• Maintains technical accuracy while being clear for users

Testing

Verified the documentation builds correctly:

cd Doc
make html

Related Issue

Fixes #142302

---

📚 Documentation preview 📚: https://cpython-previews--142338.org.readthedocs.build/

• Issue: Tempfile.mkstemp file descriptor issue #142302

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[picnixz]

Please sign the CLA and address the CI issues. In addition, please wait for the maintainer to confirm that the documentation should be changed like that.

[raixyzaditya]

Thank you for your review
CLA: I have signed the CLA.
CI Issues: All tests are now passing. The CI issues have been resolved.
Documentation Change: I'm happy to wait for maintainer confirmation on the wording. The current documentation states "The file descriptor is not inherited by child processes," which is misleading since:

• The fd IS inherited by forked child processes
• Only exec() calls are affected by O_CLOEXEC (when available)
• This has been verified empirically in production code
  I'm open to alternative wording suggestions if the current approach needs adjustment. Please let me know if there's a preferred way to clarify this behavior.

[QuiteAFoxtrot]

Hopefully this is appropriate to comment here - I don't see that O_CLOEXEC is included as a flag in the tempfile.mkstemp:

Following things backward from where the file descriptor is created here:
https://github.com/python/cpython/blob/main/Lib/tempfile.py#L257

It looks like the flags are created here:
https://github.com/python/cpython/blob/main/Lib/tempfile.py#L353

Which is just a simple switch to these guys:
https://github.com/python/cpython/blob/main/Lib/tempfile.py#L52

I have only tested this on "fork" but theoretically the file descriptor will be inherited across the "exec" calls as well since the O_CLOEXEC doesn't appear to be present in any of the flags during the file descriptor creation, and the tempfile.mkstemp function signature does not present the user any options to add O_CLOEXEC or any other filesystem-level flags (presumably by design, since the user could use their own calls to os.open if they needed that fine-grained flag control).

[raixyzaditya]

@QuiteAFoxtrot You're absolutely right. I've confirmed that O_CLOEXEC is not included in _bin_openflags or _text_openflags.
Looking at the code in Lib/tempfile.py (lines 52 - 56), the flags are:

_text_openflags = _os.O_RDWR | _os.O_CREAT | _os.O_EXCL
_bin_openflags = _text_openflags

This means that file descriptor will be inherited by the child processes created via both fork() and exec(). The original documentation is incorrect is incorrect.
I'll update the documentation to simply state: "The file descriptor will be inherited by child processes."
Thank you for catching this.

[QuiteAFoxtrot]

@vstinner 's comments on the original issue #142302 show that O_CLOEXEC is part of the default behavior of the call to os.open where the file descriptor for tempfile.mkstem is created due to PEP 446, so I was wrong - O_CLOEXEC is actually included in the process here, so the file descriptor should not be inheritable after an exec()

[vstinner]

This documentation change is wrong, I suggest to close it.

[bedevere-app]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[QuiteAFoxtrot]

Respectfully, I'd like to point out that the original docs were also wrong - the file descriptor is inherited (and more importantly, usable) with a fork()-no-exec(), shouldn't the docs still be fixed? Apologies if that's not what you meant by suggesting to close.

[vstinner]

If you consider that the documentation is unclear, you can complete/clarify https://docs.python.org/dev/library/os.html#fd-inheritance. And you might add a link to this section from mkstemp() doc ("The file descriptor is not inherited by child processes").

[raixyzaditya]

Thank you @vstinner and @QuiteAFoxtrot for the clarification regarding PEP 446 and O_CLOEXEC behaviour.
I have updated the documentation to clarify that the non-inheritance specifically applies to exec() calls, not fork(). The updated text now reads:

"The file descriptor is not inherited by child processes across exec() calls."
This addresses the ambiguity in the original documentation while remaining technically accurate. The fd IS inherited after fork() but NOT across exec() due to O_CLOEXEC.
I have made the requested changes; please review again.

[raixyzaditya]

@vstinner I hope you're doing well. Just wanted to check if you had a chance to review the latest changes. No rush - I know you're busy. Happy to make any additional adjustments needed.

[vstinner]

This paragraph is quite verbose. I expected something shorter, such as:

On UNIX, non-inheritable file descriptors are closed in child processes at the
execution of a new program, other file descriptors are inherited. Note that
non-inheritable file descriptors are still *inherited* by child process on :func:`os.fork`.

[raixyzaditya]

@vstinner Perfect! I've simplified both the changes as you suggested :-

1. mkstemp(): Just added the link without extra explanation
2. fd_inheritance: Used your shorter, clearer version

Thank you for the guidance on keeping the docs concise.

[vstinner]

LGTM, thanks for the simpler documentation.

[raixyzaditya]

Thank you sir for the review and the guidance on keeping the documentation concise. Much appreciated!

[miss-islington-app]

Thanks @raixyzaditya for the PR, and @vstinner for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14.
🐍🍒⛏🤖

[bedevere-app]

GH-143486 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-143487 is a backport of this pull request to the 3.13 branch.

[vstinner]

Merged, thanks.