Code Reading：Redox(Rust)版coreutilsのcatコマンド その2(全2回)

前書き

Rustを学習するための一環として、Redox(OS)版coreutilsのcatコマンドをCode Readingします。本記事(その2)は、catコマンドの主要な処理(ファイル内容の表示)を説明します。catコマンドのオプションパース処理に関する内容は、以下に示す前回記事(その1)を確認して下さい。

• Code Reading：Redox(Rust)版coreutilsのcatコマンド その1(全2回)

Reading対象のコード

本記事では、catコマンドの関数and_execute(以下のコード)を読んだ結果を説明します。関連するコードは、解説のタイミングで適宜示します。全文を確認する場合、Redox版coreutilsの公式リポジトリを参照して下さい。

struct Program {
    exit_status:      Cell,
    number:           bool,
    number_nonblank:  bool,
    show_ends:        bool,
    show_tabs:        bool,
    show_nonprinting: bool,
    squeeze_blank:    bool,
    paths:            Vec,
}

impl Program {
    // 省略

    /// Execute the parameters given to the program.
    fn and_execute(&self, stdout: &mut StdoutLock, stderr: &mut Stderr) -> i32 {
        let stdin = io::stdin();
        let line_count = &mut 0usize;
        let flags_enabled = self.number || self.number_nonblank || self.show_ends || self.show_tabs ||
                            self.squeeze_blank || self.show_nonprinting;

        if self.paths.is_empty() && flags_enabled {
            self.cat(&mut stdin.lock(), line_count, stdout, stderr);
        } else if self.paths.is_empty() {
            self.simple_cat(&mut stdin.lock(), stdout, stderr);
        } else {
            for path in &self.paths {
                if flags_enabled && path == "-" {
                    self.cat(&mut stdin.lock(), line_count, stdout, stderr);
                } else if path == "-" {
                    // Copy the standard input directly to the standard output.
                    self.simple_cat(&mut stdin.lock(), stdout, stderr);
                } else if fs::metadata(&path).map(|m| m.is_dir()).unwrap_or(false) {
                    stderr.write(path.as_bytes()).try(stderr);
                    stderr.write(b": Is a directory\n").try(stderr);
                    stderr.flush().try(stderr);
                    self.exit_status.set(1i32);
                } else if flags_enabled {
                    fs::File::open(&path)
                        // Open the file and copy the file's contents to standard output based input arguments.
                        .map(|file| self.cat(&mut BufReader::new(file), line_count, stdout, stderr))
                        // If an error occurred, print the error and set the exit status.
                        .unwrap_or_else(|message| {
                            stderr.write(path.as_bytes()).try(stderr);
                            stderr.write(b": ").try(stderr);
                            stderr.write(message.description().as_bytes()).try(stderr);
                            stderr.write(b"\n").try(stderr);
                            stderr.flush().try(stderr);
                            self.exit_status.set(1i32);
                        });
                } else {
                    // Open a file and copy the contents directly to standard output.
                    fs::File::open(&path).map(|ref mut file| { self.simple_cat(file, stdout, stderr); })
                        // If an error occurs, print the error and set the exit status.
                        .unwrap_or_else(|message| {
                            stderr.write(path.as_bytes()).try(stderr);
                            stderr.write(b": ").try(stderr);
                            stderr.write(message.description().as_bytes()).try(stderr);
                            stderr.write(b"\n").try(stderr);
                            stderr.flush().try(stderr);
                            self.exit_status.set(1i32);
                        });
                }
            }
        }
        self.exit_status.get()
    }

    /// A simple cat that runs a lot faster than self.cat() due to no iterators over single bytes.
    fn simple_cat(&self, file: &mut F, stdout: &mut StdoutLock, stderr: &mut Stderr) {
        let mut buf: [u8; 8*8192] = [0; 8*8192]; // 64K seems to be the sweet spot for a buffer on my machine.
        loop {
            let n_read = file.read(&mut buf).try(stderr);
            if n_read == 0 { // We've reached the end of the input
                break;
            }
            stdout.write_all(&buf[..n_read]).try(stderr);
        }
    }

    /// Cats either a file or stdin based on the flag arguments given to the program.
    fn cat(&self, file: &mut F, line_count: &mut usize, stdout: &mut StdoutLock, stderr: &mut Stderr) {
        let mut character_count = 0;
        let mut last_line_was_blank = false;
        let mut buf: [u8; 8*8192] = [0; 8*8192]; // 64K seems to be the sweet spot for a buffer on my machine.
        let mut out_buf: Vec = Vec::with_capacity(24*8192); // Worst case 2 chars out per char
        loop {
            let n_read = file.read(&mut buf).try(stderr);
            if n_read == 0 { // We've reached the end of the input
                break;
            }

            for &byte in buf[0..n_read].iter() {
                if character_count == 0 && (self.number || (self.number_nonblank && byte != b'\n')) {
                    out_buf.write(b"     ").try(stderr);
                    out_buf.write(line_count.to_string().as_bytes()).try(stderr);
                    out_buf.write(b"  ").try(stderr);
                    *line_count += 1;
                }
                match byte {
                    0...8 | 11...31 => if self.show_nonprinting {
                        push_caret(&mut out_buf, stderr, byte+64);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                    9 => {
                        if self.show_tabs {
                            push_caret(&mut out_buf, stderr, b'I');
                        } else {
                            out_buf.write(&[byte]).try(stderr);
                        }
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    }
                    10 => {
                        if character_count == 0 {
                            if self.squeeze_blank && last_line_was_blank {
                                continue
                            } else if !last_line_was_blank {
                                last_line_was_blank = true;
                            }
                        } else {
                            last_line_was_blank = false;
                            character_count = 0;
                        }
                        if self.show_ends {
                            out_buf.write(b"$\n").try(stderr);
                        } else {
                            out_buf.write(b"\n").try(stderr);
                        }
                    },
                    32...126 => {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                    127 => if self.show_nonprinting {
                        push_caret(&mut out_buf, stderr, b'?');
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                    128...159 => if self.show_nonprinting {
                        out_buf.write(b"M-^").try(stderr);
                        out_buf.write(&[byte-64]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    } else {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                    _ => if self.show_nonprinting {
                        out_buf.write(b"M-").try(stderr);
                        out_buf.write(&[byte-128]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    } else {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                }
            }
            stdout.write_all(&out_buf).try(stderr);
            out_buf.clear();
        }
    }

　// 省略
}

上記のコードで、構造体Programが持つメンバの意味合い(用途)は、下表の通りです。

catコマンドの関数and_execute()は、大別して以下の3つの処理に分岐します。本記事では、これらの分岐処理に関して説明します。

and_execute()処理：3種類の分岐

• 「引数でファイルPATHを指定しない」かつ「オプションを指定した」場合
• 引数でファイルPATHおよびオプションを指定しない場合
• 引数でファイルPATHを指定した場合

「引数でファイルPATHを指定しない」かつ「オプションを指定した」場合

本ケースは、ファイルPATHが指定されていないため、ユーザからの標準入力を標準出力に返します。さらに、オプションを解釈します。以下に、catコマンドをnオプション(行番号表示)のみで実行した例を示します。

$ ./target/debug/cat -n
この文章はテストです。
     0  この文章はテストです。
標準入力の内容を標準出力に表示します。
     1  標準入力の内容を標準出力に表示します。
今回は、行番号を表示するオプション="n"を付与しています。
     2  今回は、行番号を表示するオプション="n"を付与しています。
そのため、標準出力に行番号も付いています。
     3  そのため、標準出力に行番号も付いています。

本ケースに該当するコードおよび各変数の意味合いを以下に示します。

• 変数stdinは、標準入力へのハンドラ
• 変数line_countは、行番号の格納用
• 変数flags_enabledは、ユーザがオプションを付与して実行したかを管理するフラグ

     fn and_execute(&self, stdout: &mut StdoutLock, stderr: &mut Stderr) -> i32 {
        let stdin = io::stdin();
        let line_count = &mut 0usize;
        let flags_enabled = self.number || self.number_nonblank || self.show_ends || self.show_tabs ||
                            self.squeeze_blank || self.show_nonprinting;

        if self.paths.is_empty() && flags_enabled {
            self.cat(&mut stdin.lock(), line_count, stdout, stderr);
        } 
        // 以下、省略
    }

最初のif文を抜けると、関数self.cat()を呼び出します。この関数cat()では、以下の3点を実施します。

1. 標準入力(もしくはファイル)から文字を読込
2. 1Byteずつオプション処理しつつ、1.で読み込んだデータを全て一時バッファに書込
3. 一時バッファを標準出力に書き込み

一時バッファ経由で標準出力に書き込む理由は、I/O速度を向上させるためです。Rust は、アクセス競合を起こさないように、非バッファI/Oを採用しています。非バッファI/Oは、処理が遅いです。遅い理由は、Read/Writeの度にLock/Unlock処理を繰り返す事、およびシステムコール使用回数がバッファを利用している時用も増えてしまう事が挙げられます(参考)。

[the_ad id=“598”]

では、上述の1.〜3.の処理を順に説明します。

標準入力から文字を読み込む処理

以下に、該当部分のコードおよび変数の意味合いを示します。

• 変数character_countは、文字数
• 変数last_line_was_blankは、最終行が空行だったかを示すフラグ
• 変数bufは、標準入力から読み込んだデータを保持するバッファ(「実装者の環境では64KBが最適だった」とコメントがあります)
• 変数out_bufは、標準出力へ書き込むデータの一時バッファ(192KB。オプションによっては、入力1文字に対して2文字追記するケース、つまり出力が3文字になるケースがあるため、このサイズにしています)

    /// Cats either a file or stdin based on the flag arguments given to the program.
    fn cat(&self, file: &mut F, line_count: &mut usize, stdout: &mut StdoutLock, stderr: &mut Stderr) {
        let mut character_count = 0;
        let mut last_line_was_blank = false;
        let mut buf: [u8; 8*8192] = [0; 8*8192]; // 64K seems to be the sweet spot for a buffer on my machine.
        let mut out_buf: Vec = Vec::with_capacity(24*8192); // Worst case 2 chars out per char
        loop {
            let n_read = file.read(&mut buf).try(stderr);
            if n_read == 0 { // We've reached the end of the input
                break;
            }
        /* 省略 */

ループの頭では、関数file.read()によって、標準入力(もしくはファイル)の内容を変数bufに代入しています。戻り値n_readは、読み込んだ文字数を表します。そのため、読み込んだ文字数が0の場合は、ファイルの終端に達したと判断し、ループを抜けます。

今回は、標準入力の例なので、このif文内の処理(break)を実行する事はありません。

1Byteずつオプション処理しつつ、読み込んだデータを全て一時バッファに書込

前提として、Rustの文字コードはUTF-8です。UTF-8は、半角英数字(一部記号含む)のみ、ASCIIと同じ体系になっています。具体的には、下表に示す「数字(0〜160)」と「文字(記号)」との組み合わせがASCIIと同じです。

表中の赤字部分は、catコマンドのオプションによって、別文字に置換される文字です。

以上の文字コード(UTF-8)の情報を踏まえて、catコマンドのByte処理を説明します。まず、読み込んだデータに対して、行番号を付与します。具体的には、一文字も読み込んでなく、「number(n)オプションが有効の場合」か「“nunber-noblank(b)オプション(空白行を除いて行番号を付与)“かつ"入力文字が改行ではない場合”」に、行番号を付与します。

        // 省略
        loop {
            for &byte in buf[0..n_read].iter() {
                if character_count == 0 && (self.number || (self.number_nonblank && byte != b'\n')) {
                    out_buf.write(b"     ").try(stderr);
                    out_buf.write(line_count.to_string().as_bytes()).try(stderr);
                    out_buf.write(b"  ").try(stderr);
                    *line_count += 1;
                }
               // 省略

(注釈)：number-nonblankオプションを有効にした実行例
$ cat -b
test
     0  test
                               (注釈)：この行は何も入力しないで、Enter

空行は行番号がつかない
     1  空行は行番号がつかない

次に、1Byteで表現された文字の処理です。実装順に説明します。

以下のコードは、非表示文字(0〜31)に対する処理です。show-nonprintingオプションが有効の場合、キャレット記法(表示できない文字を特定の文字列で表示する方法)で表します。キャレット記法では、"^“と"非表示文字(0〜31)に64を加算した数値に対応する英字・記号"によって、非表示文字を表します。

例えば、非表示文字であるNUL(0)の場合、"^“と”@(64)“を合わせた”^@“で表します。以上を踏まえてコードを確認すると、以下の処理はキャレット記法で文字を一時バッファに書き込み、その後に文字数をカウント(保持)しているだけと分かります。

           match byte {
                 0...8 | 11...31 => if self.show_nonprinting {
                        push_caret(&mut out_buf, stderr, byte+64);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },

/// Print a caret notation to stdout.
fn push_caret(stdout: &mut T, stderr: &mut Stderr, notation: u8) {
    stdout.write(&[b'^']).try(stderr);
    stdout.write(&[notation]).try(stderr);
}

次の処理(以下のコード)は、show-tabsオプションが有効の場合、TAB(9)をキャレット記法で一時バッファに書き込みます。TABの場合は、直接”I(9+64=73)”を渡しています。show-tabsオプションが無効の場合、Byteをそのまま一時バッファに書き込みます。その後、文字数をカウント(保持)します。

                    9 => {
                        if self.show_tabs {
                            push_caret(&mut out_buf, stderr, b'I');
                        } else {
                            out_buf.write(&[byte]).try(stderr);
                        }
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    }

次の処理(以下のコード)は、改行LF(10)の処理で、主に2つのオプションを処理しています。

• 文字数が0の場合、squeeze-blankオプション(連続した空行を1行に変更)を実施
• show-endsオプション(行の最後に”$”を表示)の実施

1つ目の処理は、文字数が0でこの処理を初めて通った場合、最終行が空行だった事を変数last_line_was_blankフラグに保持(=trueに変更)します。文字数が0でlast_line_was_blankフラグ有効(この処理を通るのが2回目以降)の場合、ループの先頭に戻る事で空行を増やしません。文字数が1以上の場合、後ほど改行処理が入るため、「最終行が空行フラグ」および「文字数」をリセットし、次のループ処理に備えます。

2つ目の処理は、一時バッファに書き込む内容を分けています。

• show-endsオプションが有効の場合、"$“と改行(”\n”)を書込
• show-endsオプションが無効の場合、改行(”\n”)のみを書込

                  10 => {
                        if character_count == 0 {
                            if self.squeeze_blank && last_line_was_blank {
                                continue
                            } else if !last_line_was_blank {
                                last_line_was_blank = true;
                            }
                        } else {
                            last_line_was_blank = false;
                            character_count = 0;
                        }
                        if self.show_ends {
                            out_buf.write(b"$\n").try(stderr);
                        } else {
                            out_buf.write(b"\n").try(stderr);
                        }
                    },

次の処理(以下のコード)は、英数字・一部の記号を表示する処理です。オプション処理が不要なため、そのまま一時バッファに書き込み、文字数をカウントします。

                 32...126 => {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },

次の処理(以下のコード)は、「非表示文字(0〜31)をキャレット記法で表示した処理」と同等の内容を非表示文字(127〜159)に対して実施します。show-nonprintingオプションが有効の場合、非表示文字を可視化します。無効の場合、そのまま一時バッファに書き込みます。どちらの場合も、文字数をカウントします。

DEL(127)のみキャレット記法で表示し、他の非表示文字(128〜159)は"M-^“および"非表示文字から64を減算した数値に対応する英字・記号"で表示します。例えば、PAD(128)の場合、“M-^“と”@(64)“を合わせた"M-^@“で表します。

                   127 => if self.show_nonprinting {
                        push_caret(&mut out_buf, stderr, b'?');
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },
                   128...159 => if self.show_nonprinting {
                        out_buf.write(b"M-^").try(stderr);
                        out_buf.write(&[byte-64]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    } else {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },

次の処理(以下のコード)は、0〜159以外の数値に変換される文字を処理します。この処理も他の非表示文字に対する処理に似た対応をします。具体的には、該当の文字(!=0〜159)は、“M-“および"非表示文字から128を減算した数値に対応する英字・記号"で表示します。変換した文字を一時バッファに書き込み、文字数をカウントします。

                    _ => if self.show_nonprinting {
                        out_buf.write(b"M-").try(stderr);
                        out_buf.write(&[byte-128]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    } else {
                        out_buf.write(&[byte]).try(stderr);
                        count_character(&mut character_count, &self.number, &self.number_nonblank);
                    },

一時バッファを標準出力に書込

この処理(以下のコード)は、単純です。この処理に達している場合、標準出力から読み込んだデータ全てが一時バッファに書き込まれた状態です。その一時バッファ内容を標準出力に書き込みます。その後、もう一度標準入力の内容を読み込むループの先頭に戻るため、一時バッファをクリアします。

            stdout.write_all(&out_buf).try(stderr);
            out_buf.clear();

引数でファイルPATHおよびオプションを指定しない場合

本ケースは、ファイルPATHおよびオプションが指定されていないため、単純にユーザからの標準入力を標準出力に返します。以下に、本ケースでcatコマンドを実行した例を示します。

$ cat
この文章はテストです
この文章はテストです
オプションがないため、入力内容をそのまま表示します
オプションがないため、入力内容をそのまま表示します

本ケースでは、関数simple_cat()が呼ばれます。関数simple_catは、関数cat()からオプション対応を無くしただけです。以下の処理を実施しています。

• 標準入力(もしくはファイル内容)を読み込むためのバッファ確保(64KB)
• バッファに標準入力(もしくはファイル内容)の内容を読込
• バッファの内容を標準出力に書込

    /// Execute the parameters given to the program.
    fn and_execute(&self, stdout: &mut StdoutLock, stderr: &mut Stderr) -> i32 {
         /* 省略 */
        } else if self.paths.is_empty() {
            self.simple_cat(&mut stdin.lock(), stdout, stderr);
        } 
        /* 省略 */
    }

    /// A simple cat that runs a lot faster than self.cat() due to no iterators over single bytes.
    fn simple_cat(&self, file: &mut F, stdout: &mut StdoutLock, stderr: &mut Stderr) {
        let mut buf: [u8; 8*8192] = [0; 8*8192]; // 64K seems to be the sweet spot for a buffer on my machine.
        loop {
            let n_read = file.read(&mut buf).try(stderr);
            if n_read == 0 { // We've reached the end of the input
                break;
            }
            stdout.write_all(&buf[..n_read]).try(stderr);
        }
    }

引数でファイルPATHを指定した場合

本ケース(以下のコード)では、渡されたPATHの数だけループを繰り返し、以下の5通りで分岐処理します。分岐1.と分岐2.は、説明済みの内容のため、省略します。

1. 「オプション有効」かつ「PATH=”-"(標準入力と同等)」の場合、関数cat()を実行
2. 「オプション無効」かつ「PATH=”-"(標準入力と同等)」の場合、関数simple_cat()を実行
3. PATHがDirectoryの場合、エラーメッセージを表示し、終了(後述)
4. 「オプション有効」かつ「PATH=File」の場合、関数cat()を実行(後述)
5. 「オプション無効」かつ「PATH=File」の場合、関数simple_cat()を実行(後述)

    /// Execute the parameters given to the program.
    fn and_execute(&self, stdout: &mut StdoutLock, stderr: &mut Stderr) -> i32 {
       // 省略

        } else {
            for path in &self.paths {
                if flags_enabled && path == "-" {
                    self.cat(&mut stdin.lock(), line_count, stdout, stderr);
                } else if path == "-" {
                    // Copy the standard input directly to the standard output.
                    self.simple_cat(&mut stdin.lock(), stdout, stderr);
                } else if fs::metadata(&path).map(|m| m.is_dir()).unwrap_or(false) {
                    stderr.write(path.as_bytes()).try(stderr);
                    stderr.write(b": Is a directory\n").try(stderr);
                    stderr.flush().try(stderr);
                    self.exit_status.set(1i32);
                } else if flags_enabled {
                    fs::File::open(&path)
                        // Open the file and copy the file's contents to standard output based input arguments.
                        .map(|file| self.cat(&mut BufReader::new(file), line_count, stdout, stderr))
                        // If an error occurred, print the error and set the exit status.
                        .unwrap_or_else(|message| {
                            stderr.write(path.as_bytes()).try(stderr);
                            stderr.write(b": ").try(stderr);
                            stderr.write(message.description().as_bytes()).try(stderr);
                            stderr.write(b"\n").try(stderr);
                            stderr.flush().try(stderr);
                            self.exit_status.set(1i32);
                        });
                } else {
                    // Open a file and copy the contents directly to standard output.
                    fs::File::open(&path).map(|ref mut file| { self.simple_cat(file, stdout, stderr); })
                        // If an error occurs, print the error and set the exit status.
                        .unwrap_or_else(|message| {
                            stderr.write(path.as_bytes()).try(stderr);
                            stderr.write(b": ").try(stderr);
                            stderr.write(message.description().as_bytes()).try(stderr);
                            stderr.write(b"\n").try(stderr);
                            stderr.flush().try(stderr);
                            self.exit_status.set(1i32);
                        });
                }
            }
        }
        self.exit_status.get()
    }

まず、分岐3.「 PATHがディレクトリの場合」を説明します。PATHがディレクトリかどうかを判断するために、fs::metadata(&path)を用います。fs::metadata()は、引数にPATHを渡して、filesystemに問い合わせて、PATHがFileかDirctoryかなどに関するメタ情報を取得します。具体的には、std::fs::Metadata構造体を返します。

fs::metadata()は、シンボリックリンクの場合はリンク元まで辿ります。エラーとなるケースは、主に2つです。

• PATHにFileやDirectoryが存在しない場合
• アクセス権限がない場合

fs::metadata(&path)に続くmap(|m| m.is_dir())は、クロージャであり、Metadata構造体の関数であるis_dir()を用いて、Directoryかどうかの判定をしています。以上の処理でエラーが発生した場合、以下のエラーを出します。

$ cat $(pwd)          (注釈)：引数はカレントワーキングディレクトリ
/home/nao/RUST2/coreutils: Is a directory

次に、分岐4.「オプション有効かつPATH=Fileの場合」を説明します。関数cat()に渡せる形式にPATHを変換するために、fs::File::open(&path)を実行します。エラーハンドリングに用いられているunwrap_or_else()は、関数cat()が成功した場合は成功値を返し、失敗した場合はクロージャ(message)を呼び出します。また、std::error::Errorに用いられるdescription()は、非推奨になりつつある関数で、Errorトレイトに定義済みのエラーメッセージを表示します。エラーメッセージのサンプルを示します。

PATH: "この部分に、エラーに応じたメッセージが出力されます"

最後に、分岐5. 「オプション無効かつPATH=Fileの場合」を説明します。オプション有効時と同様に、関数simple_cat()に渡せる形式にPATHを変換するために、fs::File::open(&path)を実行します。オプション有効時と無効時の差異は、有効時は速度向上を目的としてBufReaderの参照を関数cat()に渡しますが、無効時は文字列加工をしないのでfileへのミュータブル参照をそのまま関数simple_cat()に渡します。エラーハンドリングは、オプション有効時と同じです。

最後に

Redox版coreutils(Rust版coreutils)のCode Readingは、catコマンドだけでなく、他のコマンドに対しても実施しています。興味があれば、以下の記事から参照できます。

• 環境構築：Redox向けcoreutils(Rust)のCode Reading準備およびReading対象コマンド一覧