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
(或其子類)。
- os.name¶
匯入的作業系統相關模組的名稱。目前已註冊的名稱有:
'posix'
、'nt'
、'java'
。
檔名、命令列引數和環境變數¶
在 Python 中,檔名、命令列引數和環境變數使用字串型別表示。在某些系統上,在將這些字串傳遞給作業系統之前,需要將它們編碼為位元組並從位元組解碼。Python 使用 檔案系統編碼和錯誤處理程式 來執行此轉換(參見 sys.getfilesystemencoding()
)。
檔案系統編碼和錯誤處理程式 在 Python 啟動時透過 PyConfig_Read()
函式進行配置:參見 filesystem_encoding
和 filesystem_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 作為 檔案系統編碼。
sys.getfilesystemencoding()
返回'utf-8'
。locale.getpreferredencoding()
返回'utf-8'
(do_setlocale 引數無效)。sys.stdin
、sys.stdout
和sys.stderr
都使用 UTF-8 作為其文字編碼,其中surrogateescape
錯誤處理程式 對於sys.stdin
和sys.stdout
啟用(sys.stderr
繼續使用backslashreplace
,就像在預設的區域設定感知模式中一樣)在 Unix 上,
os.device_encoding()
返回'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.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
,反之亦然)。environb
僅在supports_bytes_environ
為True
時可用。在 3.2 版本加入。
版本 3.9 中的變更: 更新以支援 PEP 584 的合併 (
|
) 和更新 (|=
) 運算子。
- os.reload_environ()¶
os.environ
和os.environb
對映是 Python 啟動時環境變數的快取。因此,如果在 Python 外部或透過os.putenv()
或os.unsetenv()
對當前程序環境進行更改,則不會反映這些更改。使用os.reload_environ()
更新os.environ
和os.environb
以反映當前程序環境中的任何此類更改。警告
此函式不是執行緒安全的。在另一個執行緒中修改環境時呼叫它會導致未定義行為。在重新載入時從
os.environ
或os.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)¶
返回路徑的檔案系統表示。
如果傳入的是
str
或bytes
,則原樣返回。否則,將呼叫__fspath__()
,並返回其值,只要它是一個str
或bytes
物件。在所有其他情況下,會引發TypeError
。在 3.6 版本加入。
- class os.PathLike¶
表示檔案系統路徑的物件的 抽象基類,例如
pathlib.PurePath
。在 3.6 版本加入。
- 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_environ
為True
時可用。可用性: Unix。
在 3.2 版本加入。
- os.get_exec_path(env=None)¶
返回在啟動程序時,類似於 shell,將搜尋指定可執行檔案的目錄列表。如果指定了 *env*,它應該是一個環境變數字典,用於查詢 PATH。預設情況下,當 *env* 為
None
時,使用environ
。在 3.2 版本加入。
- 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()
更為有用,因為後者會檢查環境變數LOGNAME
或USERNAME
以查詢使用者是誰,並回退到pwd.getpwuid(os.getuid())[0]
以獲取當前真實使用者 ID 的登入名。可用性: Unix, Windows, 但不包括 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_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,不包括 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.environ
和os.environb
。另請參閱
os.reload_environ()
函式。備註
在某些平臺(包括 FreeBSD 和 macOS)上,設定
environ
可能會導致記憶體洩漏。請參閱putenv()
的系統文件。使用引數
key
、value
觸發 審計事件os.putenv
。版本 3.9 中的變更: 該函式現在始終可用。
- 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_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.setresgid(rgid, egid, sgid, /)¶
設定當前程序的真實、有效和儲存的組 ID。
可用性: Unix,不包括 WASI,不包括 Android。
在 3.2 版本加入。
- os.setresuid(ruid, euid, suid, /)¶
設定當前程序的真實、有效和儲存的使用者 ID。
可用性: Unix,不包括 WASI,不包括 Android。
在 3.2 版本加入。
- 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
的項。另請參閱
os.reload_environ()
函式。使用引數
key
引發 審計事件os.unsetenv
。3.9 版本中的變化: 該函式現在始終可用,並且在 Windows 上也可用。
解除程序執行上下文的部分關聯,並將它們移動到新建立的名稱空間中。有關更多詳細資訊,請參閱 unshare(2) 手冊頁。*flags* 引數是一個位掩碼,結合了零個或多個 CLONE_* 常量,它指定了執行上下文的哪些部分應該與其現有關聯解除關聯並移動到新的名稱空間。如果 *flags* 引數為
0
,則不會對呼叫程序的執行上下文進行任何更改。可用性:Linux >= 2.6.16。
3.12 新版功能.
參見
setns()
函式。
檔案物件建立¶
檔案描述符操作¶
這些函式對使用檔案描述符引用的 I/O 流進行操作。
檔案描述符是對應於當前程序已開啟的檔案的小整數。例如,標準輸入通常是檔案描述符 0,標準輸出是 1,標準錯誤是 2。程序開啟的更多檔案將依次分配 3、4、5 等。名稱“檔案描述符”有些誤導;在 Unix 平臺上,套接字和管道也由檔案描述符引用。
當需要時,可以使用 fileno()
方法獲取與 檔案物件 關聯的檔案描述符。請注意,直接使用檔案描述符將繞過檔案物件方法,忽略諸如資料的內部緩衝等方面。
- os.close(fd)¶
關閉檔案描述符 *fd*。
- 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)
。使用引數
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.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()
。在 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.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* 引數。它們的值分別為 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 版本發生變更: 接受 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_SYMLINK¶
- 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 庫未定義,則不存在。
- 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_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* 讀取到可變 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 寫入檔案描述符 fd 的 offset 位置,檔案偏移量保持不變。
返回實際寫入的位元組數。
可用性: 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_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_fd 的 offset 位置開始,複製 count 位元組到檔案描述符 out_fd。返回傳送的位元組數。到達檔案末尾時返回
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()
。在 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_src 為
None
,則從當前位置讀取 src;對於 offset_dst 也是如此。引用管道的檔案描述符的偏移量必須為None
。src 和 dst 所指向的檔案必須位於同一檔案系統中,否則會引發OSError
,並將errno
設定為errno.EXDEV
。此複製是在沒有將資料從核心傳輸到使用者空間再返回核心的額外開銷的情況下完成的。此外,某些檔案系統可以實現額外的最佳化。複製操作就像兩個檔案都以二進位制模式開啟一樣。
成功完成後,返回拼接進出管道的位元組數。返回值為 0 表示輸入結束。如果 src 引用一個管道,則這意味著沒有資料可傳輸,並且由於沒有寫入器連線到管道的寫入端,因此阻塞沒有意義。
參見
splice(2) 手冊頁。
可用性:Linux >= 2.6.17,且 glibc >= 2.5
在 3.10 版本加入。
- os.readv(fd, buffers, /)¶
從檔案描述符 fd 讀取資料到多個可變的 bytes-like objects buffers 中。將資料傳輸到每個緩衝區直到其滿,然後繼續傳輸到序列中的下一個緩衝區以容納剩餘資料。
返回實際讀取的總位元組數,這可能小於所有物件的總容量。
作業系統可能會對可使用的緩衝區數量設定限制(
sysconf()
值'SC_IOV_MAX'
)。可用性: Unix。
在 3.3 版本加入。
- 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 必須是 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。
檔案描述符的繼承
在 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, /)¶
設定指定檔案描述符的“可繼承”標誌。
檔案和目錄
在某些 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
。
不跟隨符號連結:如果 follow_symlinks 為
False
,並且要操作的路徑的最後一個元素是符號連結,則該函式將運算子號連結本身,而不是連結所指向的檔案。對於 POSIX 系統,Python 將呼叫函式的l...
變體。您可以使用
os.supports_follow_symlinks
檢查在您的平臺上某個特定函式是否支援 follow_symlinks。如果它不可用,使用它將引發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_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 版本發生變更: 接受 path-like object。
- os.chdir(path)¶
將當前工作目錄更改為 path。
此函式可以支援 指定檔案描述符。描述符必須引用一個已開啟的目錄,而不是一個開啟的檔案。
此函式可能會引發
OSError
及其子類,例如FileNotFoundError
、PermissionError
和NotADirectoryError
。使用引數
path
引發 審計事件os.chdir
。3.3 版中變更: 在某些平臺上增加了對將 path 指定為檔案描述符的支援。
在 3.6 版本發生變更: 接受 path-like object。
- os.chflags(path, flags, *, follow_symlinks=True)¶
將 path 的標誌設定為數字 flags。flags 可以採用以下值的組合(按位或)(在
stat
模組中定義)此函式可以支援 不跟隨符號連結。
使用引數
path
、flags
引發 審計事件os.chflags
。可用性: Unix,不包括 WASI。
3.3 版中變更: 添加了 follow_symlinks 引數。
在 3.6 版本發生變更: 接受 path-like object。
- os.chmod(path, mode, *, dir_fd=None, follow_symlinks=True)¶
將 path 的模式更改為數字 mode。mode 可以是以下值(在
stat
模組中定義)之一或其按位或組合此函式可以支援 指定檔案描述符、相對於目錄描述符的路徑 和 不跟隨符號連結。
備註
雖然 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 版本發生變更: 接受 path-like object。
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 版中變更: 支援 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)
。使用引數
path
、flags
引發 審計事件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 實現可能會有它。使用引數
path
、mode
、dir_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 更改為數字 uid 和 gid。此函式不會跟隨符號連結。從 Python 3.3 開始,這等同於
os.chown(path, uid, gid, follow_symlinks=False)
。使用引數
path
、uid
、gid
、dir_fd
引發 審計事件os.chown
。可用性: Unix。
在 3.6 版本發生變更: 接受 path-like object。
- os.link(src, dst, *, src_dir_fd=None, dst_dir_fd=None, follow_symlinks=True)¶
建立指向 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_fd、dst_dir_fd 和 follow_symlinks 引數。
3.6 版中變更: 接受 src 和 dst 的 path-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 上,
0o700
的 mode 被特殊處理,以對新目錄應用訪問控制,以便只有當前使用者和管理員才能訪問。mode 的其他值被忽略。此函式還可以支援 相對於目錄描述符的路徑。
也可以建立臨時目錄;請參見
tempfile
模組的tempfile.mkdtemp()
函式。使用引數
path
、mode
、dir_fd
引發 審計事件os.mkdir
。3.3 版本中的變化: 添加了 *dir_fd* 引數。
在 3.6 版本發生變更: 接受 path-like object。
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 版本發生變更: 接受 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_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 版本發生變更: 接受 path-like object。
- 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 版本發生變更: 接受 path-like object。
- os.pathconf_names¶
將
pathconf()
和fpathconf()
接受的名稱對映到主機作業系統為這些名稱定義的整數值的字典。這可用於確定系統已知的名稱集。可用性: Unix。
- os.readlink(path, *, dir_fd=None)¶
返回一個字串,表示符號連結指向的路徑。結果可以是絕對路徑名或相對路徑名;如果是相對路徑名,可以使用
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()
。使用引數
path
、dir_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
。使用引數
path
、dir_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
。如果 src 和 dst 在不同的檔案系統上,操作可能會失敗。使用shutil.move()
來支援移動到不同的檔案系統。在 Unix 上,如果 src 是檔案而 dst 是目錄,或反之,將分別引發
IsADirectoryError
或NotADirectoryError
。如果兩者都是目錄且 dst 為空,dst 將被靜默替換。如果 dst 是非空目錄,則引發OSError
。如果兩者都是檔案,如果使用者有許可權,dst 將被靜默替換。在某些 Unix 變種上,如果 src 和 dst 在不同的檔案系統上,操作可能會失敗。如果成功,重新命名將是原子操作(這是 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 object。
- os.renames(old, new)¶
遞迴目錄或檔案重新命名函式。作用類似於
rename()
,但會首先嚐試建立使新路徑名有效的任何中間目錄。重新命名後,將使用removedirs()
剪除舊名稱最右側路徑段對應的目錄。備註
如果您缺少刪除葉目錄或檔案所需的許可權,此函式可能會在新目錄結構已建立的情況下失敗。
使用引數
src
、dst
、src_dir_fd
、dst_dir_fd
引發 審計事件os.rename
。3.6 版中已更改: 接受 old 和 new 的 類路徑物件。
- 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 object。
- os.rmdir(path, *, dir_fd=None)¶
移除(刪除)目錄 path。如果目錄不存在或不為空,則分別引發
FileNotFoundError
或OSError
。為了移除整個目錄樹,可以使用shutil.rmtree()
。此函式可以支援 相對於目錄描述符的路徑。
使用引數
path
、dir_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 可以是 類路徑物件。如果 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_symlinksTrue
和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()
相同。
- is_symlink()¶
如果此條目是符號連結(即使已損壞),則返回
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_symlinks 為
True
且條目是重解析點(例如,符號連結或目錄連線點)時才需要系統呼叫。在 Windows 上,
stat_result
的st_ino
、st_dev
和st_nlink
屬性總是設定為零。呼叫os.stat()
獲取這些屬性。結果快取在
os.DirEntry
物件上,為 follow_symlinksTrue
和False
分別設定了單獨的快取。呼叫os.stat()
以獲取最新資訊。
請注意,
os.DirEntry
的幾個屬性和方法與pathlib.Path
的幾個屬性和方法之間存在很好的對應關係。特別是,name
屬性具有相同的含義,is_dir()
、is_file()
、is_symlink()
、is_junction()
和stat()
方法也如此。在 3.5 版本加入。
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
3.3 版中已更改: 添加了 dir_fd 和 follow_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_dev¶
此檔案所在的裝置的識別符號。
- st_nlink¶
硬連結數。
- 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_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_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_mode
、st_ino
、st_dev
、st_nlink
、st_uid
、st_gid
、st_size
、st_atime
、st_mtime
、st_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_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
(相對於修改/更改時間更新訪問時間)。此函式可以支援 指定檔案描述符。
可用性: 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 版本發生變更: 接受 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 版本加入。
- os.supports_follow_symlinks¶
一個
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 版本加入。
- os.symlink(src, dst, target_is_directory=False, *, dir_fd=None)¶
建立指向 src 且名為 dst 的符號連結。
在 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 object。
3.8 版本中已更改: 在 Windows 上添加了對開發者模式下非提升許可權符號連結的支援。
- os.truncate(path, length)¶
截斷與 path 對應的檔案,使其大小最多為 length 位元組。
此函式可以支援 指定檔案描述符。
引發 審計事件
os.truncate
,引數為path
、length
。可用性: Unix, Windows。
在 3.3 版本加入。
3.5 版本中的變化: 增加了對 Windows 的支援
在 3.6 版本發生變更: 接受 path-like object。
- os.unlink(path, *, dir_fd=None)¶
刪除檔案 path。此函式在語義上與
remove()
相同;unlink
名稱是其傳統的 Unix 名稱。有關更多資訊,請參閱remove()
的文件。使用引數
path
、dir_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()
接受兩個可選引數,times 和 ns。它們指定在 path 上設定的時間,並按以下方式使用如果指定了 ns,它必須是
(atime_ns, mtime_ns)
形式的 2 元組,其中每個成員都是表示納秒的整數。如果 times 不是
None
,它必須是(atime, mtime)
形式的 2 元組,其中每個成員都是表示秒的整數或浮點數。如果 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 版本發生變更: 接受 path-like object。
- 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()
不會跟蹤它已經訪問過的目錄。此示例顯示了起始目錄下每個目錄中非目錄檔案佔用的位元組數,但不檢視任何
__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
,引數為top
、topdown
、onerror
、followlinks
。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
。dirpath、dirnames 和 filenames 與
walk()
輸出相同,dirfd 是指向目錄 dirpath 的檔案描述符。此函式始終支援 相對於目錄描述符的路徑 和 不跟隨符號連結。但請注意,與其他函式不同,
fwalk()
的 follow_symlinks 預設值為False
。此示例顯示了起始目錄下每個目錄中非目錄檔案佔用的位元組數,但不檢視任何
__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
,引數為top
、topdown
、onerror
、follow_symlinks
、dir_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_CLOEXEC
、EFD_NONBLOCK
和EFD_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_NONBLOCK¶
為新的
eventfd()
檔案描述符設定O_NONBLOCK
狀態標誌。可用性:Linux >= 2.6.27
在 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
模組中定義的那樣time.CLOCK_BOOTTIME
(對於 timerfd_create,自 Linux 3.15 起)
如果 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
) 的兩項元組,表示此函式執行之前的定時器狀態。可用性: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,它將使用檔案系統編碼進行編碼。使用引數
path
、attribute
引發 審計事件os.getxattr
。3.6 版本發生變化: 接受 路徑類物件 作為 path 和 attribute。
- os.listxattr(path=None, *, follow_symlinks=True)¶
返回 path 上的擴充套件檔案系統屬性列表。列表中的屬性表示為使用檔案系統編碼解碼的字串。如果 path 為
None
,則listxattr()
將檢查當前目錄。使用引數
path
引發 審計事件os.listxattr
。在 3.6 版本發生變更: 接受 path-like object。
- os.removexattr(path, attribute, *, follow_symlinks=True)¶
從 path 中移除擴充套件檔案系統屬性 attribute。attribute 應該是 bytes 或 str(直接或透過
PathLike
介面間接)。如果是字串,它將使用檔案系統編碼和錯誤處理程式進行編碼。使用引數
path
、attribute
引發 審計事件os.removexattr
。3.6 版本發生變化: 接受 路徑類物件 作為 path 和 attribute。
- os.setxattr(path, attribute, value, flags=0, *, follow_symlinks=True)¶
將 path 上的擴充套件檔案系統屬性 attribute 設定為 value。attribute 必須是 bytes 或不帶嵌入 NUL 的 str(直接或透過
PathLike
介面間接)。如果是 str,它將使用檔案系統編碼和錯誤處理程式進行編碼。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
。請注意,呼叫此函式不會呼叫為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
。使用引數
path
、args
、env
引發 審計事件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.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 呼叫(例如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.pidfd_open(pid, flags=0)¶
返回一個引用程序 pid 且設定了 flags 的檔案描述符。此描述符可用於無競爭和無訊號地執行程序管理。
有關更多詳細資訊,請參閱 pidfd_open(2) 手冊頁。
在 3.9 版本中新增。
可用性: Linux >= 5.10
3.12 新版功能.
- 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.Popen
或subprocess.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()
。位置引數 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
。os.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)
的方式相同)。使用引數
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 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 模組替換舊函式 部分。)如果 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 版本發生變更: 接受 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 的。如果您想使用絕對路徑,請確保第一個字元不是斜槓('/'
)。使用pathlib
或os.path.normpath()
函式以確保路徑正確編碼為 Win32。為了減少直譯器啟動開銷,Win32
ShellExecute()
函式直到首次呼叫此函式時才解析。如果函式無法解析,將引發NotImplementedError
。使用引數
path
、operation
引發 審計事件os.startfile
。使用引數
path
、operation
、arguments
、cwd
、show_cmd
引發 審計事件os.startfile/2
。可用性: 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 上,返回值是系統 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
- 自過去某個固定點以來經過的實際時間
為了向後相容,此物件也表現得像一個包含
user
、system
、children_user
、children_system
和elapsed
的五元組,按該順序排列。請參閱 Unix 手冊頁 times(2) 和 Unix 上的 times(3) 手冊頁,或 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 上,如果程序正在被跟蹤,或者
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.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.cpu_count()¶
返回系統中的邏輯 CPU 數量。如果無法確定,則返回
None
。可以使用
process_cpu_count()
函式獲取當前程序的呼叫執行緒可用的邏輯 CPU 數量。在 3.4 版本加入。
3.13 版本中的變化: 如果給定
-X cpu_count
或設定了PYTHON_CPU_COUNT
,則cpu_count()
返回被覆蓋的值 n。
- 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.sep¶
作業系統用於分隔路徑名元件的字元。POSIX 系統上為
'/'
,Windows 系統上為'\\'
。請注意,僅知道這一點不足以解析或連線路徑名 — 請使用os.path.split()
和os.path.join()
— 但它偶爾也很有用。也可透過os.path
訪問。
- os.altsep¶
作業系統用於分隔路徑名元件的備用字元,如果只有一個分隔符字元,則為
None
。在sep
為反斜槓的 Windows 系統上,此項設定為'/'
。也可透過os.path
訪問。
- os.linesep¶
當前平臺上用於分隔(或終止)行的字串。這可能是一個字元,如 POSIX 系統上的
'\n'
,也可能是多個字元,例如 Windows 系統上的'\r\n'
。在以文字模式(預設)寫入檔案時,請勿使用 os.linesep 作為行終止符;在所有平臺上都應使用單個'\n'
。
- 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_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 及更高版本上,現在使用 Cgetentropy()
函式。這些函式避免了內部檔案描述符的使用。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 版本加入。