os — 雜項作業系統介面

原始碼: Lib/os.py

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

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

  • Python 中所有內建的作業系統相關模組的設計原則是，只要存在相同的功能，就會使用相同的介面；例如，函式 os.stat(path) 以相同的格式（碰巧起源於 POSIX 介面）返回關於 path 的 stat 資訊。

  • 特定於特定作業系統的擴充套件也可以透過 os 模組獲得，但使用它們當然會對可移植性構成威脅。

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

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

  • 在 WebAssembly 平臺、Android 和 iOS 上，os 模組的很大一部分不可用或行為不同。與程序相關的 API（例如 fork()、execve()）和資源相關的 API（例如 nice()）不可用。其他如 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_encoding 和 filesystem_errors PyConfig 的成員。

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

檔案系統編碼 必須保證成功解碼所有低於 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 區域設定為 C 或 POSIX，則會啟用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()。

在 3.9 版本中更改: 更新以支援 PEP 584 的合併（|）和更新（|=）運算子。

os.environb

environ 的位元組版本：一個對映物件，其中鍵和值都是表示程序環境的 bytes 物件。environ 和 environb 是同步的（修改 environb 會更新 environ，反之亦然）。

僅當 supports_bytes_environ 為 True 時，environb 才可用。

在 3.2 版本中新增。

在 3.9 版本中更改: 更新以支援 PEP 584 的合併（|）和更新（|=）運算子。

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)

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

如果傳入的是 str 或 bytes，則會原封不動地返回。否則，會呼叫 __fspath__()，並且只要其值是 str 或 bytes 物件，就會返回其值。在所有其他情況下，會引發 TypeError 異常。

3.6 版本新增。

class os.PathLike

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

3.6 版本新增。

abstractmethod __fspath__()

返回物件的檔案系統路徑表示形式。

該方法應僅返回 str 或 bytes 物件，首選 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() 的對映同樣也在匯入時被捕獲，並且該函式可能無法反映未來的環境更改。

僅當 supports_bytes_environ 為 True 時，getenvb() 才可用。

可用性: Unix。

在 3.2 版本中新增。

os.get_exec_path(env=None)

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

在 3.2 版本中新增。

os.getegid()

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

可用性：Unix，非 WASI。

os.geteuid()

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

可用性：Unix，非 WASI。

os.getgid()

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

可用性: Unix。

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

os.getgrouplist(user, group, /)

返回 _user_ 所屬的組 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() 更有用，因為後者會檢查環境變數 LOGNAME 或 USERNAME 來找出使用者是誰，並回退到 pwd.getpwuid(os.getuid())[0] 以獲取當前真實使用者 ID 的登入名。

可用性: Unix, Windows, not 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，該 ID 可能已被另一個程序重用。

可用性: Unix, Windows, not WASI。

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

os.getpriority(which, who)

獲取程式排程優先順序。*which* 的值是 PRIO_PROCESS, PRIO_PGRP, 或 PRIO_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, not WASI, not 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.environ 和 os.environb。

注意

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

引發帶有引數 key, value 的 審計事件 os.putenv。

3.9 版本更改: 該函式現在始終可用。

os.setegid(egid, /)

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

可用性: Unix, not WASI, not Android。

os.seteuid(euid, /)

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

可用性: Unix, not WASI, not Android。

os.setgid(gid, /)

設定當前程序的組 ID。

可用性: Unix, not WASI, not Android。

os.setgroups(groups, /)

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

可用性：Unix，非 WASI。

注意

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

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_PROCESS、 PRIO_PGRP 或 PRIO_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, not WASI, not Android。

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

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

可用性: Unix, not WASI, not Android。

在 3.2 版本中新增。

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

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

可用性: Unix, not WASI, not Android。

在 3.2 版本中新增。

os.setreuid(ruid, euid, /)

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

可用性: Unix, not WASI, not Android。

os.getsid(pid, /)

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

可用性：Unix，非 WASI。

os.setsid()

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

可用性：Unix，非 WASI。

os.setuid(uid, /)

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

可用性: Unix, not WASI, not 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 - 硬體識別符號

為了向後相容，此物件也是可迭代的，其行為類似於包含 sysname、 nodename、 release、 version 和 machine 的五元組，按此順序排列。

某些系統將 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 的項。

引發帶引數 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（即，兩個或多個 inode 共享指向同一寫時複製磁碟塊的指標；支援的檔案系統包括 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。 預設情況下，新的檔案描述符是可繼承的，如果 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)。

引發一個帶有引數 path, mode, dir_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)。

引發一個帶有引數 path, uid, gid, dir_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)。

引發一個帶有引數 fd, length 的 審計事件 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_LOCK, F_TLOCK, F_ULOCK 或 F_TEST 其中之一。len 指定要鎖定的檔案部分。

引發一個帶引數 fd, cmd, len 的 審計事件 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_SET 或 0 – 將 pos 設定為相對於檔案開頭的位置

  • SEEK_CUR 或 1 – 將 pos 設定為相對於當前檔案位置的位置

  • SEEK_END 或 2 – 將 pos 設定為相對於檔案末尾的位置

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

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

在 3.3 版本中更改: 添加了對 SEEK_HOLE 和 SEEK_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_RDONLY 和 O_WRONLY) 在 os 模組中定義。特別是在 Windows 上，需要新增 O_BINARY 才能以二進位制模式開啟檔案。

此函式可以使用 dir_fd 引數支援相對於目錄描述符的路徑。

引發一個帶引數 path, mode, flags 的審計事件 open。

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

注意

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

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.5 版本中更改: 如果系統呼叫被中斷並且訊號處理程式沒有引發異常，該函式現在會重試系統呼叫，而不是引發 InterruptedError 異常（有關基本原理，請參閱PEP 475）。

在 3.6 版本中更改: 接受一個路徑類物件。

以下常量是 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_EVTONLY, O_FSYNC, O_SYMLINK 和 O_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 Kernel 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* 可以透過對一個或多個以下值進行 OR 運算來構造：O_NONBLOCK, O_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_NORMAL，POSIX_FADV_SEQUENTIAL，POSIX_FADV_RANDOM，POSIX_FADV_NOREUSE，POSIX_FADV_WILLNEED 或 POSIX_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 位置讀取資料到可變的 類位元組物件 buffers 中，不改變檔案偏移量。 將資料傳輸到每個緩衝區，直到它被填滿，然後移動到序列中的下一個緩衝區以儲存剩餘的資料。

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

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

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

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

可用性：Linux >= 2.6.30，FreeBSD >= 6.0，OpenBSD >= 2.7，AIX >= 7.1。

使用標誌需要 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 中的位元組串寫入檔案描述符 fd 的 offset 位置，不改變檔案偏移量。

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

可用性: Unix。

3.3 版本新增。

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

將 buffers 的內容寫入檔案描述符 fd 的 offset 偏移量處，不改變檔案偏移量。 buffers 必須是類位元組物件的序列。緩衝區按陣列順序處理。在處理第二個緩衝區之前，寫入第一個緩衝區的全部內容，依此類推。

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

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

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

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

可用性：Linux >= 2.6.30，FreeBSD >= 6.0，OpenBSD >= 2.7，AIX >= 7.1。

使用標誌需要 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.sendfile(out_fd, in_fd, offset, count)
os.sendfile(out_fd, in_fd, offset, count, headers=(), trailers=(), flags=0)

從檔案描述符 in_fd 複製 count 個位元組到檔案描述符 out_fd，起始偏移量為 offset。返回已傳送的位元組數。當到達 EOF 時，返回 0。

第一個函式表示法被所有定義了 sendfile() 的平臺支援。

在 Linux 上，如果 offset 被指定為 None，則位元組將從 in_fd 的當前位置讀取，並且 in_fd 的位置將被更新。

第二種情況可以在 macOS 和 FreeBSD 上使用，其中 headers 和 trailers 是任意的緩衝區序列，它們在寫入 in_fd 的資料之前和之後寫入。它返回與第一種情況相同的結果。

在 macOS 和 FreeBSD 上，如果 count 的值為 0，則表示傳送直到到達 in_fd 的末尾。

所有平臺都支援將套接字作為 out_fd 檔案描述符，並且某些平臺還允許其他型別（例如，普通檔案、管道）。

跨平臺應用程式不應使用 headers、trailers 和 flags 引數。

可用性：Unix，非 WASI。

注意

對於 sendfile() 的更高階封裝，請參閱 socket.socket.sendfile()。

3.3 版本新增。

在 3.9 版本中更改: 引數 out 和 in 重新命名為 out_fd 和 in_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, /)

設定指定檔案描述符的阻塞模式。如果 blocking 為 False，則設定 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)

將 count 個位元組從檔案描述符 src，從偏移量 offset_src 開始，傳輸到檔案描述符 dst，從偏移量 offset_dst 開始。至少一個檔案描述符必須引用管道。如果 offset_src 為 None，則從 src 的當前位置讀取；offset_dst 也是如此。與管道關聯的檔案描述符的偏移量必須為 None。src 和 dst 指向的檔案必須位於同一檔案系統中，否則會引發 OSError，其 errno 設定為 errno.EXDEV。

此複製操作不會額外消耗將資料從核心傳輸到使用者空間，然後再返回到核心的成本。此外，某些檔案系統可以實現額外的最佳化。複製操作就像以二進位制方式開啟兩個檔案一樣執行。

成功完成後，返回從管道拼接或拼接進管道的位元組數。返回值 0 表示輸入結束。如果 src 引用管道，則表示沒有要傳輸的資料，並且阻塞是沒有意義的，因為沒有寫入器連線到管道的寫入端。

可用性：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.stdout 或 sys.stderr，請使用其 write() 方法。

3.5 版本已更改: 如果系統呼叫被中斷且訊號處理程式沒有引發異常，則該函式現在會重試系統呼叫，而不是引發 InterruptedError 異常（參見 PEP 475 獲取原因）。

os.writev(fd, buffers, /)

將 buffers 的內容寫入檔案描述符 fd。buffers 必須是 位元組類物件 的序列。緩衝區按陣列順序處理。在處理第二個緩衝區之前，會先寫入第一個緩衝區的全部內容，依此類推。

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

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

可用性: Unix。

3.3 版本新增。

查詢終端的大小

3.3 版本新增。

os.get_terminal_size(fd=STDOUT_FILENO, /)

以 (列數, 行數) 的形式返回終端視窗的大小，型別為 terminal_size 的元組。

可選引數 fd （預設為 STDOUT_FILENO 或標準輸出）指定應查詢哪個檔案描述符。

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

shutil.get_terminal_size() 是通常應使用的高階函式，而 os.get_terminal_size 是底層實現。

可用性: Unix, Windows。

class os.terminal_size

元組的子類，儲存終端視窗大小的 (列數, 行數)。

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_fd 或 follow_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)

使用實際的 uid/gid 來測試對 path 的訪問許可權。請注意，大多數操作將使用有效的 uid/gid，因此可以在 suid/sgid 環境中使用此例程來測試呼叫使用者是否具有對 path 的指定訪問許可權。mode 應該是 F_OK，用於測試 path 的存在性，或者它可以是 R_OK、W_OK 和 X_OK 中一個或多個的按位或，用於測試許可權。如果允許訪問，則返回 True；如果未允許訪問，則返回 False。有關更多資訊，請參見 Unix 手冊頁 access(2)。

此函式支援指定相對於目錄描述符的路徑和不跟蹤符號連結。

如果 effective_ids 為 True，access() 將使用有效的 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_fd、effective_ids 和 follow_symlinks 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

os.chdir(path)

將當前工作目錄更改為 path。

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

此函式可能會引發 OSError 及其子類，例如 FileNotFoundError、PermissionError 和 NotADirectoryError。

引發帶有引數 path 的 審計事件 os.chdir。

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

在 3.6 版本中更改: 接受一個路徑類物件。

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

將 path 的標誌設定為數值 flags。flags 可以採用以下值的組合（按位 OR）（定義在 stat 模組中）

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

引發帶有引數 path, flags 的 審計事件 os.chflags。

可用性：Unix，非 WASI。

在 3.3 版本中更改: 添加了 follow_symlinks 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

將 path 的模式更改為數值 mode。mode 可以採用以下值之一（定義在 stat 模組中）或它們的按位 OR 組合

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

注意

儘管 Windows 支援 chmod()，但您只能使用它設定檔案的只讀標誌（透過 stat.S_IWRITE 和 stat.S_IREAD 常量或相應的整數值）。所有其他位都會被忽略。在 Windows 上，follow_symlinks 的預設值為 False。

該函式在 WASI 上受到限制，有關更多資訊，請參見WebAssembly 平臺。

引發一個帶有引數 path, mode, dir_fd 的 審計事件 os.chmod。

在 3.3 版本中更改: 添加了支援將 path 指定為開啟的檔案描述符，以及 dir_fd 和 follow_symlinks 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

將 path 的所有者和組 id 更改為數值 uid 和 gid。要使其中一個 id 保持不變，請將其設定為 -1。

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

有關接受名稱以及數字 id 的更高級別的函式，請參閱 shutil.chown()。

引發一個帶有引數 path, uid, gid, dir_fd 的 審計事件 os.chown。

可用性: Unix。

該函式在 WASI 上受到限制，有關更多資訊，請參見WebAssembly 平臺。

在 3.3 版本中更改: 添加了支援將 path 指定為開啟的檔案描述符，以及 dir_fd 和 follow_symlinks 引數。

在 3.6 版本中更改: 支援 路徑類物件。

os.chroot(path)

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

可用性: Unix, not WASI, not Android。

在 3.6 版本中更改: 接受一個路徑類物件。

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)。

引發帶有引數 path, flags 的 審計事件 os.chflags。

可用性：Unix，非 WASI。

在 3.6 版本中更改: 接受一個路徑類物件。

os.lchmod(path, mode)

將 path 的模式更改為數值 mode。如果 path 是符號連結，這將影響符號連結而不是目標。請參閱 chmod() 的文件，瞭解 mode 的可能值。從 Python 3.3 開始，這等價於 os.chmod(path, mode, follow_symlinks=False)。

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

引發一個帶有引數 path, mode, dir_fd 的 審計事件 os.chmod。

可用性：Unix, Windows, 非 Linux，FreeBSD >= 1.3, NetBSD >= 1.3, 非 OpenBSD

在 3.6 版本中更改: 接受一個路徑類物件。

在 3.13 版本中更改: 添加了對 Windows 的支援。

os.lchown(path, uid, gid)

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

引發一個帶有引數 path, uid, gid, dir_fd 的 審計事件 os.chown。

可用性: Unix。

在 3.6 版本中更改: 接受一個路徑類物件。

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

此函式可以支援指定 src_dir_fd 和/或 dst_dir_fd 以提供相對於目錄描述符的路徑，以及不跟蹤符號連結。

引發一個 審計事件 os.link，其引數為 src、 dst、 src_dir_fd、 dst_dir_fd。

可用性: Unix, Windows。

在 3.2 版本中更改: 添加了 Windows 支援。

在 3.3 版本中更改: 添加了 src_dir_fd、 dst_dir_fd 和 follow_symlinks 引數。

在 3.6 版本中更改: 接受 src 和 dst 的path-like 物件。

os.listdir(path='.')

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

path 可以是path-like 物件。如果 path 的型別是 bytes（直接或透過 PathLike 介面間接），則返回的檔名也將是 bytes 型別；在所有其他情況下，它們將是 str 型別。

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

引發一個 審計事件 os.listdir，其引數為 path。

注意

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

另請參閱

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

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

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

在 3.6 版本中更改: 接受一個路徑類物件。

os.listdrives()

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

驅動器名稱通常看起來像 'C:\\'。並非每個驅動器名稱都會與卷相關聯，並且有些驅動器名稱可能由於各種原因（包括許可權、網路連線或缺少媒體）而無法訪問。此函式不測試訪問許可權。

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

引發一個 審計事件 os.listdrives，不帶任何引數。

可用性：Windows

3.12 版本新增。

os.listmounts(volume)

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

volume 必須表示為 GUID 路徑，類似於 os.listvolumes() 返回的路徑。卷可以掛載在多個位置，也可以根本不掛載。在後一種情況下，列表將為空。此函式不會返回與卷無關的掛載點。

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

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

引發一個 審計事件 os.listmounts，其引數為 volume。

可用性：Windows

3.12 版本新增。

os.listvolumes()

返回一個列表，其中包含系統中的卷。

卷通常表示為類似於 \\?\Volume{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}\ 的 GUID 路徑。通常可以透過 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 版本中更改: 接受一個路徑類物件。

在 3.8 版本中變更: 在 Windows 上，現在會開啟代表另一個路徑的重分析點（名稱代理），包括符號連結和目錄連線。其他型別的重分析點會由作業系統按照 stat() 的方式解析。

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

建立一個名為 path 的目錄，其數字模式為 mode。

如果目錄已存在，則會引發 FileExistsError 異常。 如果路徑中的父目錄不存在，則會引發 FileNotFoundError 異常。

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

在 Windows 上，會專門處理 0o700 的 mode 值，以便將訪問控制應用於新目錄，使得只有當前使用者和管理員才有訪問許可權。 其他 mode 值將被忽略。

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

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

引發帶有引數 path、mode、dir_fd 的 審計事件 os.mkdir。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

在 3.13 版本中變更: Windows 現在會處理 0o700 的 mode 值。

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

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

mode 引數被傳遞給 mkdir() 以建立葉目錄； 請參閱 mkdir() 描述 以瞭解其如何解釋。 要設定任何新建立的父目錄的檔案許可權位，可以在呼叫 makedirs() 之前設定 umask。 現有父目錄的檔案許可權位不會更改。

如果 exist_ok 為 False (預設值)，則如果目標目錄已存在，會引發 FileExistsError 異常。

注意

如果要建立的路徑元素包含 pardir （例如，UNIX 系統上的 “..”），makedirs() 會感到困惑。

此函式可以正確處理 UNC 路徑。

引發帶有引數 path、mode、dir_fd 的 審計事件 os.mkdir。

在 3.2 版本中變更: 添加了 exist_ok 引數。

在 3.4.1 版本中變更: 在 Python 3.4.1 之前，如果 exist_ok 為 True 且目錄存在，如果 mode 與現有目錄的模式不匹配，makedirs() 仍然會引發錯誤。 由於這種行為無法安全地實現，因此在 Python 3.4.1 中被刪除。 請參閱 bpo-21082。

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

建立一個名為 path 的 FIFO（命名管道），其數字模式為 mode。 首先從模式中遮蔽掉當前的 umask 值。

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

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

可用性：Unix，非 WASI。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

建立一個名為 path 的檔案系統節點（檔案、裝置特殊檔案或命名管道）。 mode 指定要使用的許可權和要建立的節點型別，並與 stat.S_IFREG、stat.S_IFCHR、stat.S_IFBLK 和 stat.S_IFIFO 之一組合（按位或）（這些常量在 stat 中可用）。 對於 stat.S_IFCHR 和 stat.S_IFBLK，device 定義新建立的裝置特殊檔案（可能使用 os.makedev()），否則將被忽略。

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

可用性：Unix，非 WASI。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

os.major(device, /)

從原始裝置號（通常是來自 stat 的 st_dev 或 st_rdev 欄位）中提取裝置主號碼。

os.minor(device, /)

從原始裝置號（通常是來自 stat 的 st_dev 或 st_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 版本中更改: 接受一個路徑類物件。

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 上接受 path-like object。

3.8 版本更改: 在 Windows 上接受 path-like object 和位元組物件。

增加了對目錄連線點的支援，並更改為返回替換路徑（通常包括 \\?\ 字首），而不是之前返回的可選 “列印名稱” 欄位。

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

刪除（刪除）檔案 path。如果 path 是一個目錄，則會引發 OSError。使用 rmdir() 刪除目錄。如果檔案不存在，則會引發 FileNotFoundError。

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

在 Windows 上，嘗試刪除正在使用的檔案會導致引發異常；在 Unix 上，目錄條目會被刪除，但是分配給檔案的儲存空間只有在原始檔案不再使用時才可用。

此函式在語義上與 unlink() 相同。

引發一個帶有引數 path、dir_fd 的 審計事件 os.remove。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

os.removedirs(name)

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

引發一個帶有引數 path、dir_fd 的 審計事件 os.remove。

在 3.6 版本中更改: 接受一個路徑類物件。

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

將檔案或目錄 src 重新命名為 dst。如果 dst 存在，則在多種情況下，操作將失敗並引發 OSError 子類。

在 Windows 上，如果 dst 存在，則始終會引發 FileExistsError。如果 src 和 dst 位於不同的檔案系統上，則操作可能會失敗。使用 shutil.move() 來支援移動到不同的檔案系統。

在 Unix 上，如果 src 是一個檔案，而 dst 是一個目錄，反之亦然，則將分別引發 IsADirectoryError 或 NotADirectoryError。如果兩者都是目錄，並且 dst 為空，則 dst 將被靜默替換。如果 dst 是一個非空目錄，則會引發 OSError。如果兩者都是檔案，則如果使用者具有許可權，則 dst 將被靜默替換。如果 src 和 dst 位於不同的檔案系統上，則該操作在某些 Unix 版本上可能會失敗。如果成功，重新命名將是一個原子操作（這是 POSIX 要求）。

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

如果要跨平臺覆蓋目標，請使用 replace()。

引發一個帶有引數 src、dst、src_dir_fd、dst_dir_fd 的 審計事件 os.rename。

3.3 版本更改: 添加了 src_dir_fd 和 dst_dir_fd 引數。

在 3.6 版本中更改: 接受 src 和 dst 的path-like 物件。

os.renames(old, new)

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

注意

如果您缺乏刪除葉目錄或檔案所需的許可權，則此函式可能會失敗，並且會建立新的目錄結構。

引發一個帶有引數 src、dst、src_dir_fd、dst_dir_fd 的 審計事件 os.rename。

3.6 版本更改: 接受 old 和 new 的 path-like object。

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

將檔案或目錄 src 重新命名為 dst。如果 dst 是一個非空目錄，則會引發 OSError。如果 dst 存在並且是一個檔案，則如果使用者具有許可權，它將被靜默替換。如果 src 和 dst 位於不同的檔案系統上，則該操作可能會失敗。如果成功，重新命名將是一個原子操作（這是 POSIX 要求）。

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

引發一個帶有引數 src、dst、src_dir_fd、dst_dir_fd 的 審計事件 os.rename。

3.3 版本新增。

在 3.6 版本中更改: 接受 src 和 dst 的path-like 物件。

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

刪除（刪除）目錄 path。如果目錄不存在或不為空，則會分別引發 FileNotFoundError 或 OSError。為了刪除整個目錄樹，可以使用 shutil.rmtree()。

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

引發一個帶有引數 path、dir_fd 的 審計事件 os.rmdir。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

os.scandir(path='.')

返回一個迭代器，該迭代器產生與 path 指定目錄中的條目對應的 os.DirEntry 物件。條目以任意順序產生，並且不包括特殊條目 '.' 和 '..'。如果在建立迭代器後從目錄中刪除或新增到目錄中，是否包含該檔案的條目是不確定的。

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

path 可以是 路徑類物件。如果 path 的型別為 bytes（直接或間接透過 PathLike 介面），則每個 os.DirEntry 的 name 和 path 屬性的型別將為 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 FindFirstFileW 和 FindNextFileW 函式。

在 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_path 是 scandir() 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_symlinks 為 False，則僅當此條目是目錄（不跟隨符號連結）時才返回 True；如果此條目是任何其他型別的檔案或如果它不再存在，則返回 False。

結果快取在 os.DirEntry 物件上，並且為 follow_symlinks True 和 False 使用單獨的快取。呼叫 os.stat() 以及 stat.S_ISDIR() 來獲取最新資訊。

在首次未快取的呼叫中，大多數情況下不需要系統呼叫。具體來說，對於非符號連結，Windows 或 Unix 都不需要系統呼叫，除非在某些 Unix 檔案系統（如網路檔案系統）上，這些檔案系統返回 dirent.d_type == DT_UNKNOWN。如果條目是符號連結，則需要系統呼叫來跟蹤符號連結，除非 follow_symlinks 為 False。

此方法可能引發 OSError，例如 PermissionError，但是 FileNotFoundError 會被捕獲而不會引發。

is_file(*, follow_symlinks=True)

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

如果 follow_symlinks 為 False，則僅當此條目是檔案（不跟隨符號連結）時才返回 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 物件。預設情況下，此方法遵循符號連結；要統計符號連結，請新增 follow_symlinks=False 引數。

在 Unix 上，此方法始終需要系統呼叫。在 Windows 上，僅當 follow_symlinks 為 True 且條目是重解析點（例如，符號連結或目錄連線點）時才需要系統呼叫。

在 Windows 上，stat_result 的 st_ino、st_dev 和 st_nlink 屬性始終設定為零。呼叫 os.stat() 獲取這些屬性。

結果快取在 os.DirEntry 物件上，並且為 follow_symlinks True 和 False 使用單獨的快取。呼叫 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 物件。

此函式通常會跟隨符號連結；要獲取符號連結的狀態，請新增引數 follow_symlinks=False，或者使用 lstat()。

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

在 Windows 上，傳遞 follow_symlinks=False 將停用跟隨所有名稱代理重分析點，包括符號連結和目錄連線。其他型別的不像連結或作業系統無法跟隨的重分析點將直接開啟。當跟隨多個連結的鏈時，這可能會導致返回原始連結而不是阻止完全遍歷的非連結。在這種情況下，要獲取最終路徑的狀態結果，請使用 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_fd 和 follow_symlinks 引數，指定檔案描述符而不是路徑。

在 3.6 版本中更改: 接受一個路徑類物件。

在 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 版本中更改: st_ctime 在 Windows 上已棄用。請使用 st_birthtime 獲取檔案建立時間。將來，st_ctime 將包含最近一次元資料更改的時間，與其他平臺相同。

st_atime_ns

最近一次訪問的時間（以納秒為單位的整數）。

3.3 版本新增。

st_mtime_ns

最近一次內容修改的時間（以納秒為單位的整數）。

3.3 版本新增。

st_ctime_ns

最近一次元資料更改的時間（以納秒為單位的整數）。

3.3 版本新增。

在 3.12 版本中更改: st_ctime_ns 在 Windows 上已棄用。請使用 st_birthtime_ns 獲取檔案建立時間。將來，st_ctime 將包含最近一次元資料更改的時間，與其他平臺相同。

st_birthtime

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

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

st_birthtime_ns

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

3.12 版本新增。

注意

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

類似地，儘管 st_atime_ns、st_mtime_ns、st_ctime_ns 和 st_birthtime_ns 總是以納秒為單位表示，但許多系統不提供納秒精度。在提供納秒精度的系統上，用於儲存 st_atime、st_mtime、st_ctime 和 st_birthtime 的浮點物件無法保留所有精度，因此會略有不精確。如果您需要精確的時間戳，則應始終使用 st_atime_ns、st_mtime_ns、st_ctime_ns 和 st_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 檔案屬性： dwFileAttributes 是 BY_HANDLE_FILE_INFORMATION 結構體的成員，由 GetFileInformationByHandle() 返回。請參閱 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 個整數的元組訪問，這些整數給出了 stat 結構體中最重要（且可移植）的成員，順序為 st_mode、 st_ino、 st_dev、 st_nlink、 st_uid、 st_gid、 st_size、 st_atime、 st_mtime、 st_ctime。某些實現可能會在末尾新增更多項。為了與舊版本的 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_IFCHR、 S_IFIFO 或 S_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_bsize, f_frsize, f_blocks, f_bfree, f_bavail, f_files, f_ffree, f_favail, f_flag, f_namemax, f_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 （相對於 mtime/ctime 更新 atime）。

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

可用性: Unix。

在 3.2 版本中更改: 添加了 ST_RDONLY 和 ST_NOSUID 常量。

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

在 3.4 版本中更改: 添加了 ST_NODEV、 ST_NOEXEC、 ST_SYNCHRONOUS、 ST_MANDLOCK、 ST_WRITE、 ST_APPEND、 ST_IMMUTABLE、 ST_NOATIME、 ST_NODIRATIME 和 ST_RELATIME 常量。

在 3.6 版本中更改: 接受一個路徑類物件。

在 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 模組中哪些函式在本地平臺上接受 False 作為它們的 follow_symlinks 引數。不同的平臺提供不同的特性，並且 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 版本新增。

建立一個名為 dst 的符號連結，指向 src。

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

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

注意

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

當非特權使用者呼叫該函式時，會引發 OSError。

引發一個 審計事件 os.symlink，帶有引數 src、dst、dir_fd。

可用性: Unix, Windows。

該函式在 WASI 上受到限制，有關更多資訊，請參見WebAssembly 平臺。

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

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

在 3.6 版本中更改: 接受 src 和 dst 的path-like 物件。

在 3.8 版本中更改: 增加了對 Windows 上使用“開發人員模式”的非提升符號連結的支援。

os.sync()

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

可用性: Unix。

3.3 版本新增。

os.truncate(path, length)

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

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

引發一個 審計事件 os.truncate，帶有引數 path、length。

可用性: Unix, Windows。

3.3 版本新增。

在 3.5 版本中更改: 添加了對 Windows 的支援

在 3.6 版本中更改: 接受一個路徑類物件。

刪除（刪除）檔案 path。此函式在語義上與 remove() 相同；unlink 名稱是其傳統的 Unix 名稱。有關詳細資訊，請參閱 remove() 的文件。

引發一個帶有引數 path、dir_fd 的 審計事件 os.remove。

在 3.3 版本中更改: 添加了 dir_fd 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

utime() 接受兩個可選引數 times 和 ns。這些引數指定在 path 上設定的時間，並按如下方式使用

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

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

  • 如果 times 為 None 且未指定 ns，則等效於指定 ns=(atime_ns, mtime_ns)，其中兩個時間均為當前時間。

同時為 times 和 ns 指定元組是一個錯誤。

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

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

引發一個 審計事件 os.utime，引數為 path，times，ns，dir_fd。

在 3.3 版本中更改: 添加了支援將 path 指定為開啟的檔案描述符，以及 dir_fd、follow_symlinks 和 ns 引數。

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

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

如果可選引數 topdown 為 True 或未指定，則在為其任何子目錄生成三元組之前，先生成目錄的三元組（目錄是自頂向下生成的）。如果 topdown 為 False，則在為其所有子目錄生成三元組之後，再生成目錄的三元組（目錄是自底向上生成的）。無論 topdown 的值如何，都會在生成目錄及其子目錄的元組之前檢索子目錄的列表。

當 topdown 為 True 時，呼叫方可以就地修改 dirnames 列表（可能使用 del 或切片賦值），並且 walk() 只會遞迴到名稱保留在 dirnames 中的子目錄中；這可以用於修剪搜尋，強制執行特定的訪問順序，甚至可以通知 walk() 呼叫方在其恢復 walk() 之前建立或重新命名的目錄。當 topdown 為 False 時，修改 dirnames 對遍歷的行為沒有影響，因為在自底向上模式下，dirnames 中的目錄是在生成 dirpath 本身之前生成的。

預設情況下，會忽略來自 scandir() 呼叫的錯誤。如果指定了可選引數 onerror，則它應該是一個函式；它將使用一個引數（即 OSError 例項）進行呼叫。它可以報告錯誤以繼續遍歷，或者引發異常以中止遍歷。請注意，檔名在異常物件的 filename 屬性中可用。

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

注意

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

注意

如果傳遞相對路徑名，請不要在恢復 walk() 之間更改當前工作目錄。walk() 永遠不會更改當前目錄，並且假設其呼叫方也不會更改。

此示例顯示了起始目錄下的每個目錄中非目錄檔案佔用的位元組數，但它不會在任何 CVS 子目錄下查詢

import os
from os.path import join, getsize
for root, dirs, files in os.walk('python/Lib/email'):
    print(root, "consumes", end=" ")
    print(sum(getsize(join(root, name)) for name in files), end=" ")
    print("bytes in", len(files), "non-directory files")
    if 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS 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，引數為 top，topdown，onerror，followlinks。

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

在 3.6 版本中更改: 接受一個路徑類物件。

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

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

dirpath、dirnames 和 filenames 與 walk() 輸出相同，而 dirfd 是一個指向目錄 dirpath 的檔案描述符。

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

注意

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

此示例顯示了起始目錄下的每個目錄中非目錄檔案佔用的位元組數，但它不會在任何 CVS 子目錄下查詢

import os
for root, dirs, files, rootfd in os.fwalk('python/Lib/email'):
    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 'CVS' in dirs:
        dirs.remove('CVS')  # don't visit CVS 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，引數為 top, topdown, onerror, follow_symlinks, dir_fd。

可用性: Unix。

3.3 版本新增。

在 3.6 版本中更改: 接受一個路徑類物件。

在 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 位無符號整數。請注意，儘管事件計數器是最大值為 264-2 的 64 位無符號整數，但初始值被限制為 32 位無符號整數。

flags 可以由 EFD_CLOEXEC、EFD_NONBLOCK 和 EFD_SEMAPHORE 構造。

如果指定了 EFD_SEMAPHORE 並且事件計數器非零，則 eventfd_read() 返回 1 並將計數器減 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() 檔案描述符讀取操作提供類似訊號量的語義。讀取時，內部計數器減 1。

可用性: Linux >= 2.6.30

在版本 3.10 中新增。

定時器檔案描述符

在 3.13 版本中新增。

這些函式為 Linux 的定時器檔案描述符 API 提供支援。自然地，它們都僅在 Linux 上可用。

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

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

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

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

可以使用 select() 和 poll() 等待直到定時器過期且檔案描述符可讀。

clockid 必須是一個有效的 時鐘 ID，定義在 time 模組中。

如果 clockid 為 time.CLOCK_REALTIME，則使用可設定的系統級即時時鐘。如果系統時鐘被更改，則需要更新定時器設定。要在系統時鐘更改時取消定時器，請參閱 TFD_TIMER_CANCEL_ON_SET。

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

如果 clockid 為 time.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) 的雙項元組，這些值來自此函式執行之前的定時器狀態。

另請參閱

timerfd_create(2), timerfd_settime(2), settimeofday(2), clock_settime(2), 和 date(1)。

可用性: 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 秒過去後觸發一次。

另請參閱

timerfd_gettime(2)

可用性: 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 可以是位元組或字串（直接或間接透過 PathLike 介面）。如果它是字串，則使用檔案系統編碼進行編碼。

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

觸發帶有引數 path、attribute 的 審計事件 os.getxattr。

在 3.6 版本中更改: 接受 path 和 attribute 的 類路徑物件。

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

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

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

觸發帶有引數 path 的 審計事件 os.listxattr。

在 3.6 版本中更改: 接受一個路徑類物件。

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

從 path 中刪除擴充套件檔案系統屬性 attribute。attribute 應該是位元組或字串（直接或間接透過 PathLike 介面）。如果它是字串，則使用 檔案系統編碼和錯誤處理程式 進行編碼。

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

觸發帶有引數 path、attribute 的 審計事件 os.removexattr。

在 3.6 版本中更改: 接受 path 和 attribute 的 類路徑物件。

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

將 path 上的擴充套件檔案系統屬性 attribute 設定為 value。attribute 必須是位元組或字串，且不能嵌入 NUL 字元（直接或間接透過 PathLike 介面）。如果它是字串，則使用 檔案系統編碼和錯誤處理程式 進行編碼。flags 可以是 XATTR_REPLACE 或 XATTR_CREATE。如果給定 XATTR_REPLACE 且該屬性不存在，則會引發 ENODATA。如果給定 XATTR_CREATE 且該屬性已存在，則不會建立該屬性，並會引發 EEXISTS。

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

注意

Linux 核心 2.6.39 以下版本的錯誤會導致在某些檔案系統上忽略 flags 引數。

觸發帶有引數 path、attribute、value、flags 的 審計事件 os.setxattr。

在 3.6 版本中更改: 接受 path 和 attribute 的 類路徑物件。

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']) 將僅在標準輸出上列印 bar；foo 似乎被忽略了。

os.abort()

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

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。

引發帶有引數 path、 args、 env 的 審計事件 os.exec。

可用性：Unix, Windows, 不是 WASI，不是 Android，不是 iOS。

在 3.3 版本中變更: 為 execve() 添加了支援將 path 指定為開啟的檔案描述符的功能。

在 3.6 版本中更改: 接受一個路徑類物件。

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()

fork 一個子程序。在子程序中返回 0，在父程序中返回子程序的程序 id。如果發生錯誤，則引發 OSError。

請注意，在從執行緒中使用 fork() 時，包括 FreeBSD <= 6.3 和 Cygwin 在內的一些平臺存在已知問題。

引發一個沒有引數的 審計事件 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 呼叫，這些 API 呼叫在父程序中存線上程時，在子程序中是不安全的（例如 malloc 和 free）。

使用 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_EVENT 和 signal.CTRL_BREAK_EVENT 訊號是特殊訊號，只能傳送給共享公共控制檯視窗的控制檯程序，例如某些子程序。sig 的任何其他值都會導致該程序被 TerminateProcess API 無條件終止，並且退出程式碼將設定為 sig。

另請參閱 signal.pthread_kill()。

引發一個帶有引數 pid、sig 的 審計事件 os.kill。

可用性：Unix，Windows，不是 WASI，不是 iOS。

在 3.2 版本中更改: 添加了 Windows 支援。

os.killpg(pgid, sig, /)

向程序組 pgid 傳送訊號 sig。

引發一個帶有引數 pgid、sig 的 審計事件 os.killpg。

可用性：Unix，不是 WASI，不是 iOS。

os.nice(increment, /)

將 increment 新增到程序的“優先順序”。返回新的優先順序。

可用性：Unix，非 WASI。

os.pidfd_open(pid, flags=0)

返回一個引用程序 pid 的檔案描述符，並設定了 flags。此描述符可用於執行程序管理，而不會出現競爭和訊號。

有關更多詳細資訊，請參閱 pidfd_open(2) 手冊頁。

可用性：Linux >= 5.3, Android >= build-time 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 上，如果 close 方法結果（退出狀態）不是 None，可以使用 waitstatus_to_exitcode() 將其轉換為退出程式碼。在 Windows 上，close 方法的結果直接是退出程式碼（或 None）。

這是使用 subprocess.Popen 實現的； 有關管理和與子程序通訊的更強大方法，請參閱該類的文件。

可用性：不是 WASI，不是 Android，不是 iOS。

注意

Python UTF-8 模式 會影響用於 cmd 和管道內容的編碼。

popen() 是 subprocess.Popen 的簡單包裝器。使用 subprocess.Popen 或 subprocess.run() 來控制諸如編碼之類的選項。

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()。

僅限位置的引數 path、args 和 env 類似於 execve()。env 允許為 None，在這種情況下，將使用當前程序的環境。

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_SETSID 或 POSIX_SPAWN_SETSID_NP 標誌。否則，將引發 NotImplementedError。

setsigmask 引數會將訊號掩碼設定為指定的訊號集。如果不使用該引數，則子程序將繼承父程序的訊號掩碼。此引數對應於 C 庫 POSIX_SPAWN_SETSIGMASK 標誌。

sigdef 引數將重置指定集中所有訊號的處置。此引數對應於 C 庫 POSIX_SPAWN_SETSIGDEF 標誌。

scheduler 引數必須是一個元組，包含（可選的）排程策略和具有排程引數的 sched_param 的例項。排程策略位置中的 None 值表示未提供排程策略。此引數是 C 庫 POSIX_SPAWN_SETSCHEDPARAM 和 POSIX_SPAWN_SETSCHEDULER 標誌的組合。

引發一個帶有引數 path、argv、env 的 審計事件 os.posix_spawn。

在 3.8 版本中新增。

在 3.13 版本中更改: env 引數接受 None。在存在 posix_spawn_file_actions_addclosefrom_np() 的平臺上，可以使用 os.POSIX_SPAWN_CLOSEFROM。

可用性：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 環境變數指定的目錄列表中搜索 可執行 檔案（與 execvp(3) 的方式相同）。

引發一個帶有引數 path、argv、env 的 審計事件 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 建立新的子程序時執行的可呼叫物件。引數是可選的，並且是僅限關鍵字的。每個引數都指定不同的呼叫點。

  • before 是在派生子程序之前呼叫的函式。

  • after_in_parent 是在派生子程序後從父程序呼叫的函式。

  • after_in_child 是從子程序呼叫的函式。

只有在控制權預計會返回到 Python 直譯器時，才會進行這些呼叫。典型的 subprocess 啟動不會觸發它們，因為子程序不會重新進入直譯器。

在派生之前註冊執行的函式按註冊順序的反向順序呼叫。在派生之後註冊執行的函式（在父程序或子程序中）按註冊順序呼叫。

請注意，第三方 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 模組替換舊函式 部分。）

如果 *mode* 是 P_NOWAIT，則此函式返回新程序的程序 ID；如果 *mode* 是 P_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)

使用引數 mode、 path、 args、 env 引發 審計事件 os.spawn。

可用性：Unix, Windows, 不是 WASI，不是 Android，不是 iOS。

spawnlp()、 spawnlpe()、 spawnvp() 和 spawnvpe() 在 Windows 上不可用。spawnle() 和 spawnve() 在 Windows 上不是執行緒安全的；我們建議您改用 subprocess 模組。

在 3.6 版本中更改: 接受一個路徑類物件。

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。如果要使用絕對路徑，請確保第一個字元不是斜槓 ('/')。使用 pathlib 或 os.path.normpath() 函式來確保路徑為 Win32 正確編碼。

為了減少直譯器啟動開銷，Win32 ShellExecute() 函式直到首次呼叫此函式時才會被解析。如果無法解析該函式，將引發 NotImplementedError。

引發一個 審計事件 os.startfile，引數為 path, operation。

引發一個 審計事件 os.startfile/2，引數為 path、operation、arguments、cwd、show_cmd。

可用性: Windows。

在 3.10 版本中更改: 添加了 arguments、cwd 和 show_cmd 引數，以及 os.startfile/2 審計事件。

os.system(command)

在子 shell 中執行命令（一個字串）。這是透過呼叫標準 C 函式 system() 實現的，並且具有相同的限制。sys.stdin 等的更改不會反映在執行命令的環境中。如果 command 生成任何輸出，它將被髮送到直譯器標準輸出流。C 標準未指定 C 函式的返回值含義，因此 Python 函式的返回值是系統相關的。

在 Unix 上，返回值是以 wait() 指定的格式編碼的程序退出狀態。

在 Windows 上，返回值是執行 command 後系統 shell 返回的值。shell 由 Windows 環境變數 COMSPEC 給出：它通常是 cmd.exe，它返回執行命令的退出狀態；在使用非原生 shell 的系統上，請查閱你的 shell 文件。

subprocess 模組為生成新程序和檢索其結果提供了更強大的功能；使用該模組比使用此函式更好。請參閱 subprocess 文件中的 使用 subprocess 模組替換較舊的函式 部分，以獲取一些有用的技巧。

在 Unix 上，可以使用 waitstatus_to_exitcode() 將結果（退出狀態）轉換為退出碼。在 Windows 上，結果直接是退出碼。

引發一個 審計事件 os.system，引數為 command。

可用性：Unix, Windows, 不是 WASI，不是 Android，不是 iOS。

os.times()

返回當前全域性程序時間。返回值是一個具有五個屬性的物件

  • user - 使用者時間

  • system - 系統時間

  • children_user - 所有子程序的使用者時間

  • children_system - 所有子程序的系統時間

  • elapsed - 自過去某個固定點以來經過的實際時間

為了向後相容，此物件還像一個包含 user、system、children_user、children_system 和 elapsed 的五元組（按該順序）。

請參閱 Unix 手冊頁 times(2) 和 times(3) 手冊頁（在 Unix 上）或 Windows 上的 GetProcessTimes MSDN。在 Windows 上，僅知道 user 和 system；其他屬性為零。

可用性: 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_PID、 P_PGID、 P_ALL 或 (在 Linux 上) P_PIDFD。id 的解釋取決於它；請參閱它們的單獨描述。

options 是標誌的 OR 組合。必須至少包含 WEXITED、 WSTOPPED 或 WCONTINUED 中的一個；WNOHANG 和 WNOWAIT 是額外的可選標誌。

返回值是一個物件，表示 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 大於 0，則 waitpid() 請求該特定程序的狀態資訊。如果 pid 為 0，則請求當前程序的程序組中任何子程序的狀態。如果 pid 為 -1，則請求與當前程序的任何子程序相關。如果 pid 小於 -1，則請求程序組 -pid（pid 的絕對值）中任何程序的狀態。

options 是標誌的 OR 組合。如果它包含 WNOHANG 並且在請求的狀態下沒有匹配的子程序，則返回 (0, 0)。 否則，如果沒有可以等待的匹配子程序，則會引發 ChildProcessError 異常。可以使用的其他選項是 WUNTRACED 和 WCONTINUED。

在 Windows 上：等待由程序控制代碼 pid 給出的程序完成，並返回一個包含 pid 及其退出狀態左移 8 位的元組（移位使該函式的跨平臺使用更加容易）。小於或等於 0 的 pid 在 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_KILLED 和 CLD_STOPPED 值。

os.waitstatus_to_exitcode(status)

將等待狀態轉換為退出程式碼。

在 Unix 上

  • 如果程序正常退出（如果 WIFEXITED(status) 為真），則返回程序退出狀態（返回 WEXITSTATUS(status)）：結果大於或等於 0。

  • 如果程序被訊號終止（如果 WIFSIGNALED(status) 為真），則返回 -signum，其中 signum 是導致程序終止的訊號的編號（返回 -WTERMSIG(status)）：結果小於 0。

  • 否則，引發 ValueError。

在 Windows 上，返回 status 右移 8 位的結果。

在 Unix 上，如果正在跟蹤程序或使用 WUNTRACED 選項呼叫了 waitpid()，則呼叫者必須首先檢查 WIFSTOPPED(status) 是否為真。如果 WIFSTOPPED(status) 為真，則不得呼叫此函式。

另請參閱

WIFEXITED(), WEXITSTATUS(), WIFSIGNALED(), WTERMSIG(), WIFSTOPPED(), WSTOPSIG() 函式。

可用性：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。

僅當使用 WUNTRACED 選項呼叫 waitpid()，或者當程序正在被跟蹤時（請參閱 ptrace(2)），WIFSTOPPED() 才會返回 True。

可用性：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() 為 true 時，才應使用此函式。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

os.WSTOPSIG(status)

返回導致程序停止的訊號。

僅當 WIFSTOPPED() 為 true 時，才應使用此函式。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

os.WTERMSIG(status)

返回導致程序終止的訊號編號。

僅當 WIFSIGNALED() 為真時才應使用此函式。

可用性：Unix，不是 WASI，不是 Android，不是 iOS。

排程器介面

這些函式控制作業系統如何為程序分配 CPU 時間。它們僅在某些 Unix 平臺上可用。有關更多詳細資訊，請查閱您的 Unix 手冊頁。

3.3 版本新增。

如果作業系統支援，則會公開以下排程策略。

os.SCHED_OTHER

預設排程策略。

os.SCHED_BATCH

用於 CPU 密集型程序的排程策略，它嘗試在計算機的其餘部分保留互動性。

os.SCHED_IDLE

用於極低優先順序後臺任務的排程策略。

os.SCHED_SPORADIC

用於零星伺服器程式的排程策略。

os.SCHED_FIFO

先進先出排程策略。

os.SCHED_RR

迴圈排程策略。

os.SCHED_RESET_ON_FORK

此標誌可以與任何其他排程策略進行 OR 運算。當設定此標誌的程序 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, /)

以 sched_param 例項形式返回 PID 為 *pid* 的程序的排程引數。*pid* 為 0 表示呼叫程序。

os.sched_rr_get_interval(pid, /)

以秒為單位返回 PID 為 *pid* 的程序的迴圈量程。*pid* 為 0 表示呼叫程序。

os.sched_yield()

自願放棄 CPU。

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_count()，具體取決於 CPU 親和性。

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 引數是一個位掩碼，可以包含零個或多個以下值進行 OR 運算：os.GRND_RANDOM 和 GRND_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 版本新增。