os — 雜項作業系統介面

原始碼: Lib/os.py


此模組提供了一種使用與作業系統相關的功能的可移植方式。如果您只想讀寫檔案,請參閱 open();如果您想操作路徑,請參閱 os.path 模組;如果您想讀取命令列上所有檔案的所有行,請參閱 fileinput 模組。有關建立臨時檔案和目錄,請參閱 tempfile 模組;有關高階檔案和目錄處理,請參閱 shutil 模組。

關於這些函式的可用性說明

  • Python 的所有內建作業系統相關模組的設計宗旨是,只要功能相同,就使用相同的介面;例如,函式 os.stat(path) 以相同的格式(碰巧源自 POSIX 介面)返回關於 *path* 的統計資訊。

  • 特定作業系統特有的擴充套件功能也可以透過 os 模組獲取,但使用它們當然會損害可移植性。

  • 所有接受路徑或檔名的函式都接受位元組和字串物件,如果返回路徑或檔名,則返回相同型別的物件。

  • 在 VxWorks 上,不支援 os.popen、os.fork、os.execv 和 os.spawn*p*。

  • 在 WebAssembly 平臺、Android 和 iOS 上,os 模組的很大一部分不可用或行為不同。與程序(例如 fork()execve())和資源(例如 nice())相關的 API 不可用。其他 API,如 getuid()getpid(),是模擬或存根。WebAssembly 平臺也缺乏對訊號(例如 kill()wait())的支援。

備註

此模組中的所有函式在遇到無效或不可訪問的檔名和路徑,或具有正確型別但作業系統不接受的其他引數時,都會引發 OSError(或其子類)。

exception os.error

內建 OSError 異常的別名。

os.name

匯入的作業系統相關模組的名稱。目前已註冊的名稱有:'posix''nt''java'

參見

sys.platform 具有更精細的粒度。os.uname() 提供系統相關的版本資訊。

platform 模組提供對系統身份的詳細檢查。

檔名、命令列引數和環境變數

在 Python 中,檔名、命令列引數和環境變數使用字串型別表示。在某些系統上,在將這些字串傳遞給作業系統之前,需要將它們編碼為位元組並從位元組解碼。Python 使用 檔案系統編碼和錯誤處理程式 來執行此轉換(參見 sys.getfilesystemencoding())。

檔案系統編碼和錯誤處理程式 在 Python 啟動時透過 PyConfig_Read() 函式進行配置:參見 filesystem_encodingfilesystem_errors 的成員 PyConfig

版本 3.1 中的變更: 在某些系統上,使用檔案系統編碼進行轉換可能會失敗。在這種情況下,Python 使用 surrogateescape 編碼錯誤處理程式,這意味著不可解碼的位元組在解碼時被替換為 Unicode 字元 U+DC*xx*,然後在編碼時再次轉換回原始位元組。

檔案系統編碼 必須保證成功解碼所有低於 128 的位元組。如果檔案系統編碼未能提供此保證,API 函式可能會引發 UnicodeError

另請參閱 區域設定編碼

Python UTF-8 模式

版本 3.7 新增: 有關更多詳細資訊,請參閱 PEP 540

Python UTF-8 模式忽略 區域設定編碼 並強制使用 UTF-8 編碼

請注意,UTF-8 模式下的標準流設定可以透過 PYTHONIOENCODING 覆蓋(就像在預設的區域設定感知模式中一樣)。

由於這些底層 API 的更改,其他高階 API 也表現出不同的預設行為

  • 命令列引數、環境變數和檔名使用 UTF-8 編碼解碼為文字。

  • os.fsdecode()os.fsencode() 使用 UTF-8 編碼。

  • open()io.open()codecs.open() 預設使用 UTF-8 編碼。但是,它們仍然預設使用嚴格錯誤處理程式,因此嘗試以文字模式開啟二進位制檔案很可能會引發異常,而不是產生無意義的資料。

如果 Python 啟動時 LC_CTYPE 區域設定為 CPOSIX,則啟用 Python UTF-8 模式(參見 PyConfig_Read() 函式)。

可以使用 -X utf8 命令列選項和 PYTHONUTF8 環境變數啟用或停用它。

如果完全沒有設定 PYTHONUTF8 環境變數,則直譯器預設為使用當前區域設定,*除非* 當前區域設定被識別為舊版基於 ASCII 的區域設定(如 PYTHONCOERCECLOCALE 所述),並且區域設定強制轉換被停用或失敗。在這些舊版區域設定中,直譯器將預設啟用 UTF-8 模式,除非明確指示不這樣做。

Python UTF-8 模式只能在 Python 啟動時啟用。其值可以從 sys.flags.utf8_mode 讀取。

另請參閱 Windows 上的 UTF-8 模式檔案系統編碼和錯誤處理程式

參見

PEP 686

Python 3.15 將預設啟用 Python UTF-8 模式

程序引數

這些函式和資料項提供有關當前程序和使用者的資訊並對其進行操作。

os.ctermid()

返回與程序的控制終端對應的檔名。

可用性: Unix,不包括 WASI。

os.environ

一個 對映 物件,其鍵和值是表示程序環境的字串。例如,environ['HOME'] 是您的主目錄的路徑名(在某些平臺上),相當於 C 中的 getenv("HOME")

此對映在 os 模組首次匯入時(通常在 Python 啟動期間作為處理 site.py 的一部分)被捕獲。此後對環境所做的更改不會反映在 os.environ 中,除非是透過直接修改 os.environ 所做的更改。

此對映可用於修改環境以及查詢環境。修改對映時會自動呼叫 putenv()

在 Unix 上,鍵和值使用 sys.getfilesystemencoding()'surrogateescape' 錯誤處理程式。如果您想使用不同的編碼,請使用 environb

在 Windows 上,鍵會轉換為大寫。這在獲取、設定或刪除專案時也適用。例如,environ['monty'] = 'python' 將鍵 'MONTY' 對映到值 'python'

備註

直接呼叫 putenv() 不會更改 os.environ,因此最好修改 os.environ

備註

在某些平臺(包括 FreeBSD 和 macOS)上,設定 environ 可能會導致記憶體洩漏。請參閱 putenv() 的系統文件。

您可以刪除此對映中的專案以取消設定環境變數。當專案從 os.environ 中刪除時,以及呼叫 pop()clear() 方法之一時,會自動呼叫 unsetenv()

參見

os.reload_environ() 函式。

版本 3.9 中的變更: 更新以支援 PEP 584 的合併 (|) 和更新 (|=) 運算子。

os.environb

environ 的位元組版本:一個 對映 物件,其鍵和值都是表示程序環境的 bytes 物件。environenvironb 是同步的(修改 environb 會更新 environ,反之亦然)。

environb 僅在 supports_bytes_environTrue 時可用。

在 3.2 版本加入。

版本 3.9 中的變更: 更新以支援 PEP 584 的合併 (|) 和更新 (|=) 運算子。

os.reload_environ()

os.environos.environb 對映是 Python 啟動時環境變數的快取。因此,如果在 Python 外部或透過 os.putenv()os.unsetenv() 對當前程序環境進行更改,則不會反映這些更改。使用 os.reload_environ() 更新 os.environos.environb 以反映當前程序環境中的任何此類更改。

警告

此函式不是執行緒安全的。在另一個執行緒中修改環境時呼叫它會導致未定義行為。在重新載入時從 os.environos.environb 讀取,或呼叫 os.getenv(),可能會返回空結果。

在 3.14 版本加入。

os.chdir(path)
os.fchdir(fd)
os.getcwd()

這些函式在 檔案和目錄 中描述。

os.fsencode(filename)

使用 檔案系統編碼和錯誤處理程式 編碼 路徑類 *filename*;返回未更改的 bytes

fsdecode() 是反向函式。

在 3.2 版本加入。

版本 3.6 中的變更: 添加了支援,以接受實現 os.PathLike 介面的物件。

os.fsdecode(filename)

使用 檔案系統編碼和錯誤處理程式 解碼 路徑類 *filename*;返回未更改的 str

fsencode() 是反向函式。

在 3.2 版本加入。

版本 3.6 中的變更: 添加了支援,以接受實現 os.PathLike 介面的物件。

os.fspath(path)

返回路徑的檔案系統表示。

如果傳入的是 strbytes,則原樣返回。否則,將呼叫 __fspath__(),並返回其值,只要它是一個 strbytes 物件。在所有其他情況下,會引發 TypeError

在 3.6 版本加入。

class os.PathLike

表示檔案系統路徑的物件的 抽象基類,例如 pathlib.PurePath

在 3.6 版本加入。

abstractmethod __fspath__()

返回物件的 filesystem 路徑表示。

該方法應只返回 strbytes 物件,首選 str

os.getenv(key, default=None)

如果環境變數 *key* 存在,則以字串形式返回其值,否則返回 *default*。*key* 是一個字串。請注意,由於 getenv() 使用 os.environ,因此 getenv() 的對映在匯入時也被捕獲,函式可能不會反映未來的環境變化。

在 Unix 上,鍵和值使用 sys.getfilesystemencoding()'surrogateescape' 錯誤處理程式進行解碼。如果您想使用不同的編碼,請使用 os.getenvb()

可用性: Unix, Windows。

os.getenvb(key, default=None)

如果環境變數 *key* 存在,則以位元組形式返回其值,否則返回 *default*。*key* 必須是位元組。請注意,由於 getenvb() 使用 os.environb,因此 getenvb() 的對映在匯入時也被捕獲,函式可能不會反映未來的環境變化。

getenvb() 僅在 supports_bytes_environTrue 時可用。

可用性: Unix。

在 3.2 版本加入。

os.get_exec_path(env=None)

返回在啟動程序時,類似於 shell,將搜尋指定可執行檔案的目錄列表。如果指定了 *env*,它應該是一個環境變數字典,用於查詢 PATH。預設情況下,當 *env* 為 None 時,使用 environ

在 3.2 版本加入。

os.getegid()

返回當前程序的有效組 ID。這對應於當前程序中正在執行的檔案的“set id”位。

可用性: Unix,不包括 WASI。

os.geteuid()

返回當前程序的有效使用者 ID。

可用性: Unix,不包括 WASI。

os.getgid()

返回當前程序的真實組 ID。

可用性: Unix。

此函式在 WASI 上是一個存根,有關更多資訊,請參見 WebAssembly 平臺

os.getgrouplist(user, group, /)

返回使用者所屬的組 ID 列表。如果 *group* 不在列表中,則會包含它;通常,*group* 被指定為 *user* 的密碼記錄中的組 ID 欄位,因為否則該組 ID 可能會被省略。

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.getgroups()

返回與當前程序關聯的補充組 ID 列表。

可用性: Unix,不包括 WASI。

備註

在 macOS 上,getgroups() 的行為與其他 Unix 平臺有所不同。如果 Python 直譯器使用 10.5 或更早的部署目標構建,getgroups() 返回與當前使用者程序關聯的有效組 ID 列表;此列表受系統定義條目數的限制,通常為 16,如果具有足夠許可權,可以透過呼叫 setgroups() 進行修改。如果使用大於 10.5 的部署目標構建,getgroups() 返回與程序有效使用者 ID 關聯的使用者的當前組訪問列表;組訪問列表可能會在程序的生命週期內發生變化,它不受呼叫 setgroups() 的影響,並且其長度不受 16 的限制。部署目標值 MACOSX_DEPLOYMENT_TARGET 可以透過 sysconfig.get_config_var() 獲取。

os.getlogin()

返回登入到程序控制終端的使用者的名稱。在大多數情況下,使用 getpass.getuser() 更為有用,因為後者會檢查環境變數 LOGNAMEUSERNAME 以查詢使用者是誰,並回退到 pwd.getpwuid(os.getuid())[0] 以獲取當前真實使用者 ID 的登入名。

可用性: Unix, Windows, 但不包括 WASI。

os.getpgid(pid)

返回程序 ID 為 *pid* 的程序的程序組 ID。如果 *pid* 為 0,則返回當前程序的程序組 ID。

可用性: Unix,不包括 WASI。

os.getpgrp()

返回當前程序組的 ID。

可用性: Unix,不包括 WASI。

os.getpid()

返回當前程序 ID。

此函式在 WASI 上是一個存根,有關更多資訊,請參見 WebAssembly 平臺

os.getppid()

返回父程序的 ID。當父程序退出時,在 Unix 上返回的 ID 是 init 程序 (1) 的 ID,在 Windows 上它仍然是相同的 ID,可能已經被另一個程序重用。

可用性: Unix, Windows, 但不包括 WASI。

版本 3.2 中的變更: 添加了對 Windows 的支援。

os.getpriority(which, who)

獲取程式排程優先順序。*which* 的值為 PRIO_PROCESSPRIO_PGRPPRIO_USER 之一,*who* 相對於 *which* 進行解釋(PRIO_PROCESS 為程序識別符號,PRIO_PGRP 為程序組識別符號,PRIO_USER 為使用者 ID)。*who* 為零表示(分別)呼叫程序、呼叫程序的程序組或呼叫程序的真實使用者 ID。

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.PRIO_PROCESS
os.PRIO_PGRP
os.PRIO_USER

函式 getpriority()setpriority() 的引數。

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.PRIO_DARWIN_THREAD
os.PRIO_DARWIN_PROCESS
os.PRIO_DARWIN_BG
os.PRIO_DARWIN_NONUI

函式 getpriority()setpriority() 的引數。

可用性: macOS

3.12 新版功能.

os.getresuid()

返回一個元組 (ruid, euid, suid),表示當前程序的真實使用者 ID、有效使用者 ID 和儲存的使用者 ID。

可用性: Unix,不包括 WASI。

在 3.2 版本加入。

os.getresgid()

返回一個元組 (rgid, egid, sgid),表示當前程序的真實組 ID、有效組 ID 和儲存的組 ID。

可用性: Unix,不包括 WASI。

在 3.2 版本加入。

os.getuid()

返回當前程序的真實使用者 ID。

可用性: Unix。

此函式在 WASI 上是一個存根,有關更多資訊,請參見 WebAssembly 平臺

os.initgroups(username, gid, /)

呼叫系統 initgroups() 以初始化組訪問列表,其中包含指定使用者所屬的所有組,以及指定的組 ID。

可用性: Unix,不包括 WASI,不包括 Android。

在 3.2 版本加入。

os.putenv(key, value, /)

將環境變數 *key* 設定為字串 *value*。對環境的此類更改會影響使用 os.system()popen()fork()execv() 啟動的子程序。

os.environ 中專案的賦值會自動轉換為對 putenv() 的相應呼叫;但是,對 putenv() 的呼叫不會更新 os.environ,因此實際上最好對 os.environ 的專案進行賦值。這也適用於 getenv()getenvb(),它們在實現中分別使用 os.environos.environb

另請參閱 os.reload_environ() 函式。

備註

在某些平臺(包括 FreeBSD 和 macOS)上,設定 environ 可能會導致記憶體洩漏。請參閱 putenv() 的系統文件。

使用引數 keyvalue 觸發 審計事件 os.putenv

版本 3.9 中的變更: 該函式現在始終可用。

os.setegid(egid, /)

設定當前程序的有效組 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.seteuid(euid, /)

設定當前程序的有效使用者 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.setgid(gid, /)

設定當前程序的組 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.setgroups(groups, /)

將與當前程序關聯的補充組 ID 列表設定為 *groups*。*groups* 必須是一個序列,每個元素必須是一個標識組的整數。此操作通常僅適用於超級使用者。

可用性: Unix,不包括 WASI。

備註

在 macOS 上,*groups* 的長度不得超過系統定義的有效組 ID 最大數量,通常為 16。有關 getgroups() 可能不返回透過呼叫 setgroups() 設定的相同組列表的情況,請參閱其文件。

os.setns(fd, nstype=0)

將當前執行緒重新關聯到 Linux 名稱空間。有關更多詳細資訊,請參閱 setns(2)namespaces(7) 手冊頁。

如果 *fd* 指的是 /proc/pid/ns/ 連結,setns() 會將呼叫執行緒重新關聯到與該連結關聯的名稱空間,*nstype* 可以設定為 CLONE_NEW* 常量 之一以對操作施加約束(0 表示無約束)。

從 Linux 5.8 開始,*fd* 可以引用從 pidfd_open() 獲取的 PID 檔案描述符。在這種情況下,setns() 將呼叫執行緒重新關聯到 *fd* 所引用的執行緒的一個或多個相同名稱空間中。這受 *nstype* 施加的任何約束,*nstype* 是一個位掩碼,結合了一個或多個 CLONE_NEW* 常量,例如 setns(fd, os.CLONE_NEWUTS | os.CLONE_NEWPID)。呼叫者在未指定名稱空間中的成員身份保持不變。

*fd* 可以是任何具有 fileno() 方法的物件,或原始檔案描述符。

此示例將執行緒重新關聯到 init 程序的網路名稱空間

fd = os.open("/proc/1/ns/net", os.O_RDONLY)
os.setns(fd, os.CLONE_NEWNET)
os.close(fd)

可用性: Linux >= 3.0,glibc >= 2.14。

3.12 新版功能.

參見

unshare() 函式。

os.setpgrp()

呼叫系統呼叫 setpgrp()setpgrp(0, 0),具體取決於哪個版本已實現(如果有)。有關語義,請參閱 Unix 手冊。

可用性: Unix,不包括 WASI。

os.setpgid(pid, pgrp, /)

呼叫系統呼叫 setpgid() 將程序 ID 為 *pid* 的程序的程序組 ID 設定為程序組 ID 為 *pgrp* 的程序組。有關語義,請參閱 Unix 手冊。

可用性: Unix,不包括 WASI。

os.setpriority(which, who, priority)

設定程式排程優先順序。*which* 的值是 PRIO_PROCESSPRIO_PGRPPRIO_USER 之一,*who* 的解釋相對於 *which*(PRIO_PROCESS 的程序識別符號,PRIO_PGRP 的程序組識別符號,以及 PRIO_USER 的使用者 ID)。*who* 的零值表示(分別)呼叫程序、呼叫程序的程序組或呼叫程序的真實使用者 ID。*priority* 是一個在 -20 到 19 範圍內的值。預設優先順序為 0;較低的優先順序會導致更有利的排程。

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.setregid(rgid, egid, /)

設定當前程序的真實和有效組 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.setresgid(rgid, egid, sgid, /)

設定當前程序的真實、有效和儲存的組 ID。

可用性: Unix,不包括 WASI,不包括 Android。

在 3.2 版本加入。

os.setresuid(ruid, euid, suid, /)

設定當前程序的真實、有效和儲存的使用者 ID。

可用性: Unix,不包括 WASI,不包括 Android。

在 3.2 版本加入。

os.setreuid(ruid, euid, /)

設定當前程序的真實和有效使用者 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.getsid(pid, /)

呼叫系統呼叫 getsid()。有關其語義,請參閱 Unix 手冊。

可用性: Unix,不包括 WASI。

os.setsid()

呼叫系統呼叫 setsid()。有關其語義,請參閱 Unix 手冊。

可用性: Unix,不包括 WASI。

os.setuid(uid, /)

設定當前程序的使用者 ID。

可用性: Unix,不包括 WASI,不包括 Android。

os.strerror(code, /)

返回與 *code* 中錯誤程式碼對應的錯誤訊息。在某些平臺中,如果 strerror() 在給定未知錯誤號時返回 NULL,則會引發 ValueError

os.supports_bytes_environ

如果環境的本機作業系統型別是位元組(例如,Windows 上為 False),則為 True

在 3.2 版本加入。

os.umask(mask, /)

設定當前數字 umask 並返回之前的 umask。

此函式在 WASI 上是一個存根,有關更多資訊,請參見 WebAssembly 平臺

os.uname()

返回標識當前作業系統的資訊。返回值是一個具有五個屬性的物件

  • sysname - 作業系統名稱

  • nodename - 網路上機器的名稱(實現定義)

  • release - 作業系統版本

  • version - 作業系統版本

  • machine - 硬體識別符號

為了向後相容,此物件也是可迭代的,其行為類似於一個包含 sysnamenodenamereleaseversionmachine 的五元組。

某些系統將 nodename 截斷為 8 個字元或其前導部分;獲取主機名更好的方法是 socket.gethostname() 甚至 socket.gethostbyaddr(socket.gethostname())

在 macOS、iOS 和 Android 上,這會返回 *核心* 名稱和版本(即,macOS 和 iOS 上為 'Darwin';Android 上為 'Linux')。platform.uname() 可用於在 iOS 和 Android 上獲取面向使用者的作業系統名稱和版本。

可用性: Unix。

3.3 版本中的變化: 返回型別從元組變為具有命名屬性的類元組物件。

os.unsetenv(key, /)

取消設定(刪除)名為 *key* 的環境變數。對環境的此類更改會影響使用 os.system()popen()fork()execv() 啟動的子程序。

刪除 os.environ 中的項會自動轉換為對 unsetenv() 的相應呼叫;但是,對 unsetenv() 的呼叫不會更新 os.environ,因此實際上最好刪除 os.environ 的項。

另請參閱 os.reload_environ() 函式。

使用引數 key 引發 審計事件 os.unsetenv

3.9 版本中的變化: 該函式現在始終可用,並且在 Windows 上也可用。

os.unshare(flags)

解除程序執行上下文的部分關聯,並將它們移動到新建立的名稱空間中。有關更多詳細資訊,請參閱 unshare(2) 手冊頁。*flags* 引數是一個位掩碼,結合了零個或多個 CLONE_* 常量,它指定了執行上下文的哪些部分應該與其現有關聯解除關聯並移動到新的名稱空間。如果 *flags* 引數為 0,則不會對呼叫程序的執行上下文進行任何更改。

可用性:Linux >= 2.6.16。

3.12 新版功能.

參見

setns() 函式。

unshare() 函式的標誌,如果實現支援它們。有關它們的精確效果和可用性,請參閱 Linux 手冊中的 unshare(2)

os.CLONE_FILES
os.CLONE_FS
os.CLONE_NEWCGROUP
os.CLONE_NEWIPC
os.CLONE_NEWNET
os.CLONE_NEWNS
os.CLONE_NEWPID
os.CLONE_NEWTIME
os.CLONE_NEWUSER
os.CLONE_NEWUTS
os.CLONE_SIGHAND
os.CLONE_SYSVSEM
os.CLONE_THREAD
os.CLONE_VM

檔案物件建立

這些函式建立新的 檔案物件。(另請參閱 open() 以開啟檔案描述符。)

os.fdopen(fd, *args, **kwargs)

返回連線到檔案描述符 *fd* 的開啟檔案物件。這是 open() 內建函式的別名,並接受相同的引數。唯一的區別是 fdopen() 的第一個引數必須始終是整數。

檔案描述符操作

這些函式對使用檔案描述符引用的 I/O 流進行操作。

檔案描述符是對應於當前程序已開啟的檔案的小整數。例如,標準輸入通常是檔案描述符 0,標準輸出是 1,標準錯誤是 2。程序開啟的更多檔案將依次分配 3、4、5 等。名稱“檔案描述符”有些誤導;在 Unix 平臺上,套接字和管道也由檔案描述符引用。

當需要時,可以使用 fileno() 方法獲取與 檔案物件 關聯的檔案描述符。請注意,直接使用檔案描述符將繞過檔案物件方法,忽略諸如資料的內部緩衝等方面。

os.close(fd)

關閉檔案描述符 *fd*。

備註

此函式旨在用於低階 I/O,並且必須應用於由 os.open()pipe() 返回的檔案描述符。要關閉由內建函式 open() 或由 popen()fdopen() 返回的“檔案物件”,請使用其 close() 方法。

os.closerange(fd_low, fd_high, /)

關閉從 *fd_low*(包含)到 *fd_high*(不包含)的所有檔案描述符,忽略錯誤。等同於(但比以下更快)

for fd in range(fd_low, fd_high):
    try:
        os.close(fd)
    except OSError:
        pass
os.copy_file_range(src, dst, count, offset_src=None, offset_dst=None)

從檔案描述符 *src* 複製 *count* 位元組,從 *offset_src* 偏移量開始,到檔案描述符 *dst*,從 *offset_dst* 偏移量開始。如果 *offset_src* 為 None,則從當前位置讀取 *src*;*offset_dst* 同理。

在 Linux 核心 5.3 之前的版本中,*src* 和 *dst* 指向的檔案必須位於同一檔案系統中,否則會引發 OSError,其中 errno 設定為 errno.EXDEV

此複製在不增加資料從核心傳輸到使用者空間再返回核心的額外開銷的情況下完成。此外,某些檔案系統可以實現額外的最佳化,例如使用 reflinks(即,共享指向相同寫時複製磁碟塊指標的兩個或多個索引節點;支援的檔案系統包括 btrfs 和 XFS)和伺服器端複製(在 NFS 的情況下)。

該函式在兩個檔案描述符之間複製位元組。文字選項(如編碼和行尾)將被忽略。

返回值是複製的位元組數。這可能小於請求的數量。

備註

在 Linux 上,os.copy_file_range() 不應用於從 procfs 和 sysfs 等特殊檔案系統複製偽檔案的範圍。由於已知的 Linux 核心問題,它將始終複製零位元組並返回 0,就像檔案為空一樣。

可用性:Linux >= 4.5,glibc >= 2.27。

在 3.8 版本加入。

os.device_encoding(fd)

如果與 *fd* 關聯的裝置連線到終端,則返回描述該裝置編碼的字串;否則返回 None

在 Unix 上,如果啟用了 Python UTF-8 模式,則返回 'UTF-8' 而不是裝置編碼。

3.10 版本中的變化: 在 Unix 上,該函式現在實現了 Python UTF-8 模式。

os.dup(fd, /)

返回檔案描述符 *fd* 的副本。新的檔案描述符是 不可繼承的

在 Windows 上,當複製標準流(0:stdin,1:stdout,2:stderr)時,新的檔案描述符是 可繼承的

可用性:非 WASI。

3.4 版本中的變化: 新的檔案描述符現在是不可繼承的。

os.dup2(fd, fd2, inheritable=True)

將檔案描述符 *fd* 複製到 *fd2*,如果需要則首先關閉 *fd2*。返回 *fd2*。新的檔案描述符預設為 可繼承的,如果 *inheritable* 為 False 則為不可繼承的。

可用性:非 WASI。

3.4 版本中的變化: 添加了可選的 *inheritable* 引數。

3.7 版本中的變化: 成功時返回 *fd2*。以前,總是返回 None

os.fchmod(fd, mode)

將由 *fd* 給定的檔案的模式更改為數字 *mode*。有關 *mode* 的可能值,請參閱 chmod() 的文件。從 Python 3.3 開始,這等同於 os.chmod(fd, mode)

使用引數 pathmodedir_fd 引發 審計事件 os.chmod

可用性: Unix, Windows。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

3.13 版本中的變化: 添加了對 Windows 的支援。

os.fchown(fd, uid, gid)

將由 *fd* 給定的檔案的所有者和組 ID 更改為數字 *uid* 和 *gid*。要使其中一個 ID 保持不變,請將其設定為 -1。請參閱 chown()。從 Python 3.3 開始,這等同於 os.chown(fd, uid, gid)

使用引數 pathuidgiddir_fd 引發 審計事件 os.chown

可用性: Unix。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

os.fdatasync(fd)

強制將檔案描述符 *fd* 的檔案寫入磁碟。不強制更新元資料。

可用性: Unix。

備註

此函式在 MacOS 上不可用。

os.fpathconf(fd, name, /)

返回與開啟檔案相關的系統配置資訊。*name* 指定要檢索的配置值;它可能是一個字串,是定義的系統值的名稱;這些名稱在許多標準中指定(POSIX.1、Unix 95、Unix 98 等)。某些平臺還定義了其他名稱。主機作業系統已知的名稱在 pathconf_names 字典中給出。對於未包含在該對映中的配置變數,也接受將整數作為 *name* 傳遞。

如果 *name* 是字串且未知,則引發 ValueError。如果主機系統不支援 *name* 的特定值,即使它包含在 pathconf_names 中,也會引發 OSError,錯誤號為 errno.EINVAL

從 Python 3.3 開始,這等同於 os.pathconf(fd, name)

可用性: Unix。

os.fstat(fd)

獲取檔案描述符 *fd* 的狀態。返回 stat_result 物件。

從 Python 3.3 開始,這等同於 os.stat(fd)

參見

stat() 函式。

os.fstatvfs(fd, /)

返回有關包含與檔案描述符 *fd* 關聯的檔案的檔案系統的資訊,類似於 statvfs()。從 Python 3.3 開始,這等同於 os.statvfs(fd)

可用性: Unix。

os.fsync(fd)

強制將檔案描述符 *fd* 的檔案寫入磁碟。在 Unix 上,這會呼叫本機 fsync() 函式;在 Windows 上,是 MS _commit() 函式。

如果您從一個緩衝的 Python 檔案物件 *f* 開始,首先執行 f.flush(),然後執行 os.fsync(f.fileno()),以確保與 *f* 關聯的所有內部緩衝區都寫入磁碟。

可用性: Unix, Windows。

os.ftruncate(fd, length, /)

截斷與檔案描述符 *fd* 對應的檔案,使其大小最多為 *length* 位元組。從 Python 3.3 開始,這等同於 os.truncate(fd, length)

使用引數 fdlength 引發 審計事件 os.truncate

可用性: Unix, Windows。

3.5 版本中的變化: 增加了對 Windows 的支援

os.get_blocking(fd, /)

獲取檔案描述符的阻塞模式:如果設定了 O_NONBLOCK 標誌則為 False,如果清除了該標誌則為 True

另請參閱 set_blocking()socket.socket.setblocking()

可用性: Unix, Windows。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

在 Windows 上,此函式僅限於管道。

在 3.5 版本加入。

3.12 版本中的變化: 增加了對 Windows 上管道的支援。

os.grantpt(fd, /)

授予訪問與檔案描述符 *fd* 引用主偽終端裝置相關聯的從屬偽終端裝置的許可權。檔案描述符 *fd* 在失敗時不會關閉。

呼叫 C 標準庫函式 grantpt()

可用性: Unix,不包括 WASI。

在 3.13 版本加入。

os.isatty(fd, /)

如果檔案描述符 *fd* 已開啟並連線到 tty(或類似)裝置,則返回 True,否則返回 False

os.lockf(fd, cmd, len, /)

對開啟的檔案描述符應用、測試或移除 POSIX 鎖。*fd* 是一個開啟的檔案描述符。*cmd* 指定要使用的命令 - F_LOCKF_TLOCKF_ULOCKF_TEST 之一。*len* 指定要鎖定的檔案部分。

使用引數 fdcmdlen 引發 審計事件 os.lockf

可用性: Unix。

在 3.3 版本加入。

os.F_LOCK
os.F_TLOCK
os.F_ULOCK
os.F_TEST

指定 lockf() 將執行什麼操作的標誌。

可用性: Unix。

在 3.3 版本加入。

os.login_tty(fd, /)

為新的登入會話準備檔案描述符 fd 所屬的 tty。使呼叫程序成為會話領導者;使 tty 成為呼叫程序的控制 tty、標準輸入、標準輸出和標準錯誤;關閉 fd。

可用性: Unix,不包括 WASI。

在 3.11 版本中新增。

os.lseek(fd, pos, whence, /)

將檔案描述符 *fd* 的當前位置設定為 *pos*,並由 *whence* 修改,並返回相對於檔案開頭的以位元組為單位的新位置。*whence* 的有效值為

  • SEEK_SET0 – 將 *pos* 設定為相對於檔案開頭的位置

  • SEEK_CUR1 – 將 *pos* 設定為相對於當前檔案位置的位置

  • SEEK_END2 – 將 *pos* 設定為相對於檔案末尾的位置

  • SEEK_HOLE – 將 *pos* 設定為相對於 *pos* 的下一個資料位置

  • SEEK_DATA – 將 *pos* 設定為相對於 *pos* 的下一個資料空洞

3.3 版本中的變化: 增加了對 SEEK_HOLESEEK_DATA 的支援。

os.SEEK_SET
os.SEEK_CUR
os.SEEK_END

用於 lseek() 函式和 seek() 方法在 檔案類物件 上調整檔案位置指示器的 *whence* 引數。

SEEK_SET

將檔案位置調整到檔案開頭。

SEEK_CUR

將檔案位置調整到當前檔案位置。

SEEK_END

將檔案位置調整到檔案末尾。

它們的值分別為 0、1 和 2。

os.SEEK_HOLE
os.SEEK_DATA

用於 lseek() 函式和 seek() 方法在 檔案類物件 上,用於在稀疏分配檔案上查詢檔案資料和空洞的引數。

SEEK_DATA

將檔案偏移量調整到下一個包含資料的位置,相對於查詢位置。

SEEK_HOLE

將檔案偏移量調整到下一個包含空洞的位置,相對於查詢位置。空洞定義為一系列零。

備註

這些操作僅對支援它們的檔案系統有意義。

可用性:Linux >= 3.1, macOS, Unix

在 3.3 版本加入。

os.open(path, flags, mode=0o777, *, dir_fd=None)

開啟檔案 *path* 並根據 *flags* 設定各種標誌,並可能根據 *mode* 設定其模式。在計算 *mode* 時,首先會掩蓋當前 umask 值。返回新開啟檔案的檔案描述符。新的檔案描述符是 不可繼承的

有關標誌和模式值的描述,請參閱 C 執行時文件;標誌常量(如 O_RDONLYO_WRONLY)在 os 模組中定義。特別是在 Windows 上,需要新增 O_BINARY 才能以二進位制模式開啟檔案。

此函式可以透過 *dir_fd* 引數支援 相對於目錄描述符的路徑

使用引數 pathmodeflags 引發 審計事件 open

3.4 版本中的變化: 新的檔案描述符現在是不可繼承的。

備註

此函式旨在用於低階 I/O。對於正常使用,請使用內建函式 open(),它返回一個具有 read()write() 方法(以及更多)的 檔案物件。要將檔案描述符包裝在檔案物件中,請使用 fdopen()

3.3 版本中的變化: 添加了 *dir_fd* 引數。

3.5 版本中的變化: 如果系統呼叫被中斷並且訊號處理程式沒有引發異常,該函式現在會重試系統呼叫,而不是引發 InterruptedError 異常(請參閱 PEP 475 以瞭解其原理)。

在 3.6 版本發生變更: 接受 path-like object

以下常量是 open() 函式的 *flags* 引數的選項。它們可以使用位或運算子 | 組合。其中一些並非在所有平臺上都可用。有關它們的可用性和使用的描述,請參閱 Unix 上的 open(2) 手冊頁或 Windows 上的 MSDN

os.O_RDONLY
os.O_WRONLY
os.O_RDWR
os.O_APPEND
os.O_CREAT
os.O_EXCL
os.O_TRUNC

以上常量在 Unix 和 Windows 上都可用。

os.O_DSYNC
os.O_RSYNC
os.O_SYNC
os.O_NDELAY
os.O_NONBLOCK
os.O_NOCTTY
os.O_CLOEXEC

以上常量僅在 Unix 上可用。

3.3 版本中的變化: 添加了 O_CLOEXEC 常量。

os.O_BINARY
os.O_NOINHERIT
os.O_SHORT_LIVED
os.O_TEMPORARY
os.O_RANDOM
os.O_SEQUENTIAL
os.O_TEXT

以上常量僅在 Windows 上可用。

os.O_EVTONLY
os.O_FSYNC
os.O_NOFOLLOW_ANY

以上常量僅在 macOS 上可用。

3.10 版本中的變化: 添加了 O_EVTONLYO_FSYNCO_SYMLINKO_NOFOLLOW_ANY 常量。

os.O_ASYNC
os.O_DIRECT
os.O_DIRECTORY
os.O_NOFOLLOW
os.O_NOATIME
os.O_PATH
os.O_TMPFILE
os.O_SHLOCK
os.O_EXLOCK

以上常量是擴充套件,如果 C 庫未定義,則不存在。

3.4 版本中的變化: 在支援的系統上添加了 O_PATH。添加了 O_TMPFILE,僅在 Linux 核心 3.11 或更高版本上可用。

os.openpty()

開啟一個新的偽終端對。返回 pty 和 tty 的檔案描述符對 (master, slave)。新的檔案描述符是 不可繼承的。對於(稍微)更具可移植性的方法,請使用 pty 模組。

可用性: Unix,不包括 WASI。

3.4 版本中的變化: 新的檔案描述符現在是不可繼承的。

os.pipe()

建立一個管道。返回一對可用於讀寫的檔案描述符 (r, w)。新的檔案描述符是 不可繼承的

可用性: Unix, Windows。

3.4 版本中的變化: 新的檔案描述符現在是不可繼承的。

os.pipe2(flags, /)

以原子方式設定 *flags* 建立一個管道。*flags* 可以透過將一個或多個以下值進行或運算來構造:O_NONBLOCKO_CLOEXEC。返回一對可用於讀寫的檔案描述符 (r, w)

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.posix_fallocate(fd, offset, len, /)

確保為由 *fd* 指定的檔案分配足夠的磁碟空間,從 *offset* 開始並持續 *len* 位元組。

可用性: Unix。

在 3.3 版本加入。

os.posix_fadvise(fd, offset, len, advice, /)

宣佈以特定模式訪問資料的意圖,從而允許核心進行最佳化。該建議適用於由 *fd* 指定的檔案區域,從 *offset* 開始並持續 *len* 位元組。*advice* 是 POSIX_FADV_NORMALPOSIX_FADV_SEQUENTIALPOSIX_FADV_RANDOMPOSIX_FADV_NOREUSEPOSIX_FADV_WILLNEEDPOSIX_FADV_DONTNEED 之一。

可用性: Unix。

在 3.3 版本加入。

os.POSIX_FADV_NORMAL
os.POSIX_FADV_SEQUENTIAL
os.POSIX_FADV_RANDOM
os.POSIX_FADV_NOREUSE
os.POSIX_FADV_WILLNEED
os.POSIX_FADV_DONTNEED

可在 posix_fadvise() 的 *advice* 中使用的標誌,指定可能使用的訪問模式。

可用性: Unix。

在 3.3 版本加入。

os.pread(fd, n, offset, /)

從檔案描述符 *fd* 在位置 *offset* 處最多讀取 *n* 位元組,檔案偏移量保持不變。

返回包含讀取位元組的位元組串。如果已到達由 *fd* 引用的檔案末尾,則返回空位元組物件。

可用性: Unix。

在 3.3 版本加入。

os.posix_openpt(oflag, /)

開啟並返回主偽終端裝置的檔案描述符。

呼叫 C 標準庫函式 posix_openpt()。*oflag* 引數用於設定檔案狀態標誌和檔案訪問模式,具體取決於您系統上 posix_openpt() 的手冊頁中的規定。

返回的檔案描述符是 不可繼承的。如果系統上提供了值 O_CLOEXEC,則將其新增到 *oflag*。

可用性: Unix,不包括 WASI。

在 3.13 版本加入。

os.preadv(fd, buffers, offset, flags=0, /)

從檔案描述符 *fd* 在位置 *offset* 讀取到可變 bytes-like 物件 *buffers* 中,檔案偏移量保持不變。將資料傳輸到每個緩衝區直到其已滿,然後移動到序列中的下一個緩衝區以容納其餘資料。

*flags* 引數包含以下零個或多個標誌的按位或

返回實際讀取的總位元組數,這可能小於所有物件的總容量。

作業系統可能會對可使用的緩衝區數量設定限制(sysconf()'SC_IOV_MAX')。

結合了 os.readv()os.pread() 的功能。

可用性:Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1。

使用 flags 需要 Linux >= 4.6。

在 3.7 版本加入。

os.RWF_NOWAIT

不等待不可立即獲得的資料。如果指定此標誌,如果系統呼叫需要從後端儲存讀取資料或等待鎖,它將立即返回。

如果成功讀取了一些資料,它將返回讀取的位元組數。如果沒有讀取任何位元組,它將返回 -1 並將 errno 設定為 errno.EAGAIN

可用性:Linux >= 4.14。

在 3.7 版本加入。

os.RWF_HIPRI

高優先順序讀/寫。允許基於塊的檔案系統使用裝置輪詢,這提供了更低的延遲,但可能使用額外的資源。

目前在 Linux 上,此功能僅適用於使用 O_DIRECT 標誌開啟的檔案描述符。

可用性:Linux >= 4.6。

在 3.7 版本加入。

os.ptsname(fd, /)

返回與檔案描述符 fd 所引用的主偽終端裝置關聯的從偽終端裝置的名稱。檔案描述符 fd 在失敗時不會關閉。

如果可重入的 C 標準庫函式 ptsname_r() 可用,則呼叫它;否則,呼叫 C 標準庫函式 ptsname(),該函式不保證是執行緒安全的。

可用性: Unix,不包括 WASI。

在 3.13 版本加入。

os.pwrite(fd, str, offset, /)

將位元組串 str 寫入檔案描述符 fdoffset 位置,檔案偏移量保持不變。

返回實際寫入的位元組數。

可用性: Unix。

在 3.3 版本加入。

os.pwritev(fd, buffers, offset, flags=0, /)

buffers 的內容寫入檔案描述符 fd 的偏移量 offset 處,檔案偏移量保持不變。buffers 必須是 bytes-like objects 的序列。緩衝區按陣列順序處理。第一個緩衝區的全部內容寫入完成後才處理第二個緩衝區,以此類推。

*flags* 引數包含以下零個或多個標誌的按位或

返回實際寫入的總位元組數。

作業系統可能會對可使用的緩衝區數量設定限制(sysconf()'SC_IOV_MAX')。

結合了 os.writev()os.pwrite() 的功能。

可用性:Linux >= 2.6.30, FreeBSD >= 6.0, OpenBSD >= 2.7, AIX >= 7.1。

使用 flags 需要 Linux >= 4.6。

在 3.7 版本加入。

os.RWF_DSYNC

提供等效於 O_DSYNC os.open() 標誌的每次寫入行為。此標誌的效果僅適用於系統呼叫寫入的資料範圍。

可用性:Linux >= 4.7。

在 3.7 版本加入。

os.RWF_SYNC

提供等效於 O_SYNC os.open() 標誌的每次寫入行為。此標誌的效果僅適用於系統呼叫寫入的資料範圍。

可用性:Linux >= 4.7。

在 3.7 版本加入。

os.RWF_APPEND

提供等效於 O_APPEND os.open() 標誌的每次寫入行為。此標誌僅對 os.pwritev() 有意義,其效果僅適用於系統呼叫寫入的資料範圍。offset 引數不影響寫入操作;資料總是附加到檔案末尾。但是,如果 offset 引數為 -1,則當前檔案 offset 會更新。

可用性:Linux >= 4.16。

在 3.10 版本加入。

os.read(fd, n, /)

從檔案描述符 fd 讀取最多 n 個位元組。

返回包含讀取位元組的位元組串。如果已到達由 *fd* 引用的檔案末尾,則返回空位元組物件。

備註

此函式用於低階 I/O,必須應用於 os.open()pipe() 返回的檔案描述符。要讀取內建函式 open()popen()fdopen() 返回的“檔案物件”,或者 sys.stdin,請使用其 read()readline() 方法。

3.5 版中變更: 如果系統呼叫被中斷且訊號處理程式未引發異常,則該函式現在會重試系統呼叫,而不是引發 InterruptedError 異常(有關原因,請參閱 PEP 475)。

os.readinto(fd, buffer, /)

從檔案描述符 fd 讀取到可變的 緩衝區物件 buffer 中。

buffer 應該是可變的且為 bytes-like 型別。成功時,返回讀取的位元組數。讀取的位元組數可能小於緩衝區的大小。底層系統呼叫在被訊號中斷時會重試,除非訊號處理程式引發異常。其他錯誤不會重試,並且會引發錯誤。

如果 fd 位於檔案末尾或提供的 buffer 長度為 0(這可用於檢查錯誤而不讀取資料),則返回 0。從不返回負值。

備註

此函式用於低階 I/O,必須應用於 os.open()os.pipe() 返回的檔案描述符。要讀取內建函式 open()sys.stdin 返回的“檔案物件”,請使用其成員函式,例如 io.BufferedIOBase.readinto()io.BufferedIOBase.read()io.TextIOBase.read()

在 3.14 版本加入。

os.sendfile(out_fd, in_fd, offset, count)
os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

從檔案描述符 in_fdoffset 位置開始,複製 count 位元組到檔案描述符 out_fd。返回傳送的位元組數。到達檔案末尾時返回 0

第一個函式符號受所有定義了 sendfile() 的平臺支援。

在 Linux 上,如果 offset 給定為 None,則從 in_fd 的當前位置讀取位元組,並更新 in_fd 的位置。

在 macOS 和 FreeBSD 上可以使用第二種情況,其中 headerstrailers 是任意的緩衝區序列,在寫入來自 in_fd 的資料之前和之後寫入。它返回與第一種情況相同的值。

在 macOS 和 FreeBSD 上,count 的值 0 表示傳送直到到達 in_fd 的末尾。

所有平臺都支援將套接字作為 out_fd 檔案描述符,某些平臺也允許其他型別(例如普通檔案、管道)。

跨平臺應用程式不應使用 headerstrailersflags 引數。

可用性: Unix,不包括 WASI。

備註

有關 sendfile() 的更高級別包裝器,請參閱 socket.socket.sendfile()

在 3.3 版本加入。

3.9 版中變更: 引數 outin 已重新命名為 out_fdin_fd

os.SF_NODISKIO
os.SF_MNOWAIT
os.SF_SYNC

sendfile() 函式的引數,如果實現支援它們的話。

可用性: Unix,不包括 WASI。

在 3.3 版本加入。

os.SF_NOCACHE

sendfile() 函式的引數,如果實現支援它。資料不會被快取在虛擬記憶體中,並且之後會被釋放。

可用性: Unix,不包括 WASI。

在 3.11 版本中新增。

os.set_blocking(fd, blocking, /)

設定指定檔案描述符的阻塞模式。如果 blockingFalse,則設定 O_NONBLOCK 標誌,否則清除該標誌。

另請參閱 get_blocking()socket.socket.setblocking()

可用性: Unix, Windows。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

在 Windows 上,此函式僅限於管道。

在 3.5 版本加入。

3.12 版本中的變化: 增加了對 Windows 上管道的支援。

os.splice(src, dst, count, offset_src=None, offset_dst=None, flags=0)

count 位元組從檔案描述符 src(從 offset_src 開始)傳輸到檔案描述符 dst(從 offset_dst 開始)。

可以透過指定 flags 值來修改拼接行為。可以使用以下任何變數,透過位或運算子(| 運算子)組合它們

  • 如果指定了 SPLICE_F_MOVE,則請求核心移動頁面而不是複製,但如果核心無法從管道移動頁面,仍然可以複製頁面。

  • 如果指定了 SPLICE_F_NONBLOCK,則請求核心不阻塞 I/O。這使得拼接管道操作非阻塞,但由於被拼接的檔案描述符可能會阻塞,拼接仍然可能阻塞。

  • 如果指定了 SPLICE_F_MORE,它會向核心提示後續拼接中將會有更多資料。

至少一個檔案描述符必須引用一個管道。如果 offset_srcNone,則從當前位置讀取 src;對於 offset_dst 也是如此。引用管道的檔案描述符的偏移量必須為 Nonesrcdst 所指向的檔案必須位於同一檔案系統中,否則會引發 OSError,並將 errno 設定為 errno.EXDEV

此複製是在沒有將資料從核心傳輸到使用者空間再返回核心的額外開銷的情況下完成的。此外,某些檔案系統可以實現額外的最佳化。複製操作就像兩個檔案都以二進位制模式開啟一樣。

成功完成後,返回拼接進出管道的位元組數。返回值為 0 表示輸入結束。如果 src 引用一個管道,則這意味著沒有資料可傳輸,並且由於沒有寫入器連線到管道的寫入端,因此阻塞沒有意義。

參見

splice(2) 手冊頁。

可用性:Linux >= 2.6.17,且 glibc >= 2.5

在 3.10 版本加入。

os.SPLICE_F_MOVE
os.SPLICE_F_NONBLOCK
os.SPLICE_F_MORE

在 3.10 版本加入。

os.readv(fd, buffers, /)

從檔案描述符 fd 讀取資料到多個可變的 bytes-like objects buffers 中。將資料傳輸到每個緩衝區直到其滿,然後繼續傳輸到序列中的下一個緩衝區以容納剩餘資料。

返回實際讀取的總位元組數,這可能小於所有物件的總容量。

作業系統可能會對可使用的緩衝區數量設定限制(sysconf()'SC_IOV_MAX')。

可用性: Unix。

在 3.3 版本加入。

os.tcgetpgrp(fd, /)

返回與 fd(由 os.open() 返回的已開啟檔案描述符)給定的終端關聯的程序組。

可用性: Unix,不包括 WASI。

os.tcsetpgrp(fd, pg, /)

將與 fd(由 os.open() 返回的已開啟檔案描述符)給定的終端關聯的程序組設定為 pg

可用性: Unix,不包括 WASI。

os.ttyname(fd, /)

返回一個字串,該字串指定與檔案描述符 fd 關聯的終端裝置。如果 fd 未與終端裝置關聯,則會引發異常。

可用性: Unix。

os.unlockpt(fd, /)

解鎖與檔案描述符 fd 所引用的主偽終端裝置關聯的從偽終端裝置。檔案描述符 fd 在失敗時不會關閉。

呼叫 C 標準庫函式 unlockpt()

可用性: Unix,不包括 WASI。

在 3.13 版本加入。

os.write(fd, str, /)

將位元組串 str 寫入檔案描述符 fd

返回實際寫入的位元組數。

備註

此函式用於低階 I/O,必須應用於 os.open()pipe() 返回的檔案描述符。要寫入內建函式 open()popen()fdopen() 返回的“檔案物件”,或者 sys.stdoutsys.stderr,請使用其 write() 方法。

3.5 版中變更: 如果系統呼叫被中斷且訊號處理程式未引發異常,則該函式現在會重試系統呼叫,而不是引發 InterruptedError 異常(有關原因,請參閱 PEP 475)。

os.writev(fd, buffers, /)

buffers 的內容寫入檔案描述符 fdbuffers 必須是 bytes-like objects 的序列。緩衝區按陣列順序處理。第一個緩衝區的全部內容寫入完成後才處理第二個緩衝區,以此類推。

返回實際寫入的總位元組數。

作業系統可能會對可使用的緩衝區數量設定限制(sysconf()'SC_IOV_MAX')。

可用性: Unix。

在 3.3 版本加入。

查詢終端大小

在 3.3 版本加入。

os.get_terminal_size(fd=STDOUT_FILENO, /)

(columns, lines) 的形式返回終端視窗的大小,這是一個 terminal_size 型別的元組。

可選引數 fd(預設為 STDOUT_FILENO,即標準輸出)指定應查詢哪個檔案描述符。

如果檔案描述符未連線到終端,則會引發 OSError

shutil.get_terminal_size() 是通常應該使用的高階函式,os.get_terminal_size 是低階實現。

可用性: Unix, Windows。

class os.terminal_size

一個元組的子類,包含終端視窗大小的 (columns, lines)

columns

終端視窗的字元寬度。

lines

終端視窗的字元高度。

檔案描述符的繼承

在 3.4 版本加入。

檔案描述符有一個“可繼承”標誌,指示檔案描述符是否可以被子程序繼承。從 Python 3.4 開始,Python 建立的檔案描述符預設是不可繼承的。

在 UNIX 上,不可繼承的檔案描述符在執行新程式時會在子程序中關閉,其他檔案描述符則會被繼承。

在 Windows 上,不可繼承的控制代碼和檔案描述符會在子程序中關閉,除了標準流(檔案描述符 0、1 和 2:stdin、stdout 和 stderr),它們總是被繼承。使用 spawn* 函式時,所有可繼承的控制代碼和所有可繼承的檔案描述符都會被繼承。使用 subprocess 模組時,除了標準流之外的所有檔案描述符都會被關閉,只有當 close_fds 引數為 False 時,可繼承的控制代碼才會被繼承。

在 WebAssembly 平臺上,檔案描述符無法修改。

os.get_inheritable(fd, /)

獲取指定檔案描述符的“可繼承”標誌(布林值)。

os.set_inheritable(fd, inheritable, /)

設定指定檔案描述符的“可繼承”標誌。

os.get_handle_inheritable(handle, /)

獲取指定控制代碼的“可繼承”標誌(布林值)。

可用性: Windows。

os.set_handle_inheritable(handle, inheritable, /)

設定指定控制代碼的“可繼承”標誌。

可用性: Windows。

檔案和目錄

在某些 Unix 平臺上,許多這些函式支援以下一個或多個功能:

  • 指定檔案描述符:通常,提供給 os 模組中函式的 path 引數必須是指定檔案路徑的字串。但是,某些函式現在可以選擇接受一個開啟的檔案描述符作為其 path 引數。然後,該函式將在描述符所引用的檔案上操作。對於 POSIX 系統,Python 將呼叫以 f 為字首的函式變體(例如,呼叫 fchdir 而不是 chdir)。

    您可以使用 os.supports_fd 檢查在您的平臺上某個特定函式是否可以將 path 指定為檔案描述符。如果此功能不可用,使用它將引發 NotImplementedError

    如果函式還支援 dir_fdfollow_symlinks 引數,則在提供檔案描述符作為 path 時指定其中一個引數是錯誤的。

  • 相對於目錄描述符的路徑:如果 dir_fd 不為 None,它應該是一個引用目錄的檔案描述符,並且要操作的路徑應該是相對路徑;路徑將相對於該目錄。如果路徑是絕對路徑,則忽略 dir_fd。對於 POSIX 系統,Python 將呼叫帶有 at 字尾並可能帶有 f 字首的函式變體(例如,呼叫 faccessat 而不是 access)。

    您可以使用 os.supports_dir_fd 檢查在您的平臺上某個特定函式是否支援 dir_fd。如果它不可用,使用它將引發 NotImplementedError

os.access(path, mode, *, dir_fd=None, effective_ids=False, follow_symlinks=True)

使用實際的使用者 ID/組 ID 來測試對 path 的訪問許可權。請注意,大多數操作將使用有效的使用者 ID/組 ID,因此此例程可用於 suid/sgid 環境,以測試呼叫使用者是否對 path 具有指定的訪問許可權。mode 應為 F_OK 以測試 path 的存在,或者它可以是 R_OKW_OKX_OK 中的一個或多個的包含或,以測試許可權。如果允許訪問,則返回 True,否則返回 False。有關更多資訊,請參閱 Unix 手冊頁 access(2)

此函式可以支援指定 相對於目錄描述符的路徑不跟隨符號連結

如果 effective_idsTrueaccess() 將使用有效的 uid/gid 而不是真實的 uid/gid 執行訪問檢查。effective_ids 可能在您的平臺上不受支援;您可以使用 os.supports_effective_ids 檢查它是否可用。如果不可用,使用它將引發 NotImplementedError

備註

使用 access() 在實際使用 open() 開啟檔案之前檢查使用者是否被授權開啟檔案會造成安全漏洞,因為使用者可能會利用檢查和開啟檔案之間的短暫時間間隔來操縱檔案。最好使用 EAFP 技術。例如

if os.access("myfile", os.R_OK):
    with open("myfile") as fp:
        return fp.read()
return "some default data"

更好的寫法是

try:
    fp = open("myfile")
except PermissionError:
    return "some default data"
else:
    with fp:
        return fp.read()

備註

即使 access() 指示 I/O 操作會成功,它們仍然可能失敗,特別是對於網路檔案系統上的操作,這些檔案系統可能具有超出通常 POSIX 許可權位模型的許可權語義。

3.3 版中變更: 添加了 dir_fdeffective_idsfollow_symlinks 引數。

在 3.6 版本發生變更: 接受 path-like object

os.F_OK
os.R_OK
os.W_OK
os.X_OK

用作 access()mode 引數的值,分別用於測試 path 的存在性、可讀性、可寫性和可執行性。

os.chdir(path)

將當前工作目錄更改為 path

此函式可以支援 指定檔案描述符。描述符必須引用一個已開啟的目錄,而不是一個開啟的檔案。

此函式可能會引發 OSError 及其子類,例如 FileNotFoundErrorPermissionErrorNotADirectoryError

使用引數 path 引發 審計事件 os.chdir

3.3 版中變更: 在某些平臺上增加了對將 path 指定為檔案描述符的支援。

在 3.6 版本發生變更: 接受 path-like object

os.chflags(path, flags, *, follow_symlinks=True)

path 的標誌設定為數字 flagsflags 可以採用以下值的組合(按位或)(在 stat 模組中定義)

此函式可以支援 不跟隨符號連結

使用引數 pathflags 引發 審計事件 os.chflags

可用性: Unix,不包括 WASI。

3.3 版中變更: 添加了 follow_symlinks 引數。

在 3.6 版本發生變更: 接受 path-like object

os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)

path 的模式更改為數字 modemode 可以是以下值(在 stat 模組中定義)之一或其按位或組合

此函式可以支援 指定檔案描述符相對於目錄描述符的路徑不跟隨符號連結

備註

雖然 Windows 支援 chmod(),但您只能使用它設定檔案的只讀標誌(透過 stat.S_IWRITEstat.S_IREAD 常量或相應的整數值)。所有其他位都將被忽略。在 Windows 上,follow_symlinks 的預設值為 False

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

使用引數 pathmodedir_fd 引發 審計事件 os.chmod

3.3 版中變更: 添加了對將 path 指定為開啟檔案描述符的支援,以及 dir_fdfollow_symlinks 引數。

在 3.6 版本發生變更: 接受 path-like object

3.13 版中變更: 在 Windows 上添加了對檔案描述符和 follow_symlinks 引數的支援。

os.chown(path, uid, gid, *, dir_fd=None, follow_symlinks=True)

path 的所有者和組 ID 更改為數字 uidgid。要使其中一個 ID 保持不變,請將其設定為 -1。

此函式可以支援 指定檔案描述符相對於目錄描述符的路徑不跟隨符號連結

有關接受名稱和數字 ID 的高階函式,請參閱 shutil.chown()

使用引數 pathuidgiddir_fd 引發 審計事件 os.chown

可用性: Unix。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

3.3 版中變更: 添加了對將 path 指定為開啟檔案描述符的支援,以及 dir_fdfollow_symlinks 引數。

3.6 版中變更: 支援 path-like object

os.chroot(path)

將當前程序的根目錄更改為 path

可用性: Unix,不包括 WASI,不包括 Android。

在 3.6 版本發生變更: 接受 path-like object

os.fchdir(fd)

將當前工作目錄更改為由檔案描述符 fd 表示的目錄。描述符必須引用一個已開啟的目錄,而不是一個開啟的檔案。從 Python 3.3 開始,這等同於 os.chdir(fd)

使用引數 path 引發 審計事件 os.chdir

可用性: Unix。

os.getcwd()

返回表示當前工作目錄的字串。

os.getcwdb()

返回表示當前工作目錄的位元組串。

3.8 版中變更: 該函式現在在 Windows 上使用 UTF-8 編碼,而不是 ANSI 內碼表:有關原因,請參閱 PEP 529。該函式在 Windows 上不再被棄用。

os.lchflags(path, flags)

path 的標誌設定為數字 flags,類似於 chflags(),但不跟隨符號連結。從 Python 3.3 開始,這等同於 os.chflags(path, flags, follow_symlinks=False)

使用引數 pathflags 引發 審計事件 os.chflags

可用性: Unix,不包括 WASI。

在 3.6 版本發生變更: 接受 path-like object

os.lchmod(path, mode)

path 的模式更改為數字 mode。如果 path 是符號連結,則此操作會影響符號連結本身而不是目標。有關 mode 的可能值,請參閱 chmod() 的文件。從 Python 3.3 開始,這等同於 os.chmod(path, mode, follow_symlinks=False)

lchmod() 不是 POSIX 的一部分,但如果支援更改符號連結的模式,Unix 實現可能會有它。

使用引數 pathmodedir_fd 引發 審計事件 os.chmod

可用性:Unix、Windows,不支援 Linux,FreeBSD >= 1.3,NetBSD >= 1.3,不支援 OpenBSD

在 3.6 版本發生變更: 接受 path-like object

3.13 版本中的變化: 添加了對 Windows 的支援。

os.lchown(path, uid, gid)

path 的所有者和組 ID 更改為數字 uidgid。此函式不會跟隨符號連結。從 Python 3.3 開始,這等同於 os.chown(path, uid, gid, follow_symlinks=False)

使用引數 pathuidgiddir_fd 引發 審計事件 os.chown

可用性: Unix。

在 3.6 版本發生變更: 接受 path-like object

建立指向 src 的名為 dst 的硬連結。

此函式可以支援指定 src_dir_fd 和/或 dst_dir_fd 以提供 相對於目錄描述符的路徑,以及 不跟隨符號連結。在 Windows 上,follow_symlinks 的預設值為 False

使用引數 src, dst, src_dir_fd, dst_dir_fd 引發 審計事件 os.link

可用性: Unix, Windows。

3.2 版中變更: 添加了 Windows 支援。

3.3 版中變更: 添加了 src_dir_fddst_dir_fdfollow_symlinks 引數。

3.6 版中變更: 接受 srcdstpath-like object

os.listdir(path='.')

返回一個列表,其中包含由 path 指定的目錄中的條目名稱。列表的順序是任意的,並且不包括特殊條目 '.''..',即使它們存在於目錄中。如果在呼叫此函式期間從目錄中刪除或添加了檔案,則是否包含該檔案的名稱是未指定的。

path 可以是 path-like object。如果 path 的型別為 bytes(直接或透過 PathLike 介面間接),則返回的檔名也將是 bytes 型別;在所有其他情況下,它們將是 str 型別。

此函式還可以支援 指定檔案描述符;檔案描述符必須引用一個目錄。

使用引數 path 引發 審計事件 os.listdir

備註

要將 str 檔名編碼為 bytes,請使用 fsencode()

參見

scandir() 函式返回目錄條目以及檔案屬性資訊,為許多常見用例提供了更好的效能。

3.2 版中變更: path 引數變為可選。

3.3 版中變更: 添加了對將 path 指定為開啟檔案描述符的支援。

在 3.6 版本發生變更: 接受 path-like object

os.listdrives()

返回一個列表,其中包含 Windows 系統上的驅動器名稱。

驅動器名稱通常類似於 'C:\\'。並非每個驅動器名稱都與卷關聯,並且由於各種原因(包括許可權、網路連線或缺少媒體),某些驅動器可能無法訪問。此函式不測試訪問許可權。

如果收集驅動器名稱時發生錯誤,可能會引發 OSError

不帶引數地引發 審計事件 os.listdrives

可用性: Windows

3.12 新版功能.

os.listmounts(volume)

返回一個列表,其中包含 Windows 系統上卷的掛載點。

volume 必須表示為 GUID 路徑,例如由 os.listvolumes() 返回的那些。卷可以掛載在多個位置,或者根本不掛載。在後一種情況下,列表將為空。不與卷關聯的掛載點不會由本函式返回。

本函式返回的掛載點將是絕對路徑,並且可能比驅動器名稱長。

如果卷無法識別或收集路徑時發生錯誤,則引發 OSError

使用引數 volume 引發 審計事件 os.listmounts

可用性: Windows

3.12 新版功能.

os.listvolumes()

返回包含系統中卷的列表。

卷通常表示為 GUID 路徑,看起來像 \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\。檔案通常可以透過 GUID 路徑訪問,只要許可權允許。但是,使用者通常不熟悉它們,因此建議使用此函式透過 os.listmounts() 檢索掛載點。

如果收集卷時發生錯誤,則可能引發 OSError

使用無引數引發 審計事件 os.listvolumes

可用性: Windows

3.12 新版功能.

os.lstat(path, *, dir_fd=None)

對給定路徑執行等同於 lstat() 系統呼叫的操作。類似於 stat(),但不遵循符號連結。返回一個 stat_result 物件。

在不支援符號連結的平臺上,這等同於 stat()

自 Python 3.3 起,這等同於 os.stat(path, dir_fd=dir_fd, follow_symlinks=False)

此函式還可以支援 相對於目錄描述符的路徑

參見

stat() 函式。

3.2 版中已更改: 添加了對 Windows 6.0 (Vista) 符號連結的支援。

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

3.8 版中已更改: 在 Windows 上,現在開啟表示另一個路徑(名稱代理)的重解析點,包括符號連結和目錄連線點。其他型別的重解析點由作業系統像 stat() 一樣解析。

os.mkdir(path, mode=0o777, *, dir_fd=None)

建立名為 path 的目錄,並使用數字模式 mode

如果目錄已存在,則引發 FileExistsError。如果路徑中的父目錄不存在,則引發 FileNotFoundError

在某些系統上,mode 被忽略。在使用它的地方,當前的 umask 值首先被遮蔽掉。如果設定了最後 9 位以外的位(即 mode 的八進位制表示的最後 3 位),它們的含義取決於平臺。在某些平臺上,它們被忽略,您應該顯式呼叫 chmod() 來設定它們。

在 Windows 上,0o700mode 被特殊處理,以對新目錄應用訪問控制,以便只有當前使用者和管理員才能訪問。mode 的其他值被忽略。

此函式還可以支援 相對於目錄描述符的路徑

也可以建立臨時目錄;請參見 tempfile 模組的 tempfile.mkdtemp() 函式。

使用引數 pathmodedir_fd 引發 審計事件 os.mkdir

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

3.13 版中已更改: Windows 現在處理 0o700mode

os.makedirs(name, mode=0o777, exist_ok=False)

遞迴目錄建立函式。類似於 mkdir(),但會建立包含葉目錄所需的所有中間級目錄。

mode 引數傳遞給 mkdir() 以建立葉目錄;有關其解釋方式,請參見 mkdir() 說明。要設定任何新建立的父目錄的檔案許可權位,您可以在呼叫 makedirs() 之前設定 umask。現有父目錄的檔案許可權位不會更改。

如果 exist_okFalse(預設值),如果目標目錄已存在,則引發 FileExistsError

備註

如果要建立的路徑元素包含 pardir(例如 UNIX 系統上的“..”),makedirs() 將會混淆。

此函式正確處理 UNC 路徑。

使用引數 pathmodedir_fd 引發 審計事件 os.mkdir

3.2 版中已更改: 添加了 exist_ok 引數。

3.4.1 版中已更改: 在 Python 3.4.1 之前,如果 exist_okTrue 且目錄已存在,如果 mode 與現有目錄的模式不匹配,makedirs() 仍然會引發錯誤。由於此行為無法安全實現,因此在 Python 3.4.1 中已刪除。請參見 bpo-21082

在 3.6 版本發生變更: 接受 path-like object

3.7 版中已更改: mode 引數不再影響新建立的中間級目錄的檔案許可權位。

os.mkfifo(path, mode=0o666, *, dir_fd=None)

使用數字模式 mode 建立一個名為 path 的 FIFO(命名管道)。當前的 umask 值首先從模式中遮蔽掉。

此函式還可以支援 相對於目錄描述符的路徑

FIFO 是可以像常規檔案一樣訪問的管道。FIFO 存在直到它們被刪除(例如使用 os.unlink())。通常,FIFO 用作“客戶端”和“伺服器”型別程序之間的集合點:伺服器開啟 FIFO 以進行讀取,客戶端開啟它以進行寫入。請注意,mkfifo() 不會開啟 FIFO — 它只是建立集合點。

可用性: Unix,不包括 WASI。

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

os.mknod(path, mode=0o600, device=0, *, dir_fd=None)

建立名為 path 的檔案系統節點(檔案、裝置特殊檔案或命名管道)。mode 指定要使用的許可權和要建立的節點型別,與 stat.S_IFREGstat.S_IFCHRstat.S_IFBLKstat.S_IFIFO 中的一個(這些常量可在 stat 中獲得)組合(按位或)。對於 stat.S_IFCHRstat.S_IFBLKdevice 定義新建立的裝置特殊檔案(可能使用 os.makedev()),否則它將被忽略。

此函式還可以支援 相對於目錄描述符的路徑

可用性: Unix,不包括 WASI。

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

os.major(device, /)

從原始裝置號中提取裝置主編號(通常是 stat 中的 st_devst_rdev 欄位)。

os.minor(device, /)

從原始裝置號中提取裝置次編號(通常是 stat 中的 st_devst_rdev 欄位)。

os.makedev(major, minor, /)

根據主裝置號和次裝置號組合原始裝置號。

os.pathconf(path, name)

返回與命名檔案相關的系統配置資訊。name 指定要檢索的配置值;它可能是一個字串,是已定義系統值的名稱;這些名稱在許多標準(POSIX.1、Unix 95、Unix 98 等)中指定。某些平臺也定義了其他名稱。宿主作業系統已知的名稱在 pathconf_names 字典中給出。對於未包含在該對映中的配置變數,也接受將整數作為 name 傳遞。

如果 *name* 是字串且未知,則引發 ValueError。如果主機系統不支援 *name* 的特定值,即使它包含在 pathconf_names 中,也會引發 OSError,錯誤號為 errno.EINVAL

此函式可以支援 指定檔案描述符

可用性: Unix。

在 3.6 版本發生變更: 接受 path-like object

os.pathconf_names

pathconf()fpathconf() 接受的名稱對映到主機作業系統為這些名稱定義的整數值的字典。這可用於確定系統已知的名稱集。

可用性: Unix。

返回一個字串,表示符號連結指向的路徑。結果可以是絕對路徑名或相對路徑名;如果是相對路徑名,可以使用 os.path.join(os.path.dirname(path), result) 轉換為絕對路徑名。

如果 path 是字串物件(直接或間接透過 PathLike 介面),結果也將是字串物件,並且呼叫可能會引發 UnicodeDecodeError。如果 path 是位元組物件(直接或間接),結果將是位元組物件。

此函式還可以支援 相對於目錄描述符的路徑

當嘗試解析可能包含連結的路徑時,請使用 realpath() 來正確處理遞迴和平臺差異。

可用性: Unix, Windows。

3.2 版中已更改: 添加了對 Windows 6.0 (Vista) 符號連結的支援。

3.3 版本中的變化: 添加了 *dir_fd* 引數。

3.6 版中已更改: 在 Unix 上接受 類路徑物件

3.8 版中已更改: 在 Windows 上接受 類路徑物件 和位元組物件。

添加了對目錄連線點的支援,並更改為返回替換路徑(通常包含 \\?\ 字首),而不是以前返回的可選“列印名稱”欄位。

os.remove(path, *, dir_fd=None)

刪除檔案 path。如果 path 是目錄,則引發 OSError。使用 rmdir() 刪除目錄。如果檔案不存在,則引發 FileNotFoundError

此函式可以支援 相對於目錄描述符的路徑

在 Windows 上,嘗試刪除正在使用的檔案會導致引發異常;在 Unix 上,目錄條目被刪除,但分配給檔案的儲存空間在原始檔案不再使用之前不會可用。

此函式在語義上等同於 unlink()

使用引數 pathdir_fd 引發 審計事件 os.remove

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

os.removedirs(name)

遞迴刪除目錄。類似於 rmdir(),但如果葉目錄成功刪除,removedirs() 會嘗試連續刪除 path 中提到的每個父目錄,直到引發錯誤(該錯誤被忽略,因為它通常意味著父目錄不為空)。例如,os.removedirs('foo/bar/baz') 將首先刪除目錄 'foo/bar/baz',然後如果 'foo/bar''foo' 為空,則刪除它們。如果葉目錄無法成功刪除,則引發 OSError

使用引數 pathdir_fd 引發 審計事件 os.remove

在 3.6 版本發生變更: 接受 path-like object

os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

將檔案或目錄 src 重新命名為 dst。如果 dst 存在,該操作在多種情況下將以 OSError 的子類失敗。

在 Windows 上,如果 dst 存在,則總是引發 FileExistsError。如果 srcdst 在不同的檔案系統上,操作可能會失敗。使用 shutil.move() 來支援移動到不同的檔案系統。

在 Unix 上,如果 src 是檔案而 dst 是目錄,或反之,將分別引發 IsADirectoryErrorNotADirectoryError。如果兩者都是目錄且 dst 為空,dst 將被靜默替換。如果 dst 是非空目錄,則引發 OSError。如果兩者都是檔案,如果使用者有許可權,dst 將被靜默替換。在某些 Unix 變種上,如果 srcdst 在不同的檔案系統上,操作可能會失敗。如果成功,重新命名將是原子操作(這是 POSIX 要求)。

此函式可以支援指定 src_dir_fd 和/或 dst_dir_fd 以提供 相對於目錄描述符的路徑

如果您希望跨平臺覆蓋目標,請使用 replace()

使用引數 srcdstsrc_dir_fddst_dir_fd 引發 審計事件 os.rename

3.3 版中已更改: 添加了 src_dir_fddst_dir_fd 引數。

3.6 版中變更: 接受 srcdstpath-like object

os.renames(old, new)

遞迴目錄或檔案重新命名函式。作用類似於 rename(),但會首先嚐試建立使新路徑名有效的任何中間目錄。重新命名後,將使用 removedirs() 剪除舊名稱最右側路徑段對應的目錄。

備註

如果您缺少刪除葉目錄或檔案所需的許可權,此函式可能會在新目錄結構已建立的情況下失敗。

使用引數 srcdstsrc_dir_fddst_dir_fd 引發 審計事件 os.rename

3.6 版中已更改: 接受 oldnew類路徑物件

os.replace(src, dst, *, src_dir_fd=None, dst_dir_fd=None)

將檔案或目錄 src 重新命名為 dst。如果 dst 是非空目錄,則會引發 OSError。如果 dst 存在且是檔案,則在使用者有許可權的情況下會靜默替換。如果 srcdst 位於不同的檔案系統上,操作可能會失敗。如果成功,重新命名將是原子操作(這是 POSIX 要求)。

此函式可以支援指定 src_dir_fd 和/或 dst_dir_fd 以提供 相對於目錄描述符的路徑

使用引數 srcdstsrc_dir_fddst_dir_fd 引發 審計事件 os.rename

在 3.3 版本加入。

3.6 版中變更: 接受 srcdstpath-like object

os.rmdir(path, *, dir_fd=None)

移除(刪除)目錄 path。如果目錄不存在或不為空,則分別引發 FileNotFoundErrorOSError。為了移除整個目錄樹,可以使用 shutil.rmtree()

此函式可以支援 相對於目錄描述符的路徑

使用引數 pathdir_fd 引發 審計事件 os.rmdir

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

os.scandir(path='.')

返回一個 os.DirEntry 物件迭代器,對應於 path 給定目錄中的條目。條目以任意順序生成,特殊條目 '.''..' 不包括在內。如果在建立迭代器後從目錄中刪除或新增檔案,是否包含該檔案的條目是未指定的。

使用 scandir() 而不是 listdir() 可以顯著提高還需要檔案型別或檔案屬性資訊的程式碼的效能,因為 os.DirEntry 物件在掃描目錄時如果作業系統提供此資訊,則會公開此資訊。所有 os.DirEntry 方法都可能執行系統呼叫,但 is_dir()is_file() 通常只需要對符號連結進行系統呼叫;os.DirEntry.stat() 在 Unix 上總是需要系統呼叫,但在 Windows 上只對符號連結需要系統呼叫。

path 可以是 類路徑物件。如果 pathbytes 型別(直接或間接透過 PathLike 介面),則每個 os.DirEntrynamepath 屬性的型別將是 bytes;在所有其他情況下,它們將是 str 型別。

此函式還可以支援 指定檔案描述符;檔案描述符必須引用一個目錄。

使用引數 path 引發 審計事件 os.scandir

scandir() 迭代器支援 上下文管理器 協議並具有以下方法

scandir.close()

關閉迭代器並釋放已獲取的資源。

當迭代器耗盡或被垃圾回收時,或在迭代過程中發生錯誤時,此函式會自動呼叫。但是,建議顯式呼叫它或使用 with 語句。

在 3.6 版本加入。

以下示例展示了 scandir() 的簡單用法,以顯示給定 path 中不以 '.' 開頭的所有檔案(不包括目錄)。entry.is_file() 呼叫通常不會進行額外的系統呼叫。

with os.scandir(path) as it:
    for entry in it:
        if not entry.name.startswith('.') and entry.is_file():
            print(entry.name)

備註

在基於 Unix 的系統上,scandir() 使用系統的 opendir()readdir() 函式。在 Windows 上,它使用 Win32 FindFirstFileWFindNextFileW 函式。

在 3.5 版本加入。

3.6 版中已更改: 添加了對 上下文管理器 協議和 close() 方法的支援。如果 scandir() 迭代器既未耗盡也未顯式關閉,則在其解構函式中將發出 ResourceWarning

該函式接受 類路徑物件

3.7 版中已更改: 在 Unix 上添加了對 檔案描述符 的支援。

class os.DirEntry

scandir() 生成的物件,用於公開目錄條目的檔案路徑和其他檔案屬性。

scandir() 將在不進行額外系統呼叫的情況下儘可能多地提供此資訊。當執行 stat()lstat() 系統呼叫時,os.DirEntry 物件將快取結果。

os.DirEntry 例項不應儲存在長期資料結構中;如果您知道檔案元資料已更改或自呼叫 scandir() 以來已過去很長時間,請呼叫 os.stat(entry.path) 以獲取最新資訊。

因為 os.DirEntry 方法可以進行作業系統呼叫,所以它們也可能引發 OSError。如果您需要對錯誤進行非常細粒度的控制,可以在呼叫 os.DirEntry 方法之一時捕獲 OSError 並進行適當處理。

為了直接用作 類路徑物件os.DirEntry 實現了 PathLike 介面。

os.DirEntry 例項的屬性和方法如下

name

條目的基本檔名,相對於 scandir() path 引數。

如果 scandir() path 引數是 bytes 型別,則 name 屬性將為 bytes,否則為 str。使用 fsdecode() 解碼位元組檔名。

path

條目的完整路徑名:等同於 os.path.join(scandir_path, entry.name),其中 scandir_pathscandir() path 引數。路徑只有在 scandir() path 引數是絕對路徑時才是絕對路徑。如果 scandir() path 引數是 檔案描述符,則 path 屬性與 name 屬性相同。

如果 scandir() path 引數是 bytes 型別,則 path 屬性將為 bytes,否則為 str。使用 fsdecode() 解碼位元組檔名。

inode()

返回條目的 inode 號。

結果快取在 os.DirEntry 物件上。使用 os.stat(entry.path, follow_symlinks=False).st_ino 獲取最新資訊。

在第一次未快取的呼叫中,Windows 上需要系統呼叫,而 Unix 上不需要。

is_dir(*, follow_symlinks=True)

如果此條目是目錄或指向目錄的符號連結,則返回 True;如果此條目是或指向任何其他型別的檔案,或者它不再存在,則返回 False

如果 follow_symlinksFalse,則僅當此條目是目錄時才返回 True(不跟隨符號連結);如果此條目是任何其他型別的檔案,或者它不再存在,則返回 False

結果快取在 os.DirEntry 物件上,為 follow_symlinks TrueFalse 分別設定了單獨的快取。呼叫 os.stat() 以及 stat.S_ISDIR() 以獲取最新資訊。

在第一次未快取的呼叫中,大多數情況下不需要系統呼叫。具體來說,對於非符號連結,Windows 和 Unix 都不需要系統呼叫,除了某些 Unix 檔案系統(例如網路檔案系統)返回 dirent.d_type == DT_UNKNOWN 的情況。如果條目是符號連結,則除非 follow_symlinksFalse,否則需要系統呼叫才能跟隨符號連結。

此方法可以引發 OSError,例如 PermissionError,但 FileNotFoundError 被捕獲而不會引發。

is_file(*, follow_symlinks=True)

如果此條目是檔案或指向檔案的符號連結,則返回 True;如果此條目是或指向目錄或其他非檔案條目,或者它不再存在,則返回 False

如果 follow_symlinksFalse,則僅當此條目是檔案時才返回 True(不跟隨符號連結);如果此條目是目錄或其他非檔案條目,或者它不再存在,則返回 False

結果快取在 os.DirEntry 物件上。快取、進行的系統呼叫和引發的異常與 is_dir() 相同。

如果此條目是符號連結(即使已損壞),則返回 True;如果此條目指向目錄或任何型別的檔案,或者它不再存在,則返回 False

結果快取在 os.DirEntry 物件上。呼叫 os.path.islink() 以獲取最新資訊。

在第一次未快取的呼叫中,大多數情況下不需要系統呼叫。具體來說,Windows 和 Unix 都不需要系統呼叫,除了某些 Unix 檔案系統(例如網路檔案系統)返回 dirent.d_type == DT_UNKNOWN 的情況。

此方法可以引發 OSError,例如 PermissionError,但 FileNotFoundError 被捕獲而不會引發。

is_junction()

如果此條目是連線點(即使已損壞),則返回 True;如果此條目指向常規目錄、任何型別的檔案、符號連結,或者它不再存在,則返回 False

結果快取在 os.DirEntry 物件上。呼叫 os.path.isjunction() 以獲取最新資訊。

3.12 新版功能.

stat(*, follow_symlinks=True)

返回此條目的 stat_result 物件。此方法預設跟隨符號連結;要對符號連結進行 stat,請新增引數 follow_symlinks=False

在 Unix 上,此方法總是需要系統呼叫。在 Windows 上,它只在 follow_symlinksTrue 且條目是重解析點(例如,符號連結或目錄連線點)時才需要系統呼叫。

在 Windows 上,stat_resultst_inost_devst_nlink 屬性總是設定為零。呼叫 os.stat() 獲取這些屬性。

結果快取在 os.DirEntry 物件上,為 follow_symlinks TrueFalse 分別設定了單獨的快取。呼叫 os.stat() 以獲取最新資訊。

請注意,os.DirEntry 的幾個屬性和方法與 pathlib.Path 的幾個屬性和方法之間存在很好的對應關係。特別是,name 屬性具有相同的含義,is_dir()is_file()is_symlink()is_junction()stat() 方法也如此。

在 3.5 版本加入。

3.6 版中已更改: 添加了對 PathLike 介面的支援。添加了對 Windows 上 bytes 路徑的支援。

3.12 版中已更改: 在 Windows 上,stat 結果的 st_ctime 屬性已棄用。檔案建立時間可正確作為 st_birthtime 獲取,將來 st_ctime 可能會更改為返回零或元資料更改時間(如果可用)。

os.stat(path, *, dir_fd=None, follow_symlinks=True)

獲取檔案或檔案描述符的狀態。對給定路徑執行等同於 stat() 系統呼叫的操作。path 可以指定為字串或位元組——直接或間接透過 PathLike 介面——或作為開啟的檔案描述符。返回一個 stat_result 物件。

此函式通常遵循符號連結;要對符號連結進行 stat,請新增引數 follow_symlinks=False,或使用 lstat()

此函式可以支援 指定檔案描述符不跟隨符號連結

在 Windows 上,傳遞 follow_symlinks=False 將停用所有名稱代理重解析點的跟隨,包括符號連結和目錄連線點。不類似連結或作業系統無法跟隨的其他型別的重解析點將直接開啟。當跟隨多個連結鏈時,這可能會導致返回原始連結而不是阻止完全遍歷的非連結。要在此情況下獲取最終路徑的 stat 結果,請使用 os.path.realpath() 函式儘可能地解析路徑名,並對結果呼叫 lstat()。這不適用於懸空符號連結或連線點,它們將引發通常的異常。

示例

>>> import os
>>> statinfo = os.stat('somefile.txt')
>>> statinfo
os.stat_result(st_mode=33188, st_ino=7876932, st_dev=234881026,
st_nlink=1, st_uid=501, st_gid=501, st_size=264, st_atime=1297230295,
st_mtime=1297230027, st_ctime=1297230027)
>>> statinfo.st_size
264

參見

fstat()lstat() 函式。

3.3 版中已更改: 添加了 dir_fdfollow_symlinks 引數,指定檔案描述符而不是路徑。

在 3.6 版本發生變更: 接受 path-like object

3.8 版中已更改: 在 Windows 上,現在遵循所有可由作業系統解析的重解析點,並且傳遞 follow_symlinks=False 停用所有名稱代理重解析點的跟隨。如果作業系統遇到無法跟隨的重解析點,stat 現在返回原始路徑的資訊,就像指定了 follow_symlinks=False 而不是引發錯誤一樣。

class os.stat_result

其屬性大致對應於 stat 結構的成員的物件。它用於 os.stat()os.fstat()os.lstat() 的結果。

屬性

st_mode

檔案模式:檔案型別和檔案模式位(許可權)。

st_ino

平臺相關,但如果非零,則唯一標識給定 st_dev 值的檔案。通常是

st_dev

此檔案所在的裝置的識別符號。

硬連結數。

st_uid

檔案所有者的使用者識別符號。

st_gid

檔案所有者的組識別符號。

st_size

檔案大小(以位元組為單位),如果它是常規檔案或符號連結。符號連結的大小是它所包含的路徑名的長度,不帶終止空位元組。

時間戳

st_atime

最近訪問時間,以秒為單位表示。

st_mtime

最近內容修改時間,以秒為單位表示。

st_ctime

最近元資料更改時間,以秒為單位表示。

3.12 版本中已更改: Windows 上 st_ctime 已棄用。檔案建立時間請使用 st_birthtime。將來,st_ctime 將包含最近元資料更改時間,與其他平臺一致。

st_atime_ns

最近訪問時間,以納秒為單位的整數表示。

在 3.3 版本加入。

st_mtime_ns

最近內容修改時間,以納秒為單位的整數表示。

在 3.3 版本加入。

st_ctime_ns

最近元資料更改時間,以納秒為單位的整數表示。

在 3.3 版本加入。

3.12 版本中已更改: Windows 上 st_ctime_ns 已棄用。檔案建立時間請使用 st_birthtime_ns。將來,st_ctime 將包含最近元資料更改時間,與其他平臺一致。

st_birthtime

檔案建立時間,以秒為單位表示。此屬性並非總是可用,可能會引發 AttributeError

3.12 版本中已更改: st_birthtime 現已在 Windows 上可用。

st_birthtime_ns

檔案建立時間,以納秒為單位的整數表示。此屬性並非總是可用,可能會引發 AttributeError

3.12 新版功能.

備註

st_atimest_mtimest_ctimest_birthtime 屬性的確切含義和解析度取決於作業系統和檔案系統。例如,在使用 FAT32 檔案系統的 Windows 系統上,st_mtime 的解析度為 2 秒,而 st_atime 的解析度僅為 1 天。有關詳細資訊,請參閱您的作業系統文件。

同樣,儘管 st_atime_nsst_mtime_nsst_ctime_nsst_birthtime_ns 總是以納秒錶示,但許多系統不提供納秒精度。在提供納秒精度的系統上,用於儲存 st_atimest_mtimest_ctimest_birthtime 的浮點物件無法保留所有精度,因此會略有不精確。如果需要精確的時間戳,應始終使用 st_atime_nsst_mtime_nsst_ctime_nsst_birthtime_ns

在某些 Unix 系統(例如 Linux)上,以下屬性也可能可用

st_blocks

為檔案分配的 512 位元組塊的數量。當檔案有空洞時,這可能小於 st_size/512。

st_blksize

用於高效檔案系統 I/O 的“首選”塊大小。以較小的塊寫入檔案可能會導致低效的讀取-修改-重寫。

st_rdev

如果是 inode 裝置,則為裝置型別。

st_flags

使用者定義的檔案標誌。

在其他 Unix 系統(例如 FreeBSD)上,以下屬性可能可用(但可能只有在 root 嘗試使用它們時才會填充)

st_gen

檔案生成號。

在 Solaris 及其派生系統上,以下屬性也可能可用

st_fstype

唯一標識包含該檔案的檔案系統型別的字串。

在 macOS 系統上,以下屬性也可能可用

st_rsize

檔案的實際大小。

st_creator

檔案的建立者。

st_type

檔案型別。

在 Windows 系統上,以下屬性也可用

st_file_attributes

Windows 檔案屬性:GetFileInformationByHandle() 返回的 BY_HANDLE_FILE_INFORMATION 結構中的 dwFileAttributes 成員。請參閱 stat 模組中的 FILE_ATTRIBUTE_* <stat.FILE_ATTRIBUTE_ARCHIVE> 常量。

在 3.5 版本加入。

st_reparse_tag

st_file_attributes 設定了 FILE_ATTRIBUTE_REPARSE_POINT 時,此欄位包含標識重解析點型別的標籤。請參閱 stat 模組中的 IO_REPARSE_TAG_* 常量。

標準模組 stat 定義了用於從 stat 結構中提取資訊的函式和常量。(在 Windows 上,某些項填充了虛擬值。)

為了向後相容,stat_result 例項也可以作為至少包含 10 個整數的元組訪問,這些整數按 st_modest_inost_devst_nlinkst_uidst_gidst_sizest_atimest_mtimest_ctime 的順序給出 stat 結構中最重要的(和可移植的)成員。某些實現可能會在末尾新增更多項。為了與舊版 Python 相容,將 stat_result 作為元組訪問始終返回整數。

3.5 版本中已更改: Windows 現在在可用時將檔案索引作為 st_ino 返回。

3.7 版本中已更改: 為 Solaris/派生系統添加了 st_fstype 成員。

3.8 版本中已更改: 在 Windows 上添加了 st_reparse_tag 成員。

3.8 版本中已更改: 在 Windows 上,st_mode 成員現在根據需要將特殊檔案標識為 S_IFCHRS_IFIFOS_IFBLK

3.12 版本中已更改: 在 Windows 上,st_ctime 已棄用。最終,為了與其他平臺一致,它將包含最後一次元資料更改時間,但目前仍包含建立時間。請使用 st_birthtime 獲取建立時間。

在 Windows 上,st_ino 現在可能最多為 128 位,具體取決於檔案系統。以前它不會超過 64 位,較大的檔案識別符號將被任意打包。

在 Windows 上,st_rdev 不再返回值。以前它會包含與 st_dev 相同的值,這是不正確的。

在 Windows 上添加了 st_birthtime 成員。

os.statvfs(path)

對給定路徑執行 statvfs() 系統呼叫。返回值是一個物件,其屬性描述給定路徑上的檔案系統,並對應於 statvfs 結構的成員,即:f_bsizef_frsizef_blocksf_bfreef_bavailf_filesf_ffreef_favailf_flagf_namemaxf_fsid

f_flag 屬性的位標誌定義了兩個模組級常量:如果設定了 ST_RDONLY,則檔案系統以只讀方式掛載;如果設定了 ST_NOSUID,則停用或不支援 setuid/setgid 位的語義。

為基於 GNU/glibc 的系統定義了額外的模組級常量。這些是 ST_NODEV (禁止訪問裝置特殊檔案)、ST_NOEXEC (禁止程式執行)、ST_SYNCHRONOUS (寫入立即同步)、ST_MANDLOCK (允許對檔案系統進行強制鎖定)、ST_WRITE (寫入檔案/目錄/符號連結)、ST_APPEND (僅追加檔案)、ST_IMMUTABLE (不可變檔案)、ST_NOATIME (不更新訪問時間)、ST_NODIRATIME (不更新目錄訪問時間)、ST_RELATIME (相對於修改/更改時間更新訪問時間)。

此函式可以支援 指定檔案描述符

可用性: Unix。

3.2 版本中已更改: 添加了 ST_RDONLYST_NOSUID 常量。

3.3 版中變更: 添加了對將 path 指定為開啟檔案描述符的支援。

3.4 版本中已更改: 添加了 ST_NODEVST_NOEXECST_SYNCHRONOUSST_MANDLOCKST_WRITEST_APPENDST_IMMUTABLEST_NOATIMEST_NODIRATIMEST_RELATIME 常量。

在 3.6 版本發生變更: 接受 path-like object

3.7 版本中已更改: 添加了 f_fsid 屬性。

os.supports_dir_fd

一個 set 物件,指示 os 模組中的哪些函式接受檔案描述符作為其 dir_fd 引數。不同的平臺提供不同的功能,Python 用於實現 dir_fd 引數的基礎功能並非在所有 Python 支援的平臺上都可用。為了保持一致性,可能支援 dir_fd 的函式總是允許指定該引數,但如果功能在本地不可用時使用,則會引發異常。(在所有平臺上始終支援為 dir_fd 指定 None。)

要檢查特定函式是否接受檔案描述符作為其 dir_fd 引數,請在 supports_dir_fd 上使用 in 運算子。例如,如果 os.stat() 在本地平臺接受檔案描述符作為 dir_fd,則此表示式評估為 True

os.stat in os.supports_dir_fd

目前 dir_fd 引數僅適用於 Unix 平臺;它們在 Windows 上均不適用。

在 3.3 版本加入。

os.supports_effective_ids

一個 set 物件,指示 os.access() 是否允許在本地平臺為其 effective_ids 引數指定 True。(在所有平臺上始終支援為 effective_ids 指定 False。)如果本地平臺支援,則集合將包含 os.access();否則它將為空。

如果 os.access() 在本地平臺支援 effective_ids=True,則此表示式評估為 True

os.access in os.supports_effective_ids

目前 effective_ids 僅在 Unix 平臺上受支援;它在 Windows 上不適用。

在 3.3 版本加入。

os.supports_fd

一個 set 物件,指示 os 模組中的哪些函式允許在本地平臺將其 path 引數指定為開啟的檔案描述符。不同的平臺提供不同的功能,Python 用於接受開啟檔案描述符作為 path 引數的基礎功能並非在所有 Python 支援的平臺上都可用。

要確定特定函式是否允許將其 path 引數指定為開啟的檔案描述符,請在 supports_fd 上使用 in 運算子。例如,如果 os.chdir() 在您的本地平臺接受檔案描述符作為 path,則此表示式評估為 True

os.chdir in os.supports_fd

在 3.3 版本加入。

一個 set 物件,指示 os 模組中的哪些函式允許在本地平臺為其 follow_symlinks 引數接受 False。不同的平臺提供不同的功能,Python 用於實現 follow_symlinks 的基礎功能並非在所有 Python 支援的平臺上都可用。為了保持一致性,可能支援 follow_symlinks 的函式總是允許指定該引數,但如果功能在本地不可用時使用,則會引發異常。(在所有平臺上始終支援為 follow_symlinks 指定 True。)

要檢查特定函式是否接受 False 作為其 follow_symlinks 引數,請在 supports_follow_symlinks 上使用 in 運算子。例如,如果可以在本地平臺呼叫 os.stat() 時指定 follow_symlinks=False,則此表示式評估為 True

os.stat in os.supports_follow_symlinks

在 3.3 版本加入。

建立指向 src 且名為 dst 的符號連結。

在 Windows 上,符號連結表示檔案或目錄,並且不會動態變形以匹配目標。如果目標存在,將建立與目標型別匹配的符號連結。否則,如果 target_is_directoryTrue,則符號連結將建立為目錄,否則建立為檔案符號連結(預設)。在非 Windows 平臺上,target_is_directory 被忽略。

此函式可以支援 相對於目錄描述符的路徑

備註

在較新版本的 Windows 10 上,如果啟用了開發者模式,非特權帳戶可以建立符號連結。如果開發者模式不可用/未啟用,則需要 SeCreateSymbolicLinkPrivilege 許可權,或者程序必須以管理員身份執行。

當由非特權使用者呼叫此函式時,會引發 OSError

引發 審計事件 os.symlink,引數為 srcdstdir_fd

可用性: Unix, Windows。

該功能在 WASI 上受到限制,詳情請參閱 WebAssembly 平臺

3.2 版中已更改: 添加了對 Windows 6.0 (Vista) 符號連結的支援。

3.3 版本中已更改: 添加了 dir_fd 引數,現在允許在非 Windows 平臺上使用 target_is_directory

3.6 版中變更: 接受 srcdstpath-like object

3.8 版本中已更改: 在 Windows 上添加了對開發者模式下非提升許可權符號連結的支援。

os.sync()

強制將所有內容寫入磁碟。

可用性: Unix。

在 3.3 版本加入。

os.truncate(path, length)

截斷與 path 對應的檔案,使其大小最多為 length 位元組。

此函式可以支援 指定檔案描述符

引發 審計事件 os.truncate,引數為 pathlength

可用性: Unix, Windows。

在 3.3 版本加入。

3.5 版本中的變化: 增加了對 Windows 的支援

在 3.6 版本發生變更: 接受 path-like object

刪除檔案 path。此函式在語義上與 remove() 相同;unlink 名稱是其傳統的 Unix 名稱。有關更多資訊,請參閱 remove() 的文件。

使用引數 pathdir_fd 引發 審計事件 os.remove

3.3 版本中的變化: 添加了 *dir_fd* 引數。

在 3.6 版本發生變更: 接受 path-like object

os.utime(path, times=None, *, [ns, ]dir_fd=None, follow_symlinks=True)

設定由 path 指定的檔案的訪問時間和修改時間。

utime() 接受兩個可選引數,timesns。它們指定在 path 上設定的時間,並按以下方式使用

  • 如果指定了 ns,它必須是 (atime_ns, mtime_ns) 形式的 2 元組,其中每個成員都是表示納秒的整數。

  • 如果 times 不是 None,它必須是 (atime, mtime) 形式的 2 元組,其中每個成員都是表示秒的整數或浮點數。

  • 如果 timesNonens 未指定,則等效於指定 ns=(atime_ns, mtime_ns),其中兩個時間都是當前時間。

同時為 timesns 指定元組是錯誤的。

請注意,您在此處設定的確切時間可能不會被隨後的 stat() 呼叫返回,具體取決於您的作業系統記錄訪問和修改時間的解析度;請參閱 stat()。保留精確時間的最佳方法是使用 os.stat() 結果物件中的 st_atime_nsst_mtime_ns 欄位以及 utime()ns 引數。

此函式可以支援 指定檔案描述符相對於目錄描述符的路徑不跟隨符號連結

引發 審計事件 os.utime,引數為 pathtimesnsdir_fd

3.3 版本中已更改: 添加了支援將 path 指定為開啟的檔案描述符,以及 dir_fdfollow_symlinksns 引數。

在 3.6 版本發生變更: 接受 path-like object

os.walk(top, topdown=True, onerror=None, followlinks=False)

透過自上而下或自下而上遍歷目錄樹來生成目錄樹中的檔名。對於以目錄 top 為根的樹中的每個目錄(包括 top 本身),它會生成一個 3 元組 (dirpath, dirnames, filenames)

dirpath 是一個字串,表示目錄的路徑。dirnamesdirpath 中子目錄的名稱列表(包括指向目錄的符號連結,不包括 '.''..')。filenamesdirpath 中非目錄檔案的名稱列表。請注意,列表中的名稱不包含路徑元件。要獲取到 dirpath 中檔案或目錄的完整路徑(以 top 開頭),請執行 os.path.join(dirpath, name)。列表是否排序取決於檔案系統。如果在生成列表期間從 dirpath 目錄中刪除或添加了檔案,則該檔案的名稱是否包含在內是不確定的。

如果可選引數 topdownTrue 或未指定,則在生成任何子目錄的三元組之前生成目錄的三元組(目錄自上而下生成)。如果 topdownFalse,則在生成所有子目錄的三元組之後生成目錄的三元組(目錄自下而上生成)。無論 topdown 的值如何,子目錄列表在生成目錄及其子目錄的元組之前檢索。

topdownTrue 時,呼叫者可以就地修改 dirnames 列表(可能使用 del 或切片賦值),walk() 將只遞迴到 dirnames 中保留名稱的子目錄;這可用於修剪搜尋、強制特定的訪問順序,甚至通知 walk() 有關呼叫者在重新開始 walk() 之前建立或重新命名的目錄。當 topdownFalse 時,修改 dirnames 對遍歷的行為沒有影響,因為在自下而上模式下,dirnames 中的目錄在 dirpath 本身生成之前生成。

預設情況下,來自 scandir() 呼叫的錯誤將被忽略。如果指定了可選引數 onerror,它應該是一個函式;它將被呼叫,帶有一個引數,一個 OSError 例項。它可以報告錯誤以繼續遍歷,或者引發異常以中止遍歷。請注意,檔名作為異常物件的 filename 屬性可用。

預設情況下,walk() 不會進入解析為目錄的符號連結。將 followlinks 設定為 True 可訪問由符號連結指向的目錄,在支援它們的系統上。

備註

請注意,將 followlinks 設定為 True 可能導致無限遞迴,如果連結指向其自身的父目錄。walk() 不會跟蹤它已經訪問過的目錄。

備註

如果您傳遞相對路徑名,請不要在 walk() 的恢復之間更改當前工作目錄。walk() 從不更改當前目錄,並假設其呼叫者也不會更改。

此示例顯示了起始目錄下每個目錄中非目錄檔案佔用的位元組數,但不檢視任何 __pycache__ 子目錄

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

在下一個示例中(shutil.rmtree() 的簡單實現),自下而上遍歷樹是必不可少的,rmdir() 不允許在目錄清空之前刪除目錄

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files in os.walk(top, topdown=False):
    for name in files:
        os.remove(os.path.join(root, name))
    for name in dirs:
        os.rmdir(os.path.join(root, name))
os.rmdir(top)

引發 審計事件 os.walk,引數為 toptopdownonerrorfollowlinks

3.5 版本中已更改: 此函式現在呼叫 os.scandir() 而不是 os.listdir(),透過減少對 os.stat() 的呼叫次數,使其更快。

在 3.6 版本發生變更: 接受 path-like object

os.fwalk(top='.', topdown=True, onerror=None, *, follow_symlinks=False, dir_fd=None)

這與 walk() 的行為完全相同,只是它生成一個 4 元組 (dirpath, dirnames, filenames, dirfd),並且它支援 dir_fd

dirpathdirnamesfilenameswalk() 輸出相同,dirfd 是指向目錄 dirpath 的檔案描述符。

此函式始終支援 相對於目錄描述符的路徑不跟隨符號連結。但請注意,與其他函式不同,fwalk()follow_symlinks 預設值為 False

備註

由於 fwalk() 生成檔案描述符,這些描述符僅在下一次迭代步驟之前有效,因此如果您想保留它們更長時間,應該複製它們(例如使用 dup())。

此示例顯示了起始目錄下每個目錄中非目錄檔案佔用的位元組數,但不檢視任何 __pycache__ 子目錄

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/xml'):
    print(root, "consumes", end=" ")
    print(sum([os.stat(name, dir_fd=rootfd).st_size for name in files]),
          end=" ")
    print("bytes in", len(files), "non-directory files")
    if '__pycache__' in dirs:
        dirs.remove('__pycache__')  # don't visit __pycache__ directories

在下一個示例中,自下而上遍歷樹是必不可少的:rmdir() 不允許在目錄清空之前刪除目錄

# Delete everything reachable from the directory named in "top",
# assuming there are no symbolic links.
# CAUTION:  This is dangerous!  For example, if top == '/', it
# could delete all your disk files.
import os
for root, dirs, files, rootfd in os.fwalk(top, topdown=False):
    for name in files:
        os.unlink(name, dir_fd=rootfd)
    for name in dirs:
        os.rmdir(name, dir_fd=rootfd)

引發 審計事件 os.fwalk,引數為 toptopdownonerrorfollow_symlinksdir_fd

可用性: Unix。

在 3.3 版本加入。

在 3.6 版本發生變更: 接受 path-like object

3.7 版本中已更改: 添加了對 bytes 路徑的支援。

os.memfd_create(name[, flags=os.MFD_CLOEXEC])

建立一個匿名檔案並返回引用它的檔案描述符。flags 必須是系統上可用的 os.MFD_* 常量之一(或它們的按位或組合)。預設情況下,新的檔案描述符是 不可繼承的

name 中提供的名稱用作檔名,並將作為目錄 /proc/self/fd/ 中相應符號連結的目標顯示。顯示的名稱始終以 memfd: 為字首,僅用於除錯目的。名稱不影響檔案描述符的行為,因此多個檔案可以具有相同的名稱而沒有任何副作用。

可用性:Linux >= 3.17,glibc >= 2.27。

在 3.8 版本加入。

os.MFD_CLOEXEC
os.MFD_ALLOW_SEALING
os.MFD_HUGETLB
os.MFD_HUGE_SHIFT
os.MFD_HUGE_MASK
os.MFD_HUGE_64KB
os.MFD_HUGE_512KB
os.MFD_HUGE_1MB
os.MFD_HUGE_2MB
os.MFD_HUGE_8MB
os.MFD_HUGE_16MB
os.MFD_HUGE_32MB
os.MFD_HUGE_256MB
os.MFD_HUGE_512MB
os.MFD_HUGE_1GB
os.MFD_HUGE_2GB
os.MFD_HUGE_16GB

這些標誌可以傳遞給 memfd_create()

可用性:Linux >= 3.17,glibc >= 2.27

MFD_HUGE* 標誌僅在 Linux 4.14 及更高版本上可用。

在 3.8 版本加入。

os.eventfd(initval[, flags=os.EFD_CLOEXEC])

建立並返回一個事件檔案描述符。檔案描述符支援原始 read()write(),緩衝區大小為 8,select()poll() 及類似函式。有關更多資訊,請參閱手冊頁 eventfd(2)。預設情況下,新的檔案描述符是 不可繼承的

initval 是事件計數器的初始值。初始值必須是 32 位無符號整數。請注意,初始值限制為 32 位無符號整數,儘管事件計數器是無符號 64 位整數,最大值為 264-2。

flags 可以由 EFD_CLOEXECEFD_NONBLOCKEFD_SEMAPHORE 構成。

如果指定了 EFD_SEMAPHORE 且事件計數器非零,則 eventfd_read() 返回 1 並將計數器減一。

如果未指定 EFD_SEMAPHORE 且事件計數器非零,則 eventfd_read() 返回當前事件計數器值並將計數器重置為零。

如果事件計數器為零且未指定 EFD_NONBLOCK,則 eventfd_read() 阻塞。

eventfd_write() 增加事件計數器。如果寫入操作會使計數器增加到大於 264-2 的值,則寫入會阻塞。

示例

import os

# semaphore with start value '1'
fd = os.eventfd(1, os.EFD_SEMAPHORE | os.EFC_CLOEXEC)
try:
    # acquire semaphore
    v = os.eventfd_read(fd)
    try:
        do_work()
    finally:
        # release semaphore
        os.eventfd_write(fd, v)
finally:
    os.close(fd)

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.10 版本加入。

os.eventfd_read(fd)

eventfd() 檔案描述符讀取值並返回一個 64 位無符號整數。此函式不驗證 fd 是否為 eventfd()

可用性:Linux >= 2.6.27

在 3.10 版本加入。

os.eventfd_write(fd, value)

將值新增到 eventfd() 檔案描述符。value 必須是 64 位無符號整數。此函式不驗證 fd 是否為 eventfd()

可用性:Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_CLOEXEC

為新的 eventfd() 檔案描述符設定 close-on-exec 標誌。

可用性:Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_NONBLOCK

為新的 eventfd() 檔案描述符設定 O_NONBLOCK 狀態標誌。

可用性:Linux >= 2.6.27

在 3.10 版本加入。

os.EFD_SEMAPHORE

為從 eventfd() 檔案描述符讀取提供類似訊號量的語義。讀取時,內部計數器減一。

可用性:Linux >= 2.6.30

在 3.10 版本加入。

定時器檔案描述符

在 3.13 版本加入。

這些函式提供了對 Linux 的 定時器檔案描述符 API 的支援。當然,它們都只在 Linux 上可用。

os.timerfd_create(clockid, /, *, flags=0)

建立並返回一個定時器檔案描述符(timerfd)。

timerfd_create() 返回的檔案描述符支援

檔案描述符的 read() 方法可以以 8 位元組的緩衝區大小呼叫。如果定時器已經過期一次或多次,read() 將以主機的位元組序返回過期次數,這可以透過 int.from_bytes(x, byteorder=sys.byteorder) 轉換為 int>。

select()poll() 可用於等待定時器過期,直到檔案描述符可讀。

clockid 必須是有效的時鐘 ID,如 time 模組中定義的那樣

如果 clockidtime.CLOCK_REALTIME,則使用可設定的系統範圍即時時鐘。如果系統時鐘更改,則需要更新定時器設定。要在系統時鐘更改時取消定時器,請參閱 TFD_TIMER_CANCEL_ON_SET

如果 clockidtime.CLOCK_MONOTONIC,則使用不可設定的單調遞增時鐘。即使系統時鐘更改,定時器設定也不會受到影響。

如果 clockidtime.CLOCK_BOOTTIME,則與 time.CLOCK_MONOTONIC 相同,只是它包含了系統暫停的任何時間。

可以透過指定 flags 值來修改檔案描述符的行為。可以使用以下任何變數,並透過按位或(| 運算子)組合它們

如果 TFD_NONBLOCK 未設定為標誌,則 read() 將阻塞直到定時器過期。如果將其設定為標誌,則 read() 不會阻塞,但如果自上次呼叫 read 以來沒有過期,則 read() 將引發 OSError 異常,其中 errno 設定為 errno.EAGAIN

TFD_CLOEXEC 始終由 Python 自動設定。

不再需要檔案描述符時,必須使用 os.close() 關閉,否則檔案描述符將洩漏。

參見

timerfd_create(2) 手冊頁。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.timerfd_settime(fd, /, *, flags=flags, initial=0.0, interval=0.0)

更改定時器檔案描述符的內部定時器。此函式與 timerfd_settime_ns() 操作相同的間隔定時器。

fd 必須是有效的定時器檔案描述符。

可以透過指定 flags 值來修改定時器的行為。可以使用以下任何變數,並透過按位或(| 運算子)組合它們

透過將 initial 設定為零(0)來停用定時器。如果 initial 大於或等於零,則啟用定時器。如果 initial 小於零,它將引發 OSError 異常,其中 errno 設定為 errno.EINVAL

預設情況下,定時器將在 initial 秒過去後觸發。(如果 initial 為零,定時器將立即觸發。)

但是,如果設定了 TFD_TIMER_ABSTIME 標誌,則當定時器的時鐘(由 timerfd_create() 中的 clockid 設定)達到 initial 秒時,定時器將觸發。

定時器的間隔由 interval float 設定。如果 interval 為零,則定時器僅在首次過期時觸發一次。如果 interval 大於零,則定時器將自上次過期以來每經過 interval 秒觸發一次。如果 interval 小於零,它將引發 OSError 異常,其中 errno 設定為 errno.EINVAL

如果 TFD_TIMER_CANCEL_ON_SET 標誌與 TFD_TIMER_ABSTIME 一起設定,並且此定時器的時鐘是 time.CLOCK_REALTIME,則如果即時時鐘不連續更改,則定時器被標記為可取消。讀取描述符將因錯誤 ECANCELED 而中止。

Linux 將系統時鐘作為 UTC 管理。夏令時轉換僅透過更改時間偏移來完成,不會導致系統時鐘不連續更改。

以下事件將導致系統時鐘不連續更改

  • settimeofday

  • clock_settime

  • 透過 date 命令設定系統日期和時間

返回一個包含 ( next_expiration, interval) 的兩項元組,表示此函式執行之前的定時器狀態。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.timerfd_settime_ns(fd, /, *, flags=0, initial=0, interval=0)

類似於 timerfd_settime(),但使用納秒錶示時間。此函式與 timerfd_settime() 操作相同的間隔定時器。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.timerfd_gettime(fd, /)

返回一個包含浮點數 (next_expiration, interval) 的兩項元組。

next_expiration 表示下次定時器觸發的相對時間,無論 TFD_TIMER_ABSTIME 標誌是否設定。

interval 表示定時器的間隔。如果為零,則定時器在 next_expiration 秒過去後只會觸發一次。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.timerfd_gettime_ns(fd, /)

類似於 timerfd_gettime(),但以納秒返回時間。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.TFD_NONBLOCK

timerfd_create() 函式的一個標誌,用於為新的定時器檔案描述符設定 O_NONBLOCK 狀態標誌。如果未將 TFD_NONBLOCK 設定為標誌,則 read() 會阻塞。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.TFD_CLOEXEC

timerfd_create() 函式的一個標誌,如果將 TFD_CLOEXEC 設定為標誌,則為新檔案描述符設定 close-on-exec 標誌。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.TFD_TIMER_ABSTIME

timerfd_settime()timerfd_settime_ns() 函式的一個標誌。如果設定此標誌,則 initial 將被解釋為定時器時鐘上的絕對值(以 Unix 紀元以來的 UTC 秒或納秒為單位)。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

os.TFD_TIMER_CANCEL_ON_SET

TFD_TIMER_ABSTIME 一起用於 timerfd_settime()timerfd_settime_ns() 函式的標誌。當底層時鐘的時間不連續變化時,定時器將被取消。

可用性:Linux >= 2.6.27,glibc >= 2.8

在 3.13 版本加入。

Linux 擴充套件屬性

在 3.3 版本加入。

這些函式僅在 Linux 上可用。

os.getxattr(path, attribute, *, follow_symlinks=True)

返回 path 的擴充套件檔案系統屬性 attribute 的值。attribute 可以是 bytes 或 str(直接或透過 PathLike 介面間接)。如果是 str,它將使用檔案系統編碼進行編碼。

此函式可以支援 指定檔案描述符不跟隨符號連結

使用引數 pathattribute 引發 審計事件 os.getxattr

3.6 版本發生變化: 接受 路徑類物件 作為 pathattribute

os.listxattr(path=None, *, follow_symlinks=True)

返回 path 上的擴充套件檔案系統屬性列表。列表中的屬性表示為使用檔案系統編碼解碼的字串。如果 pathNone,則 listxattr() 將檢查當前目錄。

此函式可以支援 指定檔案描述符不跟隨符號連結

使用引數 path 引發 審計事件 os.listxattr

在 3.6 版本發生變更: 接受 path-like object

os.removexattr(path, attribute, *, follow_symlinks=True)

path 中移除擴充套件檔案系統屬性 attributeattribute 應該是 bytes 或 str(直接或透過 PathLike 介面間接)。如果是字串,它將使用檔案系統編碼和錯誤處理程式進行編碼。

此函式可以支援 指定檔案描述符不跟隨符號連結

使用引數 pathattribute 引發 審計事件 os.removexattr

3.6 版本發生變化: 接受 路徑類物件 作為 pathattribute

os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)

path 上的擴充套件檔案系統屬性 attribute 設定為 valueattribute 必須是 bytes 或不帶嵌入 NUL 的 str(直接或透過 PathLike 介面間接)。如果是 str,它將使用檔案系統編碼和錯誤處理程式進行編碼。flags 可以是 XATTR_REPLACEXATTR_CREATE。如果給出 XATTR_REPLACE 且屬性不存在,則將引發 ENODATA。如果給出 XATTR_CREATE 且屬性已存在,則不會建立屬性,並引發 EEXISTS

此函式可以支援 指定檔案描述符不跟隨符號連結

備註

Linux 核心版本低於 2.6.39 中的一個錯誤導致在某些檔案系統上忽略 flags 引數。

使用引數 pathattributevalueflags 引發 審計事件 os.setxattr

3.6 版本發生變化: 接受 路徑類物件 作為 pathattribute

os.XATTR_SIZE_MAX

擴充套件屬性的值可以達到的最大大小。目前,在 Linux 上為 64 KiB。

os.XATTR_CREATE

這是 setxattr() 中 flags 引數的可能值。它指示操作必須建立屬性。

os.XATTR_REPLACE

這是 setxattr() 中 flags 引數的可能值。它指示操作必須替換現有屬性。

程序管理

這些函式可用於建立和管理程序。

各種 exec* 函式為載入到程序中的新程式接受一個引數列表。在每種情況下,這些引數的第一個都作為新程式本身的名稱而不是使用者可能在命令列中鍵入的引數傳遞給新程式。對於 C 程式設計師,這是傳遞給程式的 main()argv[0]。例如,os.execv('/bin/echo', ['foo', 'bar']) 只會在標準輸出上列印 barfoo 似乎被忽略了。

os.abort()

向當前程序生成 SIGABRT 訊號。在 Unix 上,預設行為是生成核心轉儲;在 Windows 上,程序立即返回退出程式碼 3。請注意,呼叫此函式不會呼叫為 SIGABRT 註冊的 Python 訊號處理程式,該處理程式使用 signal.signal()

os.add_dll_directory(path)

將路徑新增到 DLL 搜尋路徑。

此搜尋路徑用於解析匯入的擴充套件模組(模組本身透過 sys.path 解析)的依賴項,也由 ctypes 使用。

透過對返回的物件呼叫 close() 或在 with 語句中使用它來刪除目錄。

有關 DLL 如何載入的更多資訊,請參閱 Microsoft 文件

使用引數 path 引發 審計事件 os.add_dll_directory

可用性: Windows。

3.8 新增: 以前的 CPython 版本會使用當前程序的預設行為來解析 DLL。這導致了不一致性,例如有時只搜尋 PATH 或當前工作目錄,並且諸如 AddDllDirectory 等 OS 函式無效。

在 3.8 中,DLL 載入的兩種主要方式現在明確覆蓋了程序範圍的行為,以確保一致性。有關更新庫的資訊,請參閱 移植說明

os.execl(path, arg0, arg1, ...)
os.execle(path, arg0, arg1, ..., env)
os.execlp(file, arg0, arg1, ...)
os.execlpe(file, arg0, arg1, ..., env)
os.execv(path, args)
os.execve(path, args, env)
os.execvp(file, args)
os.execvpe(file, args, env)

這些函式都執行一個新的程式,替換當前程序;它們不會返回。在 Unix 上,新的可執行檔案被載入到當前程序中,並將具有與呼叫者相同的程序 ID。錯誤將作為 OSError 異常報告。

當前程序會立即被替換。開啟的檔案物件和描述符不會被重新整理,因此如果這些開啟的檔案中可能有緩衝資料,您應該在呼叫 exec* 函式之前使用 sys.stdout.flush()os.fsync() 重新整理它們。

exec* 函式的“l”和“v”變體在命令列引數傳遞方式上有所不同。“l”變體在編寫程式碼時引數數量固定時可能最容易使用;單個引數只需成為 execl*() 函式的附加引數。“v”變體在引數數量可變時很好,引數以列表或元組的形式作為 args 引數傳遞。在這兩種情況下,子程序的引數都應該以執行命令的名稱開頭,但這並非強制執行。

名稱末尾包含“p”的變體(execlp()execlpe()execvp()execvpe())將使用 PATH 環境變數來定位程式 file。當環境被替換時(使用 exec*e 變體之一,在下一段中討論),新環境將用作 PATH 變數的來源。其他變體,execl()execle()execv()execve(),不會使用 PATH 變數來定位可執行檔案;path 必須包含適當的絕對或相對路徑。相對路徑必須包含至少一個斜槓,即使在 Windows 上也是如此,因為純名稱將無法解析。

對於 execle()execlpe()execve()execvpe()(請注意,這些都以“e”結尾),env 引數必須是一個對映,用於定義新程序的環境變數(這些變數取代當前程序的環境);函式 execl()execlp()execv()execvp() 都使新程序繼承當前程序的環境。

對於某些平臺上的 execve()path 也可以指定為開放檔案描述符。此功能可能在您的平臺上不受支援;您可以使用 os.supports_fd 檢查它是否可用。如果不可用,使用它將引發 NotImplementedError

使用引數 pathargsenv 引發 審計事件 os.exec

可用性: Unix, Windows, 不支援 WASI, 不支援 Android, 不支援 iOS。

3.3 版本發生變化: 增加了對 execve()path 指定為開放檔案描述符的支援。

在 3.6 版本發生變更: 接受 path-like object

os._exit(n)

以狀態 n 退出程序,不呼叫清理處理程式,不重新整理 stdio 緩衝區等。

備註

標準退出方式是 sys.exit(n)_exit() 通常只應在 fork() 之後的子程序中使用。

以下退出程式碼已定義,可與 _exit() 一起使用,儘管它們並非強制。這些通常用於用 Python 編寫的系統程式,例如郵件伺服器的外部命令傳遞程式。

備註

其中一些在所有 Unix 平臺上可能不可用,因為存在一些差異。這些常量是在底層平臺定義它們的地方定義的。

os.EX_OK

表示沒有發生錯誤的退出程式碼。可能取自某些平臺上的 EXIT_SUCCESS 的定義值。通常值為零。

可用性: Unix, Windows。

os.EX_USAGE

表示命令使用不正確,例如給定錯誤的引數數量時的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_DATAERR

表示輸入資料不正確的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_NOINPUT

表示輸入檔案不存在或不可讀的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_NOUSER

表示指定使用者不存在的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_NOHOST

表示指定主機不存在的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_UNAVAILABLE

表示所需服務不可用的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_SOFTWARE

表示檢測到內部軟體錯誤的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_OSERR

表示檢測到作業系統錯誤,例如無法 fork 或建立管道的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_OSFILE

表示某些系統檔案不存在、無法開啟或存在其他型別錯誤的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_CANTCREAT

表示使用者指定的輸出檔案無法建立的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_IOERR

表示在某個檔案上進行 I/O 時發生錯誤的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_TEMPFAIL

表示發生臨時故障的退出程式碼。這表示可能不是真正的錯誤,例如在可重試操作期間無法建立網路連線。

可用性: Unix,不包括 WASI。

os.EX_PROTOCOL

表示協議交換非法、無效或無法理解的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_NOPERM

表示執行操作許可權不足的退出程式碼(但並非用於檔案系統問題)。

可用性: Unix,不包括 WASI。

os.EX_CONFIG

表示發生某種配置錯誤的退出程式碼。

可用性: Unix,不包括 WASI。

os.EX_NOTFOUND

表示“未找到條目”之類的退出程式碼。

可用性: Unix,不包括 WASI。

os.fork()

派生一個子程序。在子程序中返回 0,在父程序中返回子程序的程序 ID。如果發生錯誤,則引發 OSError

請注意,包括 FreeBSD <= 6.3 和 Cygwin 在內的一些平臺在使用來自執行緒的 fork() 時存在已知問題。

使用無引數的 審計事件 os.fork 引發。

警告

如果您在呼叫 fork() 的應用程式中使用 TLS 套接字,請參閱 ssl 文件中的警告。

警告

在 macOS 上,當與使用更高級別的系統 API 混合使用時,使用此功能是不安全的,這包括使用 urllib.request

3.8 版本發生變化: 不再支援在子直譯器中呼叫 fork()(引發 RuntimeError)。

3.12 版本發生變化: 如果 Python 能夠檢測到您的程序有多個執行緒,os.fork() 現在會引發 DeprecationWarning

我們選擇在可檢測時將其作為警告浮現,以便更好地告知開發人員 POSIX 平臺明確指出不支援的設計問題。即使在“看起來”有效的程式碼中,在 POSIX 平臺上將執行緒與 os.fork() 混合使用也從未安全過。當父程序中存線上程時,CPython 執行時本身始終進行不安全地在子程序中使用的 API 呼叫(例如 mallocfree)。

macOS 使用者或使用 glibc 之外的 libc 或 malloc 實現的使用者更有可能遇到執行此類程式碼時的死鎖。

有關我們為何將此長期存在的平臺相容性問題浮現給開發人員的技術細節,請參閱 有關 fork 與執行緒不相容的討論

可用性: POSIX, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.forkpty()

派生一個子程序,使用新的偽終端作為子程序的控制終端。返回一對 (pid, fd),其中 pid 在子程序中為 0,在父程序中為新的子程序的程序 ID,fd 是偽終端主端的描述符。對於更具可移植性的方法,請使用 pty 模組。如果發生錯誤,則引發 OSError

使用無引數的 審計事件 os.forkpty 引發。

警告

在 macOS 上,當與使用更高級別的系統 API 混合使用時,使用此功能是不安全的,這包括使用 urllib.request

3.8 版本發生變化: 不再支援在子直譯器中呼叫 forkpty()(引發 RuntimeError)。

3.12 版本發生變化: 如果 Python 能夠檢測到您的程序有多個執行緒,則現在會引發 DeprecationWarning。請參閱 os.fork() 上的更詳細解釋。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.kill(pid, sig, /)

向程序 pid 傳送訊號 sig。主機平臺上可用的特定訊號的常量在 signal 模組中定義。

Windows:signal.CTRL_C_EVENTsignal.CTRL_BREAK_EVENT 訊號是特殊訊號,只能傳送到共享公共控制檯視窗的控制檯程序,例如某些子程序。sig 的任何其他值將導致程序被 TerminateProcess API 無條件終止,並且退出程式碼將設定為 sig

另請參閱 signal.pthread_kill()

使用引數 pidsig 引發 審計事件 os.kill

可用性: Unix, Windows, 不支援 WASI, 不支援 iOS。

3.2 版中變更: 添加了 Windows 支援。

os.killpg(pgid, sig, /)

向程序組 pgid 傳送訊號 sig

使用引數 pgidsig 引發 審計事件 os.killpg

可用性: Unix, 不包括 WASI, 不包括 iOS。

os.nice(increment, /)

increment 新增到程序的“nice 值”。返回新的 nice 值。

可用性: Unix,不包括 WASI。

os.pidfd_open(pid, flags=0)

返回一個引用程序 pid 且設定了 flags 的檔案描述符。此描述符可用於無競爭和無訊號地執行程序管理。

有關更多詳細資訊,請參閱 pidfd_open(2) 手冊頁。

可用性: Linux >= 5.3,Android >= 構建時 API 級別 31

在 3.9 版本中新增。

os.PIDFD_NONBLOCK

此標誌指示檔案描述符將是非阻塞的。如果檔案描述符引用的程序尚未終止,則嘗試使用 waitid(2) 等待檔案描述符將立即返回錯誤 EAGAIN,而不是阻塞。

可用性: Linux >= 5.10

3.12 新版功能.

os.plock(op, /)

將程式段鎖定到記憶體中。op 的值(在 <sys/lock.h> 中定義)確定鎖定哪些段。

可用性: Unix, 不包括 WASI, 不包括 iOS。

os.popen(cmd, mode='r', buffering=-1)

開啟到命令 cmd 的管道。返回值是一個連線到管道的開放檔案物件,可以讀取或寫入,具體取決於 mode'r'(預設)還是 'w'buffering 引數的含義與內建 open() 函式的相應引數相同。返回的檔案物件讀取或寫入文字字串而不是位元組。

close 方法在子程序成功退出時返回 None,如果發生錯誤則返回子程序的返回程式碼。在 POSIX 系統上,如果返回程式碼為正,則表示程序的返回值左移一個位元組。如果返回程式碼為負,則程序被由返回程式碼的負值給出的訊號終止。(例如,如果子程序被殺死,則返回值為 - signal.SIGKILL。)在 Windows 系統上,返回值包含子程序的帶符號整數返回程式碼。

在 Unix 上,waitstatus_to_exitcode() 可用於將 close 方法結果(退出狀態)轉換為退出程式碼,如果它不是 None。在 Windows 上,close 方法結果直接是退出程式碼(或 None)。

這是使用 subprocess.Popen 實現的;有關管理子程序和與子程序通訊的更強大方法,請參閱該類的文件。

可用性:不適用於 WASI、Android、iOS。

備註

Python UTF-8 模式 影響用於 cmd 和管道內容的編碼。

popen()subprocess.Popen 的一個簡單包裝器。使用 subprocess.Popensubprocess.run() 來控制編碼等選項。

3.14 版本後已棄用: 該函式被 軟棄用,不應再用於編寫新程式碼。subprocess 模組是推薦的替代方案。

os.posix_spawn(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

封裝了 C 庫 API posix_spawn(),以便在 Python 中使用。

大多數使用者應使用 subprocess.run() 而不是 posix_spawn()

位置引數 pathargsenv 類似於 execve()。允許 envNone,在這種情況下使用當前程序的環境。

path 引數是可執行檔案的路徑。path 應包含一個目錄。使用 posix_spawnp() 傳遞不帶目錄的可執行檔案。

file_actions 引數可以是描述在 C 庫實現中的 fork()exec() 步驟之間對子程序中的特定檔案描述符執行的操作的元組序列。每個元組的第一個元素必須是下面列出的三個型別指示符之一,描述其餘的元組元素

os.POSIX_SPAWN_OPEN

(os.POSIX_SPAWN_OPEN, fd, path, flags, mode)

執行 os.dup2(os.open(path, flags, mode), fd)

os.POSIX_SPAWN_CLOSE

(os.POSIX_SPAWN_CLOSE, fd)

執行 os.close(fd)

os.POSIX_SPAWN_DUP2

(os.POSIX_SPAWN_DUP2, fd, new_fd)

執行 os.dup2(fd, new_fd)

os.POSIX_SPAWN_CLOSEFROM

(os.POSIX_SPAWN_CLOSEFROM, fd)

執行 os.closerange(fd, INF)

這些元組對應於 C 庫的 posix_spawn_file_actions_addopen()posix_spawn_file_actions_addclose()posix_spawn_file_actions_adddup2()posix_spawn_file_actions_addclosefrom_np() API 呼叫,用於為 posix_spawn() 呼叫本身做準備。

setpgroup 引數將子程序的程序組設定為指定的值。如果指定的值為 0,則子程序的程序組 ID 將與其程序 ID 相同。如果 setpgroup 的值未設定,子程序將繼承父程序的程序組 ID。此引數對應於 C 庫的 POSIX_SPAWN_SETPGROUP 標誌。

如果 resetids 引數為 True,它將子程序的有效 UID 和 GID 重置為父程序的實際 UID 和 GID。如果引數為 False,則子程序保留父程序的有效 UID 和 GID。在任何一種情況下,如果可執行檔案上啟用了 set-user-ID 和 set-group-ID 許可權位,它們的效果將覆蓋有效 UID 和 GID 的設定。此引數對應於 C 庫的 POSIX_SPAWN_RESETIDS 標誌。

如果 setsid 引數為 True,它將為 posix_spawn 建立一個新的會話 ID。setsid 需要 POSIX_SPAWN_SETSIDPOSIX_SPAWN_SETSID_NP 標誌。否則,將引發 NotImplementedError

setsigmask 引數將訊號掩碼設定為指定的訊號集。如果未使用該引數,則子程序繼承父程序的訊號掩碼。此引數對應於 C 庫的 POSIX_SPAWN_SETSIGMASK 標誌。

sigdef 引數將重置指定集合中所有訊號的處理方式。此引數對應於 C 庫的 POSIX_SPAWN_SETSIGDEF 標誌。

scheduler 引數必須是一個元組,包含(可選的)排程策略和 sched_param 的例項以及排程引數。排程策略位置的值為 None 表示未提供。此引數是 C 庫 POSIX_SPAWN_SETSCHEDPARAMPOSIX_SPAWN_SETSCHEDULER 標誌的組合。

使用引數 pathargvenv 引發 審計事件 os.posix_spawn

在 3.8 版本加入。

3.13 版本中已更改: env 引數接受 Noneos.POSIX_SPAWN_CLOSEFROM 在存在 posix_spawn_file_actions_addclosefrom_np() 的平臺上可用。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.posix_spawnp(path, argv, env, *, file_actions=None, setpgroup=None, resetids=False, setsid=False, setsigmask=(), setsigdef=(), scheduler=None)

封裝了 C 庫 API posix_spawnp(),以便在 Python 中使用。

類似於 posix_spawn(),不同之處在於系統會在 PATH 環境變數指定的目錄列表中搜索 executable 檔案(與 execvp(3) 的方式相同)。

使用引數 pathargvenv 引發 審計事件 os.posix_spawn

在 3.8 版本加入。

可用性: POSIX, 不支援 WASI, 不支援 Android, 不支援 iOS。

請參閱 posix_spawn() 文件。

os.register_at_fork(*, before=None, after_in_parent=None, after_in_child=None)

註冊可呼叫物件,以便在使用 os.fork() 或類似程序克隆 API fork 新子程序時執行。引數是可選的且僅限關鍵字。每個引數指定一個不同的呼叫點。

  • before 是在 fork 子程序之前呼叫的函式。

  • after_in_parent 是在 fork 子程序後從父程序呼叫的函式。

  • after_in_child 是從子程序呼叫的函式。

這些呼叫只有在控制權預期返回到 Python 直譯器時才進行。典型的 subprocess 啟動不會觸發它們,因為子程序不會重新進入直譯器。

註冊在 fork 之前執行的函式以相反的註冊順序呼叫。註冊在 fork 之後執行的函式(無論是在父程序還是子程序中)以註冊順序呼叫。

請注意,第三方 C 程式碼進行的 fork() 呼叫可能不會呼叫這些函式,除非它明確呼叫 PyOS_BeforeFork()PyOS_AfterFork_Parent()PyOS_AfterFork_Child()

無法登出函式。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.7 版本加入。

os.spawnl(mode, path, ...)
os.spawnle(mode, path, ..., env)
os.spawnlp(mode, file, ...)
os.spawnlpe(mode, file, ..., env)
os.spawnv(mode, path, args)
os.spawnve(mode, path, args, env)
os.spawnvp(mode, file, args)
os.spawnvpe(mode, file, args, env)

在新程序中執行程式 path

(請注意,subprocess 模組提供了更強大的功能來生成新程序並檢索其結果;建議使用該模組而不是這些函式。特別是請檢視 使用 subprocess 模組替換舊函式 部分。)

如果 modeP_NOWAIT,此函式返回新程序的程序 ID;如果 modeP_WAIT,如果程序正常退出,則返回程序的退出程式碼,否則返回 -signal,其中 signal 是殺死程序的訊號。在 Windows 上,程序 ID 實際上將是程序控制代碼,因此可以與 waitpid() 函式一起使用。

請注意,在 VxWorks 上,當新程序被殺死時,此函式不返回 -signal。相反,它會引發 OSError 異常。

spawn* 函式的 "l" 和 "v" 變體在命令列引數的傳遞方式上有所不同。如果引數數量在編寫程式碼時是固定的,則 "l" 變體可能最容易使用;單個引數簡單地成為 spawnl*() 函式的額外引數。"v" 變體在引數數量可變時很好,引數以列表或元組的形式作為 args 引數傳遞。在這兩種情況下,子程序的引數必須以正在執行的命令的名稱開頭。

末尾包含第二個 “p” 的變體(spawnlp()spawnlpe()spawnvp()spawnvpe())將使用 PATH 環境變數來定位程式 file。當環境被替換時(使用 spawn*e 變體之一,將在下一段中討論),新環境將用作 PATH 變數的來源。其他變體,spawnl()spawnle()spawnv()spawnve(),將不使用 PATH 變數來定位可執行檔案;path 必須包含適當的絕對路徑或相對路徑。

對於 spawnle()spawnlpe()spawnve()spawnvpe()(請注意,它們都以 "e" 結尾),env 引數必須是一個對映,用於定義新程序的環境變數(它們用於代替當前程序的環境);函式 spawnl()spawnlp()spawnv()spawnvp() 都導致新程序繼承當前程序的環境。請注意,env 字典中的鍵和值必須是字串;無效的鍵或值將導致函式失敗,返回值為 127

例如,以下對 spawnlp()spawnvpe() 的呼叫是等效的

import os
os.spawnlp(os.P_WAIT, 'cp', 'cp', 'index.html', '/dev/null')

L = ['cp', 'index.html', '/dev/null']
os.spawnvpe(os.P_WAIT, 'cp', L, os.environ)

使用引數 modepathargsenv 引發 審計事件 os.spawn

可用性: Unix, Windows, 不支援 WASI, 不支援 Android, 不支援 iOS。

spawnlp()spawnlpe()spawnvp()spawnvpe() 在 Windows 上不可用。spawnle()spawnve() 在 Windows 上不是執行緒安全的;我們建議您改用 subprocess 模組。

在 3.6 版本發生變更: 接受 path-like object

3.14 版本後已棄用: 這些函式被 軟棄用,不應再用於編寫新程式碼。subprocess 模組是推薦的替代方案。

os.P_NOWAIT
os.P_NOWAITO

spawn* 函式族中 mode 引數的可能值。如果給定這些值中的任何一個,spawn* 函式將在新程序建立後立即返回,並以程序 ID 作為返回值。

可用性: Unix, Windows。

os.P_WAIT

spawn* 函式族中 mode 引數的可能值。如果將其作為 mode 給出,spawn* 函式將直到新程序執行完成才會返回,如果執行成功,將返回程序的退出程式碼,如果訊號殺死程序,則返回 -signal

可用性: Unix, Windows。

os.P_DETACH
os.P_OVERLAY

spawn* 函式族中 mode 引數的可能值。這些值不如上面列出的值可移植。P_DETACH 類似於 P_NOWAIT,但新程序與呼叫程序的控制檯分離。如果使用 P_OVERLAY,則當前程序將被替換;spawn* 函式將不返回。

可用性: Windows。

os.startfile(path[, operation][, arguments][, cwd][, show_cmd])

使用關聯的應用程式啟動檔案。

當未指定 operation 時,這就像在 Windows 資源管理器中雙擊檔案,或者將檔名作為互動式命令 shell 中的 start 命令的引數:檔案將使用其副檔名關聯的任何應用程式(如果有)開啟。

當給出其他 operation 時,它必須是指定對檔案執行操作的“命令動詞”。Microsoft 文件中常見的動詞是 'open''print''edit'(用於檔案)以及 'explore''find'(用於目錄)。

啟動應用程式時,將 arguments 指定為單個字串進行傳遞。當使用此函式啟動文件時,此引數可能不起作用。

預設工作目錄是繼承的,但可以透過 cwd 引數覆蓋。這應該是一個絕對路徑。相對 path 將根據此引數解析。

使用 show_cmd 覆蓋預設視窗樣式。這是否有效將取決於正在啟動的應用程式。值為 Win32 ShellExecute() 函式支援的整數。

startfile() 在關聯應用程式啟動後立即返回。沒有等待應用程式關閉的選項,也無法檢索應用程式的退出狀態。path 引數是相對於當前目錄或 cwd 的。如果您想使用絕對路徑,請確保第一個字元不是斜槓('/')。使用 pathlibos.path.normpath() 函式以確保路徑正確編碼為 Win32。

為了減少直譯器啟動開銷,Win32 ShellExecute() 函式直到首次呼叫此函式時才解析。如果函式無法解析,將引發 NotImplementedError

使用引數 pathoperation 引發 審計事件 os.startfile

使用引數 pathoperationargumentscwdshow_cmd 引發 審計事件 os.startfile/2

可用性: Windows。

3.10 版本中已更改: 增加了 argumentscwdshow_cmd 引數,以及 os.startfile/2 審計事件。

os.system(command)

在子 shell 中執行命令(字串)。這是透過呼叫標準 C 函式 system() 實現的,並具有相同的限制。對 sys.stdin 等的更改不會反映在執行命令的環境中。如果 command 產生任何輸出,它將被髮送到直譯器標準輸出流。C 標準沒有指定 C 函式返回值的含義,因此 Python 函式的返回值是系統相關的。

在 Unix 上,返回值是按 wait() 指定的格式編碼的程序退出狀態。

在 Windows 上,返回值是系統 shell 執行 command 後返回的值。shell 由 Windows 環境變數 COMSPEC 給出:它通常是 cmd.exe,它返回執行命令的退出狀態;在使用非原生 shell 的系統上,請查閱您的 shell 文件。

subprocess 模組提供了更強大的功能來生成新程序並檢索其結果;建議使用該模組而不是此函式。有關一些有用的食譜,請參閱 subprocess 文件中的 使用 subprocess 模組替換舊函式 部分。

在 Unix 上,waitstatus_to_exitcode() 可用於將結果(退出狀態)轉換為退出程式碼。在 Windows 上,結果直接是退出程式碼。

使用引數 command 引發 審計事件 os.system

可用性: Unix, Windows, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.times()

返回當前全域性程序時間。返回值是一個具有五個屬性的物件

  • user - 使用者時間

  • system - 系統時間

  • children_user - 所有子程序的使用者時間

  • children_system - 所有子程序的系統時間

  • elapsed - 自過去某個固定點以來經過的實際時間

為了向後相容,此物件也表現得像一個包含 usersystemchildren_userchildren_systemelapsed 的五元組,按該順序排列。

請參閱 Unix 手冊頁 times(2) 和 Unix 上的 times(3) 手冊頁,或 Windows 上的 GetProcessTimes MSDN。在 Windows 上,只知道 usersystem;其他屬性為零。

可用性: Unix, Windows。

3.3 版本中的變化: 返回型別從元組變為具有命名屬性的類元組物件。

os.wait()

等待子程序完成,並返回一個元組,其中包含其 pid 和退出狀態指示:一個 16 位數字,其低位元組是殺死程序的訊號編號,其高位元組是退出狀態(如果訊號編號為零);如果產生了核心檔案,則低位元組的高位被設定。

如果沒有可等待的子程序,則會引發 ChildProcessError

waitstatus_to_exitcode() 可用於將退出狀態轉換為退出程式碼。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

參見

下面文件中的其他 wait*() 函式可用於等待特定子程序的完成,並且具有更多選項。waitpid() 是唯一在 Windows 上也可用。

os.waitid(idtype, id, options, /)

等待子程序完成。

idtype 可以是 P_PIDP_PGIDP_ALL,或者(在 Linux 上)P_PIDFDid 的解釋取決於它;請參閱它們的單獨描述。

options 是標誌的 OR 組合。至少需要 WEXITEDWSTOPPEDWCONTINUED 之一;WNOHANGWNOWAIT 是附加的可選標誌。

返回值是一個物件,表示 siginfo_t 結構中包含的資料,具有以下屬性

  • si_pid (程序 ID)

  • si_uid (子程序的實際使用者 ID)

  • si_signo (始終為 SIGCHLD)

  • si_status (退出狀態或訊號編號,取決於 si_code)

  • si_code (可能的值請參見 CLD_EXITED)

如果指定了 WNOHANG 且在請求狀態中沒有匹配的子程序,則返回 None。否則,如果沒有可等待的匹配子程序,則會引發 ChildProcessError

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.3 版本加入。

3.13 版本中已更改: 此函式現在也可在 macOS 上使用。

os.waitpid(pid, options, /)

此函式的詳細資訊在 Unix 和 Windows 上有所不同。

在 Unix 上:等待由程序 ID pid 給出的子程序完成,並返回一個包含其程序 ID 和退出狀態指示的元組(編碼方式與 wait() 相同)。呼叫的語義受整數 options 的值影響,對於正常操作,它應為 0

如果 pid 大於 0waitpid() 請求該特定程序的狀態資訊。如果 pid0,則請求是關於當前程序程序組中任何子程序的狀態。如果 pid-1,則請求是關於當前程序的任何子程序。如果 pid 小於 -1,則請求是關於程序組 -pidpid 的絕對值)中任何程序的狀態。

options 是標誌的 OR 組合。如果它包含 WNOHANG 並且在請求狀態中沒有匹配的子程序,則返回 (0, 0)。否則,如果沒有可等待的匹配子程序,則會引發 ChildProcessError。可以使用的其他選項是 WUNTRACEDWCONTINUED

在 Windows 上:等待由程序控制代碼 pid 給出的程序完成,並返回一個包含 pid 及其退出狀態(左移 8 位)的元組(移位使函式的跨平臺使用更容易)。小於或等於 0pid 在 Windows 上沒有特殊含義,會引發異常。整數 options 的值沒有影響。pid 可以引用其 ID 已知的任何程序,不一定是子程序。使用 P_NOWAIT 呼叫的 spawn* 函式返回適當的程序控制代碼。

waitstatus_to_exitcode() 可用於將退出狀態轉換為退出程式碼。

可用性: Unix, Windows, 不支援 WASI, 不支援 Android, 不支援 iOS。

3.5 版本中已更改: 如果系統呼叫被中斷且訊號處理程式未引發異常,該函式現在會重試系統呼叫,而不是引發 InterruptedError 異常(有關原因,請參閱 PEP 475)。

os.wait3(options)

類似於 waitpid(),但未給定程序 ID 引數,並返回一個包含子程序 ID、退出狀態指示和資源使用資訊的 3 元素元組。有關資源使用資訊的詳細資訊,請參閱 resource.getrusage()options 引數與提供給 waitpid()wait4() 的相同。

waitstatus_to_exitcode() 可用於將退出狀態轉換為退出程式碼。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.wait4(pid, options)

類似於 waitpid(),但返回一個 3 元素元組,其中包含子程序 ID、退出狀態指示和資源使用資訊。有關資源使用資訊的詳細資訊,請參閱 resource.getrusage()wait4() 的引數與提供給 waitpid() 的相同。

waitstatus_to_exitcode() 可用於將退出狀態轉換為退出程式碼。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.P_PID
os.P_PGID
os.P_ALL
os.P_PIDFD

這些是 waitid()idtype 的可能值。它們影響 id 的解釋

  • P_PID - 等待 PID 為 id 的子程序。

  • P_PGID - 等待程序組 ID 為 id 的任何子程序。

  • P_ALL - 等待任何子程序;id 被忽略。

  • P_PIDFD - 等待由檔案描述符 id 標識的子程序(使用 pidfd_open() 建立的程序檔案描述符)。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

備註

P_PIDFD 僅在 Linux >= 5.4 上可用。

在 3.3 版本加入。

3.9 版本新增: P_PIDFD 常量。

os.WCONTINUED

options 標誌適用於 waitpid()wait3()wait4()waitid(),它會導致子程序在上次報告後,如果已從作業控制停止中繼續,則被報告。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WEXITED

options 標誌適用於 waitid(),它會導致已終止的子程序被報告。

其他 wait* 函式總是報告已終止的子程序,因此此選項不適用於它們。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.3 版本加入。

os.WSTOPPED

options 標誌適用於 waitid(),它會導致因接收到訊號而停止的子程序被報告。

此選項不適用於其他 wait* 函式。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.3 版本加入。

os.WUNTRACED

options 標誌適用於 waitpid()wait3()wait4(),它也導致子程序被報告,如果它們已停止但其當前狀態自停止以來尚未報告。

此選項不適用於 waitid()

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WNOHANG

options 標誌使得 waitpid()wait3()wait4()waitid() 在沒有子程序狀態立即可用時立即返回。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WNOWAIT

options 標誌使得 waitid() 將子程序留在可等待狀態,以便稍後的 wait*() 呼叫可以再次檢索子程序狀態資訊。

此選項不適用於其他 wait* 函式。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.CLD_EXITED
os.CLD_KILLED
os.CLD_DUMPED
os.CLD_TRAPPED
os.CLD_STOPPED
os.CLD_CONTINUED

這些是 waitid() 返回結果中 si_code 的可能值。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.3 版本加入。

3.9 版本中已更改: 增加了 CLD_KILLEDCLD_STOPPED 值。

os.waitstatus_to_exitcode(status)

將等待狀態轉換為退出程式碼。

在 Unix 上

  • 如果程序正常退出(如果 WIFEXITED(status) 為真),返回程序退出狀態(返回 WEXITSTATUS(status)):結果大於或等於 0。

  • 如果程序被訊號終止(如果 WIFSIGNALED(status) 為真),返回 -signum,其中 signum 是導致程序終止的訊號編號(返回 -WTERMSIG(status)):結果小於 0。

  • 否則,引發 ValueError

在 Windows 上,返回 status 右移 8 位。

在 Unix 上,如果程序正在被跟蹤,或者 waitpid() 是用 WUNTRACED 選項呼叫的,呼叫者必須首先檢查 WIFSTOPPED(status) 是否為真。如果 WIFSTOPPED(status) 為真,則不得呼叫此函式。

可用性: Unix, Windows, 不支援 WASI, 不支援 Android, 不支援 iOS。

在 3.9 版本中新增。

以下函式將 system()wait()waitpid() 返回的程序狀態碼作為引數。它們可用於確定程序的處理方式。

os.WCOREDUMP(status, /)

如果程序生成了核心轉儲,則返回 True,否則返回 False

此函式僅在 WIFSIGNALED() 為真時才應使用。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WIFCONTINUED(status)

如果停止的子程序已透過傳送 SIGCONT 恢復(如果程序已從作業控制停止中繼續),則返回 True,否則返回 False

請參閱 WCONTINUED 選項。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WIFSTOPPED(status)

如果程序因收到訊號而停止,則返回 True,否則返回 False

WIFSTOPPED() 僅當 waitpid() 呼叫使用 WUNTRACED 選項或程序正在被跟蹤時才返回 True(請參閱 ptrace(2))。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WIFSIGNALED(status)

如果程序因訊號終止,則返回 True,否則返回 False

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WIFEXITED(status)

如果程序正常終止,即透過呼叫 exit()_exit(),或者從 main() 返回,則返回 True;否則返回 False

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WEXITSTATUS(status)

返回程序退出狀態。

此函式僅在 WIFEXITED() 為真時才應使用。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WSTOPSIG(status)

返回導致程序停止的訊號。

此函式僅在 WIFSTOPPED() 為真時才應使用。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

os.WTERMSIG(status)

返回導致程序終止的訊號編號。

此函式僅在 WIFSIGNALED() 為真時才應使用。

可用性: Unix, 不支援 WASI, 不支援 Android, 不支援 iOS。

排程器介面

這些函式控制作業系統如何為程序分配 CPU 時間。它們僅在某些 Unix 平臺上可用。有關更詳細的資訊,請查閱您的 Unix manpages。

在 3.3 版本加入。

如果作業系統支援,則公開以下排程策略。

os.SCHED_OTHER

預設排程策略。

os.SCHED_BATCH

用於 CPU 密集型程序的排程策略,旨在保持計算機其餘部分的互動性。

os.SCHED_DEADLINE

用於具有截止時間限制的任務的排程策略。

在 3.14 版本加入。

os.SCHED_IDLE

用於極低優先順序後臺任務的排程策略。

os.SCHED_NORMAL

SCHED_OTHER 的別名。

在 3.14 版本加入。

os.SCHED_SPORADIC

用於零星伺服器程式的排程策略。

os.SCHED_FIFO

先進先出排程策略。

os.SCHED_RR

輪詢排程策略。

os.SCHED_RESET_ON_FORK

此標誌可以與任何其他排程策略進行按位或操作。當設定了此標誌的程序派生子程序時,其子程序的排程策略和優先順序將重置為預設值。

class os.sched_param(sched_priority)

此類表示在 sched_setparam()sched_setscheduler()sched_getparam() 中使用的可調排程引數。它是不可變的。

目前,只有一個可能的引數

sched_priority

排程策略的排程優先順序。

os.sched_get_priority_min(policy)

獲取 policy 的最小優先順序值。policy 是上面列出的排程策略常量之一。

os.sched_get_priority_max(policy)

獲取 policy 的最大優先順序值。policy 是上面列出的排程策略常量之一。

os.sched_setscheduler(pid, policy, param, /)

為 PID 為 pid 的程序設定排程策略。pid 為 0 表示呼叫程序。policy 是上面列出的排程策略常量之一。param 是一個 sched_param 例項。

os.sched_getscheduler(pid, /)

返回 PID 為 pid 的程序的排程策略。pid 為 0 表示呼叫程序。結果是上面列出的排程策略常量之一。

os.sched_setparam(pid, param, /)

為 PID 為 pid 的程序設定排程引數。pid 為 0 表示呼叫程序。param 是一個 sched_param 例項。

os.sched_getparam(pid, /)

返回 PID 為 pid 的程序的排程引數,作為 sched_param 例項。pid 為 0 表示呼叫程序。

os.sched_rr_get_interval(pid, /)

返回 PID 為 pid 的程序的輪詢時間片(以秒為單位)。pid 為 0 表示呼叫程序。

os.sched_yield()

自願放棄 CPU。有關詳細資訊,請參見手冊頁 sched_yield(2)

os.sched_setaffinity(pid, mask, /)

將 PID 為 pid 的程序(如果為零,則為當前程序)限制到一組 CPU。mask 是一個整數可迭代物件,表示應將程序限制到的 CPU 集合。

os.sched_getaffinity(pid, /)

返回 PID 為 pid 的程序被限制到的 CPU 集合。

如果 pid 為零,則返回當前程序的呼叫執行緒被限制到的 CPU 集合。

另請參見 process_cpu_count() 函式。

其他系統資訊

os.confstr(name, /)

返回字串型別的系統配置值。name 指定要檢索的配置值;它可能是已定義的系統值的名稱字串;這些名稱在許多標準(POSIX、Unix 95、Unix 98 等)中指定。某些平臺也定義了其他名稱。主機作業系統已知的名稱作為 confstr_names 字典的鍵給出。對於不包含在該對映中的配置變數,也接受將整數作為 name 傳入。

如果 name 指定的配置值未定義,則返回 None

如果 name 是字串且未知,則會引發 ValueError。如果主機系統不支援 name 的特定值,即使它包含在 confstr_names 中,也會引發 OSError,錯誤號為 errno.EINVAL

可用性: Unix。

os.confstr_names

字典,將 confstr() 接受的名稱對映到主機作業系統為這些名稱定義的整數值。這可用於確定系統已知名稱的集合。

可用性: Unix。

os.cpu_count()

返回系統中的邏輯 CPU 數量。如果無法確定,則返回 None

可以使用 process_cpu_count() 函式獲取當前程序的呼叫執行緒可用的邏輯 CPU 數量。

在 3.4 版本加入。

3.13 版本中的變化: 如果給定 -X cpu_count 或設定了 PYTHON_CPU_COUNT,則 cpu_count() 返回被覆蓋的值 n

os.getloadavg()

返回系統執行佇列中過去 1、5 和 15 分鐘的平均程序數,如果無法獲取平均負載,則引發 OSError

可用性: Unix。

os.process_cpu_count()

獲取當前程序的呼叫執行緒可用的邏輯 CPU 數量。如果無法確定,則返回 None。根據 CPU 親和性,它可能小於 cpu_count()

可以使用 cpu_count() 函式獲取系統中的邏輯 CPU 數量。

如果給定 -X cpu_count 或設定了 PYTHON_CPU_COUNT,則 process_cpu_count() 返回被覆蓋的值 n

另請參見 sched_getaffinity() 函式。

在 3.13 版本加入。

os.sysconf(name, /)

返回整數型別的系統配置值。如果 name 指定的配置值未定義,則返回 -1。關於 confstr()name 引數的註釋也適用於此處;提供已知名稱資訊的字典由 sysconf_names 給出。

可用性: Unix。

os.sysconf_names

字典,將 sysconf() 接受的名稱對映到主機作業系統為這些名稱定義的整數值。這可用於確定系統已知名稱的集合。

可用性: Unix。

3.11 版本中的變化: 新增 'SC_MINSIGSTKSZ' 名稱。

以下資料值用於支援路徑操作。這些在所有平臺上都已定義。

路徑名上的高階操作在 os.path 模組中定義。

os.curdir

作業系統用於指代當前目錄的常量字串。Windows 和 POSIX 系統上為 '.'。也可透過 os.path 訪問。

os.pardir

作業系統用於指代父目錄的常量字串。Windows 和 POSIX 系統上為 '..'。也可透過 os.path 訪問。

os.sep

作業系統用於分隔路徑名元件的字元。POSIX 系統上為 '/',Windows 系統上為 '\\'。請注意,僅知道這一點不足以解析或連線路徑名 — 請使用 os.path.split()os.path.join() — 但它偶爾也很有用。也可透過 os.path 訪問。

os.altsep

作業系統用於分隔路徑名元件的備用字元,如果只有一個分隔符字元,則為 None。在 sep 為反斜槓的 Windows 系統上,此項設定為 '/'。也可透過 os.path 訪問。

os.extsep

分隔基本檔名和副檔名的字元;例如,os.py 中的 '.'。也可透過 os.path 訪問。

os.pathsep

作業系統傳統上用於分隔搜尋路徑元件(如 PATH)的字元,例如 POSIX 系統上的 ':' 或 Windows 系統上的 ';'。也可透過 os.path 訪問。

os.defpath

如果環境中沒有 'PATH' 鍵,則 exec*p*spawn*p* 使用的預設搜尋路徑。也可透過 os.path 訪問。

os.linesep

當前平臺上用於分隔(或終止)行的字串。這可能是一個字元,如 POSIX 系統上的 '\n',也可能是多個字元,例如 Windows 系統上的 '\r\n'。在以文字模式(預設)寫入檔案時,請勿使用 os.linesep 作為行終止符;在所有平臺上都應使用單個 '\n'

os.devnull

空裝置的檔案路徑。例如:POSIX 系統上的 '/dev/null',Windows 系統上的 'nul'。也可透過 os.path 訪問。

os.RTLD_LAZY
os.RTLD_NOW
os.RTLD_GLOBAL
os.RTLD_LOCAL
os.RTLD_NODELETE
os.RTLD_NOLOAD
os.RTLD_DEEPBIND

用於 setdlopenflags()getdlopenflags() 函式的標誌。有關不同標誌的含義,請參見 Unix 手冊頁 dlopen(3)

在 3.3 版本加入。

隨機數

os.getrandom(size, flags=0)

獲取最多 size 個隨機位元組。該函式可以返回少於請求的位元組數。

這些位元組可用於為使用者空間的隨機數生成器播種或用於加密目的。

getrandom() 依賴於從裝置驅動程式和其他環境噪聲源收集的熵。不必要地讀取大量資料會對 /dev/random/dev/urandom 裝置的其它使用者產生負面影響。

flags 引數是一個位掩碼,可以包含以下一個或多個值的按位或組合:os.GRND_RANDOMGRND_NONBLOCK

另請參見 Linux getrandom() 手冊頁

可用性:Linux >= 3.17。

在 3.6 版本加入。

os.urandom(size, /)

返回一個包含 size 個隨機位元組的位元組串,適用於加密用途。

此函式從特定於作業系統的隨機性源返回隨機位元組。返回的資料對於加密應用程式應該足夠不可預測,儘管其確切質量取決於作業系統實現。

在 Linux 上,如果 getrandom() 系統呼叫可用,它將以阻塞模式使用:阻塞直到系統 urandom 熵池初始化(核心收集到 128 位熵)。有關理由,請參見 PEP 524。在 Linux 上,可以使用 getrandom() 函式以非阻塞模式(使用 GRND_NONBLOCK 標誌)獲取隨機位元組,或者輪詢直到系統 urandom 熵池初始化。

在類 Unix 系統上,隨機位元組從 /dev/urandom 裝置讀取。如果 /dev/urandom 裝置不可用或不可讀,則會引發 NotImplementedError 異常。

在 Windows 上,它將使用 BCryptGenRandom()

參見

secrets 模組提供了更高級別的函式。有關平臺提供的隨機數生成器的易於使用的介面,請參見 random.SystemRandom

3.5 版本中的變化: 在 Linux 3.17 及更高版本上,如果可用,現在使用 getrandom() 系統呼叫。在 OpenBSD 5.6 及更高版本上,現在使用 C getentropy() 函式。這些函式避免了內部檔案描述符的使用。

3.5.2 版本中的變化: 在 Linux 上,如果 getrandom() 系統呼叫阻塞(urandom 熵池尚未初始化),則回退到讀取 /dev/urandom

3.6 版本中的變化: 在 Linux 上,getrandom() 現在以阻塞模式使用以提高安全性。

3.11 版本中的變化: 在 Windows 上,使用 BCryptGenRandom() 代替已棄用的 CryptGenRandom()

os.GRND_NONBLOCK

預設情況下,當從 /dev/random 讀取時,如果沒有可用的隨機位元組,getrandom() 會阻塞;當從 /dev/urandom 讀取時,如果熵池尚未初始化,它也會阻塞。

如果設定了 GRND_NONBLOCK 標誌,則 getrandom() 在這些情況下不會阻塞,而是立即引發 BlockingIOError

在 3.6 版本加入。

os.GRND_RANDOM

如果設定了此位,則隨機位元組將從 /dev/random 池而不是 /dev/urandom 池中抽取。

在 3.6 版本加入。