`os` -- 基本的な「オペレーティングシステム」サービス¶

このモジュールは、該当する :term:`CPython` モジュールのサブセットを実装しています。詳しくはオリジナルの CPython ドキュメンテーションを参照してください: os.

os モジュールには、ファイルシステムのアクセス、マウント、ターミナルのリダイレクトと複製、uname と urandom のための関数があります。

一般関数¶

os.uname()¶

基盤のマシンやオペレーティングシステムに関する情報を含むタプル(おそらく名前付きタプル)を返します。タプルには次の5つのフィールドがあり、それぞれが文字列です。

sysname -- 基盤システムの名前

nodename -- ネットワーク名(sysname と同じこともあります)

release -- 基盤システムのバージョン

version -- MicroPython のバージョンとビルド日付

machine -- 基盤ハードウェアの識別子(ボード、CPUなど)

os.urandom(n)¶: n 個のランダムバイトを持つ bytes 型オブジェクトを返します。可能な限り、ハードウェア乱数生成器によって乱数を生成します。

ファイルシステムのアクセス¶

os.chdir(path)¶: カレントディレクトリを変更します。

os.getcwd()¶: カレントディレクトリのパスを返します。

os.ilistdir([dir])¶

この関数はイテレータを返します。イテレータが生成するのは、ディレクトリ内のエントリに対応するタプルです。引数なしの場合はカレントディレクトリを、それ以外の場合は dir で指定したディレクトリをリストします。

タプルの形式は (name, type, inode [, size]) です。

name は文字列(dir が bytes 型オブジェクトの場合は bytes 型オブジェクト)であり、エントリの名前です。

type はエントリのタイプを指定する整数で、ディレクトリの場合は 0x4000、通常のファイルの場合は 0x8000 です。

inode はファイルのiノードに対応する整数であり、そのような概念を持たないファイルシステムについては 0 になります。

一部のプラットフォームでは、エントリのサイズを含む4タプルが返されることがあります。ファイルエントリの場合、 size はファイルのサイズを表す整数で、未知の場合は -1 です。現在のところ、ディレクトリエントリについては未定義です。

os.listdir([dir])¶: 引数を指定しない場合は、カレントディレクトリ内のエントリを表示します。それ以外の場合は指定されたディレクトリ内のエントリを表示します。

os.mkdir(path)¶: 新規にディレクトリを作成します。

os.remove(path)¶: ファイルを削除します。

os.rmdir(path)¶: ディレクトリを削除します。

os.rename(old_path, new_path)¶: ファイルの名前を変更します。

os.stat(path)¶: ファイルまたはディレクトリのステータスを取得します。

os.statvfs(path)¶

ファイルシステムの状態を取得します。

次の順序でファイルシステム情報を含むタプルを返します。

f_bsize -- ファイルシステムのブロックサイズ

f_frsize -- フラグメントサイズ

f_blocks -- f_frsize 単位の fs のサイズ

f_bfree -- 空きブロックの数

f_bavail -- 権限なしユーザーのための空きブロック数

f_files -- iノード数

f_ffree -- フリーのiノードの数

f_favail -- 権限なしユーザの空きiノード数

f_flag -- マウントフラグ

f_namemax -- 最大ファイル名の長さ

iノードに関連するパラメータ f_files, f_ffree, f_avail, f_flags は、ポート固有の実装で使えない場合には 0 になります。

os.sync()¶: すべてのファイルシステムを同期します。

ターミナルのリダイレクトと複製¶

os.dupterm(stream_object, index=0, /)¶

与えた stream ライクなオブジェクトに MicroPython 端末(REPL)を複製または切り替えを行います。 stream_object の引数はネイティブストリームオブジェクトか、io.IOBase から派生して readinto() と write() メソッドを実装したものでなければなりません。ストリームは非ブロッキングモードで、 readinto() は読み込み可能なデータがない場合は None を返すようにします。

この関数を呼び出した後、すべての端末出力がこのストリーム上で繰り返され、ストリーム上で利用可能なすべての入力がターミナル入力に渡されます。

index パラメータは負でない整数であり、設定されている複製を指定します。ポートは２つ以上のスロットを実装できます(スロット 0 は常に使用可能です)。その場合、端末の入出力は設定されているすべてのスロットに複製されます。

stream_object に None を渡した場合、 index によって指定されたスロットで重複が取り消されます。

この関数は、指定したスロットの前のストリームオブジェクトを返します。

ファイルシステムのマウント¶

いくつかのポートは仮想ファイルシステム(VFS)を提供し、この VFS 内に複数の「実」ファイルシステムをマウントする機能を備えています。ファイルシステムオブジェクトは、VFS のルート、またはルートに存在するサブディレクトリにマウントできます。これにより、Python プログラムで見られるファイルシステムの動的で柔軟な設定が可能になります。この機能を持つポートは mount() と umount() 関数、そしておそらく VFS クラスで表されるさまざまなファイルシステムの実装を提供します。

os.mount(fsobj, mount_point, *, readonly)¶

ファイルシステムオブジェクト fsobj を mount_point 文字列で指定した VFS 内の場所にマウントします。 fsobj には mount() メソッドを持つ VFS オブジェクト、またはブロックデバイスを指定できます。ブロックデバイスであればファイルシステムタイプが自動的に検出されます(ファイルシステムが認識されない場合は例外が発生します)。 mount_point が '/' であれば fsobj をルートににマウントし、'/<name>' であればルート配下のサブディレクトリにマウントします。

readonly が True であればファイルシステムが読み取り専用でマウントされています。

マウント処理では、ファイルシステムオブジェクトに対してメソッド mount() 呼出します。

mount_point に既にマウントされていれば OSError(EPERM) 例外が発生します。

os.umount(mount_point)¶

ファイルシステムをアンマウントします。 mount_point には、マウント場所を指定する文字列、または以前にマウントされたファイルシステムオブジェクトを指定できます。アンマウント処理では、ファイルシステムオブジェクトに対してメソッド unmount() 呼出します。

"mount_point が見つからなければ OSError(EINVAL) 例外が発生します。

class os.VfsFat(block_dev)¶

FAT ファイルシステムのフォーマットを使うファイルシステムオブジェクトを作成します。FAT ファイルシステムのストレージは block_dev によって提供されます。このコンストラクタによって作成されたオブジェクトは mount() を使ってマウントできます。

static mkfs(block_dev)¶: block_dev に FAT ファイルシステムを構築します。

class os.VfsLfs1(block_dev, readsize=32, progsize=32, lookahead=32)¶

littlefs v1 filesystem format を使うファイルシステムオブジェクトを作成します。littlefs ファイルシステムのストレージは block_dev によって提供されます。 block_dev は extended interface をサポートしている必要があります。このコンストラクタによって作成されたオブジェクトは mount() を使ってマウントできます。

詳しくはファイルシステムの利用を参照してください。

static mkfs(block_dev, readsize=32, progsize=32, lookahead=32)¶: block_dev に Lfs1 ファイルシステムを構築します。

注釈

特定の状況で littlefs v1 が失敗するという報告があります。詳細については littlefs issue 347 を参照してください。

class os.VfsLfs2(block_dev, readsize=32, progsize=32, lookahead=32, mtime=True)¶

littlefs v2 filesystem format を使うファイルシステムオブジェクトを作成します。littlefs ファイルシステムのストレージは block_dev によって提供されます。 block_dev は extended interface をサポートしている必要があります。このコンストラクタによって作成されたオブジェクトは mount() を使ってマウントできます。

mtime 引数はファイルの更新タイムスタンプを有効にします。このオプションはマウント毎に有効/無効にでき、 mtime が有効な場合にのみタイムスタンプが追加/更新されます。 mtime が無効であれば、タイムスタンプが追加/更新されないままとなります。タイムスタンプのない Littlefs v2 ファイルシステムは、再フォーマットしなくても動作し、既存のファイルをオープンして書き込みを行うと、タイムスタンプは透過的に追加されます。 mtime が有効になっている場合、タイムスタンプのないファイルに対して os.stat を行った際のタイムスタンプの値は 0 になります。

詳しくはファイルシステムの利用を参照してください。

static mkfs(block_dev, readsize=32, progsize=32, lookahead=32)¶: block_dev に Lfs2 ファイルシステムを構築します。

注釈

特定の状況で littlefs v2 が失敗するという報告があります。詳細については littlefs issue 295 を参照してください。

ブロックデバイス¶

ブロックデバイスは、ブロックプロトコルを実装するオブジェクトです。これによりデバイスが MicroPython ファイルシステムをサポートできるようになります。物理ハードウェアはユーザー定義のクラスによって表されます。 AbstractBlockDev クラスはそのようなクラスを定義するためのテンプレートです。MicroPython が提供していないブロックデバイスクラスを自作する場合は後述のメソッドを実装する必要があります。

このクラスの具象サブクラスでは通常(フラッシュメモリのような)ハードウェアの一部にメモリのような機能へのアクセスが許可されます。ブロックデバイスはサポートされているファイルシステムでフォーマットでき、 os のメソッドを使ってマウントできます。

後述する２種類のブロックプロトコルを使ったブロックデバイスの実装例についてはファイルシステムの利用を参照してください。

シンプルインタフェースと拡張インタフェース¶

さまざまなユースケースをサポートするために、 readblocks や writeblocks メソッドには２つの互換性のあるシグネチャがあります(以下を参照)。与えられたブロックデバイスは、どちらか一方、または両方を実装しています。２番目の形式(offset 引数のあるもの)は「拡張インタフェース」といいます。

書き込み操作をより細かく制御する必要のある一部のファイルシステム(littlefs など)では、たとえば、消去せずにサブブロック領域に書き込む場合、ブロックデバイスが拡張インターフェイスをサポートしている必要がある場合があります。

class os.AbstractBlockDev(...)¶

ブロックデバイスオブジェクトを構築します。コンストラクタへのパラメータは、特定のブロックデバイスに依存します。

readblocks(block_num, buf)¶

readblocks(block_num, buf, offset)

最初の形式は、整列した複数のブロックを読み取ります。インデックス block_num で指定したブロックを開始点として、デバイスから buf (バイトの配列)にブロックを読み込みます。読み込むブロック数は buf の長さで与えられ、ブロックサイズの倍数になります。

２番目の形式では、ブロック内の任意の場所、任意の長さで読み取ることができます。ブロックインデックス block_num とブロック内のバイトオフセット offset を開始点として、デバイスから buf (バイトの配列)にブロックを読み込みます。読み込むブロック数は buf の長さで与えられ、読み込むバイト数になります。

writeblocks(block_num, buf)¶

writeblocks(block_num, buf, offset)

最初の形式は、整列した複数のブロックを書き込みます。書き込む前には、対象のブロックが（必要に応じて）消去されます。インデックス block_num で指定したブロックに buf (バイトの配列)からブロックを書き込みます。書き込むブロック数は buf の長さで与えられ、ブロックサイズの倍数になります。

２番目の形式では、ブロック内の任意の場所に、任意の長さで書き込むことができます。書き込むバイトのみを変更する必要があり、このメソッドの呼び出し元は、関連するブロックが事前の ioctl 呼び出しによって消去されることを保証する必要があります。ブロックインデックス block_num とそのブロック内のバイトオフセット offset を開始点として、 buf （バイト配列）からデバイスに書き込みます。書き込むバイト数は buf の長さで指定されます。

offset 引数が指定されている場合、たとえゼロであっても、実装がブロックを暗黙的に消去してはならないことに注意してください。

ioctl(op, arg)¶

ブロックデバイスの制御とパラメータ問い合わせをおこないます。実行する操作は op に次の整数のうちの１つで指定します。

1 -- デバイスを初期化します(arg は未使用)

2 -- デバイスをシャットダウンします(arg は未使用)

3 -- デバイスを同期します(arg は未使用)

4 -- ブロック数を取得し、整数で返します(arg は未使用)

5 -- ブロック内のバイト数を取得し、整数で返します。 None の場合はデフォルト値の 512 が使われます(arg は未使用)

6 -- ブロックを消去します。 arg は消去するブロック数です

少なくとも ioctl(4, ...) が受け付けられる必要があります。littlefs については ioctl(6, ...) も受け付けられる必要があります。その他の操作が受け付けられるかはハードウェアに依存します。

littlefs は writeblocks(block, ...) の呼び出しの前に ioctl(6, block) を発行します。これによりハードウェアが要求するなら、デバイスドライバは書き込みの前にブロックを消去できます。あるいは、ドライバが ioctl(6, block) を捉えて 0 (成功)を返すようにするかもしれません。この場合、ドライバは消去の必要性を検出する責任を負います。

特に記載のない限り ioctl(op, arg) は None を返します。したがって処理系は op の未使用値を無視できます。op が受け付けられる場合、操作 4 と 5 の戻り値は上記のとおりです。受け付けられる他の操作の戻り値は、成功した場合は 0 を返し、失敗した場合はゼロ以外を返します。失敗した場合の戻り値は OSError の errno コードです。

os -- 基本的な「オペレーティングシステム」サービス¶