[グダグダ] Linux の touch コマンドのマニュアルを読んでいく実況

※体系立ててわかりやすく解説することを意図した記事ではありません.

# 暫定のスコープを決める

趣味だし, 心ゆくまで `touch` コマンドについて理解したい. とは言っても `touch` コマンドに限らず, こういったコマンドは OS によって仕様が違う. ある 1 つの OS の `touch` コマンドを理解していない状態で複数の OS に手を出すと, 心ゆくまでを通り越してしまうので今回は GNU/Linux に限って理解することにする. 開発環境もプロダクション環境も Linux なことが多いため.

# 読むマニュアルを決める

`man touch` する日もあるが, 今日は HTML で読みたい気分なので [GNU Coreutils 9.0](https://www.gnu.org/software/coreutils/manual/html_node/index.html) > [13 Changing file attributes](https://www.gnu.org/software/coreutils/manual/html_node/Changing-file-attributes.html) > [13.4 touch: Change file timestamps](https://www.gnu.org/software/coreutils/manual/html_node/touch-invocation.html) を読むことにする.

# パソコン変えたばっかで Linux いなかった

ホストが macOS なのを言い忘れてたが, 読むのは Linux コマンドのマニュアルなのでホストの細かい環境は省略する. ゲストは Docker で適当に Ubuntu コンテナを立てればいいかなと思っている. Ubuntu のバージョンによって `touch` コマンドの仕様が変わるなどあまりないんじゃないかと思うし, さっさと読みたいし. @reflet さんの [Dockerのコンテナを起動したままにする](https://qiita.com/reflet/items/dd65f9ffef2a2fcfcf30) という記事を参考にコンテナを立てた. ありがとうございます :bow: 

```:Ubuntu の最新版をデタッチドで起動した. ※ターミナルのプロンプトは加工している(以下同じ).
$ docker run -itd ubuntu /bin/sh
Unable to find image 'ubuntu:latest' locally
latest: Pulling from library/ubuntu
185e8a4c1005: Pull complete 
Digest: sha256:9101220a875cee98b016668342c489ff0674f247f6ca20dfc91b91c0f28581ae
Status: Downloaded newer image for ubuntu:latest
fb7e4cf4c154d8f07c0064dba36dac688306746b7ba22d0347f47c822c5d0076
```

```:コンテナがちゃんと生きている.
$ docker ps
CONTAINER ID   IMAGE     COMMAND     CREATED         STATUS         PORTS     NAMES
fb7e4cf4c154   ubuntu    "/bin/sh"   2 minutes ago   Up 2 minutes             goofy_clarke
```

```:コンテナの中に入った. バージョン古いけどまあいいか.
$ docker exec -it fb7e4cf4c154 /bin/sh
# dpkg -s coreutils | grep Version
Version: 8.30-3ubuntu2
```

# 読んでいく

> `touch` changes the access and/or modification timestamps of the specified files.

ファイルたちには **access timestamp** と **modification timestamp** というメタデータ（？）がくっついていて `touch` はそれをいじれるのだろう.

> Synopsis: touch [*option*]… *file*…

は OK.

> Any *file* argument that does not exist is created empty, unless option `--no-create` (`-c`) or `--no-dereference` (`-h`) was in effect.

基本的にファイルなかったら作られる. `touch` って名前からして, 触ったよ！, っていう感じなのに, ファイルがなかったらできちゃうあたり, むむむ？って思い続けてる. `--no-create` は, 作るな！, だからファイルが作られないのはわかるんだけど, `--no-dereference` で対象のシンボリックリンクがなかったときにシンボリックリンクが作られないのはなんでだ？ `--no-dereference` の説明を読めば気持ちがわかるんだろうか. あ, シンボシックリンクがないからって作ろうとしても, リンクする先がわからないから作りようがないわけか.

> A *file* argument string of ‘`-`’ is handled specially and causes touch to change the times of the file associated with standard output.

“*file…*” のうちの少なくとも 1 つが `-` だったら何かが起こるということ？ “the times of the file associated with standard output” が意味するものがわからない. これは保留して記事最後の脚注に入れる. [^1]

> By default, `touch` sets file timestamps to the current time. Because `touch` acts on its operands left to right, the resulting timestamps of earlier and later operands may disagree. 

```PHP:たまに書く処理 (PHP)
// こうではなくて
$now = time();
foreach ($books as $book) {
    $book['updated_at'] = $now;
}

// こういうイメージなのだろう
foreach ($books as $book) {
    $book['updated_at'] = time();
}
```

> When setting file timestamps to the current time, `touch` can change the timestamps for files that the user does not own but has write permission for. Otherwise, the user must own the files. Some older systems have a further restriction: the user must own the files unless both the access and modification timestamps are being set to the current time.

ファイルを所有していれば書き込み権限いらないの面白いな. `chmod` とかも思い出すと, メタデータは書き込み権限なくても所有してれば変えられるぐらいの感覚でいいのか.

> The `touch` command cannot set a file’s status change timestamp to a user-specified value, and cannot change the file’s birth time (if supported) at all. Also, `touch` has issues similar to those affecting all programs that update file timestamps. For example, `touch` may set a file’s timestamp to a value that differs slightly from the requested time. See [File timestamps](https://www.gnu.org/software/coreutils/manual/html_node/File-timestamps.html).

ファイルたちには **access timestamp** と **modification timestamp** だけではなくて, **status change timestamp** や **birth time** といったメタデータ（？）もあるようだ. リンク追ってくと発散しちゃうから [File timestamps](https://www.gnu.org/software/coreutils/manual/html_node/File-timestamps.html) のリンクは保留する. [^2]

> Timestamps assume the time zone rules specified by the `TZ` environment variable, or by the system default rules if `TZ` is not set. See [Specifying the Time Zone with `TZ`](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html#TZ-Variable) in The GNU C Library Reference Manual. You can avoid ambiguities during daylight saving transitions by using UTC timestamps.

タイムスタンプの具体的な指定方法とかフォーマットについてはオプションについて読むときに理解することにしよう. “system default rules” ってどこ見ればいいんだ？　[Specifying the Time Zone with `TZ`](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html#TZ-Variable) のリンクは例によって保留する. [^3]

# ここからはオプションのドキュメント

> The program accepts the following options. Also see [Common options](https://www.gnu.org/software/coreutils/manual/html_node/Common-options.html).

[Common options](https://www.gnu.org/software/coreutils/manual/html_node/Common-options.html) のリンクは保留する. [^4]

> **‘`-a`’**
> **‘`--time=atime`’**
> **‘`--time=access`’**
> **‘`--time=use`’**
>     Change the access timestamp only. See File timestamps.

ここまででわかったのは `touch` コマンドは **atime** and/or **mtime** を変更するコマンドだということだ. atime も mtime も変更したくなかったら何もしなければいいので, 変更パターンとしては以下の 3 つとなる ↓

1. atime と mtime
1. atime だけ
1. mtime だけ

すぐ上で引用したオプションは 2 つ目のためのオプションだ.

唐突だが, 個人的には同じ 1 つのことをやるために似たような手段が複数あるのが好きではない. だが, 同じ 1 つのことをやるために似たような手段が複数あることメリット・デメリットを人と議論したことがないので, この考えはまだ独りよがりで危険だなと思う. また, メリット・デメリットとは別で, 似たような手段が複数存在する/残されるに至った理由/経緯も知らないといけないと思う. 

選択肢が複数あるとき, 自分はだいたい説明的なものを選ぶ. なんでもかんでも忘れてしまうので, `-a` とか書いてあると, タイムスタンプ全部帰るオプションだっけ, などと推測しかねないから `--time=` の方を使う. あと, ルールが整ってないと忘れてしまうので, 使う機会があれば `--time=atime` を使うと思う.

タイムスタンプの名前は **access** と **modification** なのに `--time=` に渡すときには **access** と **modify** になると言われても困ってしまう. **use** に関しては, どっから出てきたおまけなのかと思う. **atime** と **mtime** は **ctime** と並んで POSIX で使われる名称のようだし両方 `--time=` で使えるから `--time=atime` 一択だなあ.

> **‘`-c`’**
> **‘`--no-create`’**
> Do not warn about or create files that do not exist.

言っていることはわかった. だけど, 作成しないのがデフォルトで `--create` (`-c`) で作成できる, みたいにデフォルトは最小限でオプションでやることは増えていく方がわかりやすいんじゃないだろうか. `mkdir` の `--parents` (`-p`) はそういう考え方なんだろうと理解している. それと, なかったらエラーがデフォルトで `--silent` (`-s`) つけるとファイルなくてもよい, の方が静かな死が減りそう. だんだん文句が増えてきた. あ, `-c` じゃなくて `--no-create` 使いたい派である.

> **‘`-d time`’**
> **‘`--date=time`’**
> Use *time* instead of the current time. It can contain month names, time zones, ‘`am`’ and ‘`pm`’, ‘`yesterday`’, etc. For example, `--date="2020-07-21 14:19:13.489392193 +0530"` specifies the instant of time that is 489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC. See [Date input formats](https://www.gnu.org/software/coreutils/manual/html_node/Date-input-formats.html). File systems that do not support high-resolution timestamps silently ignore any excess precision here. [^5]

いろいろな自由な形式で日時を指定できるよ！楽しい！というか怖いので `--date=` に UNIX timestamp をくっつけるのが丸そう.

> **‘`-f`’**
> Ignored; for compatibility with BSD versions of `touch`.

無視.

> **‘`-h`’**
> **‘`--no-dereference`’**
> Attempt to change the timestamps of a symbolic link, rather than what the link refers to. When using this option, empty files are not created, but option `-c` must also be used to avoid warning about files that do not exist. Not all systems support changing the timestamps of symlinks, since underlying system support for this action was not required until POSIX 2008. Also, on some systems, the mere act of examining a symbolic link changes the access timestamp, such that only changes to the modification timestamp will persist long enough to be observable. When coupled with option `-r`, a reference timestamp is taken from a symbolic link rather than the file it refers to.

シンボリックリンクが存在しなかったらエラーになる. エラーにならないようにするには `--no-create` (`-c`) オプションのエラーを無視する機能を使う. ファイルがシンボリックリンクではなかったらどうなるんだろう.

シンボリックリンクが 2 つ以上つなげられるのだとすると, このオプションをつけない場合は末端のファイルのタイムスタンプだけ変更するのか, それとも指定したシンボリックが指すシンボリックリンクから全てタイムスタンプを変更するのか？

また, このオプションはタイムスタンプの変更対象として指定したシンボリックリンクに対してのみではなく `--reference=file` (`-r file`) でタイムスタンプを持ってくる元として指定したシンボリックリンクに対しても効果を持つ. これもファイルがシンボリックリンクではなかったらどうなるんだろう.

> **‘`-m`’**
> **‘`--time=mtime`’**
> **‘`--time=modify`’**
> Change the modification timestamp only.

自分は `--time=mtime` を使う.

> **‘`-r file`’**
> **‘`--reference=file`’**
> Use the times of the reference *file* instead of the current time. If this option is combined with the `--date=time` (`-d time`) option, the reference *file*’s time is the origin for any relative *times* given, but is otherwise ignored. For example, ‘`-r foo -d '-5 seconds'`’ specifies a timestamp equal to five seconds before the corresponding timestamp for `foo`. If *file* is a symbolic link, the reference timestamp is taken from the target of the symlink, unless `-h` was also in effect.

指定したファイルまたはシンボリックリンクが指すファイルのタイムスタンプを使用する. `--date=time` (`-d time`) オプションや `--no-dereference` (`-h`) オプションと組み合わせる使い方がある.

ふと思ったことがあって `touch` コマンドってこんなにオプションやその組み合わせが豊富だけどそもそも何に使うんだろう？使用頻度高いのかな？

> **‘`-t [[cc]yy]mmddhhmm[.ss]`’**
> Use the argument (optional four-digit or two-digit years, months, days, hours, minutes, optional seconds) instead of the current time. If the year is specified with only two digits, then cc is 20 for years in the range 0 … 68, and 19 for years in 69 … 99. If no digits of the year are specified, the argument is interpreted as a date in the current year. On the atypical systems that support leap seconds, ss may be ‘60’.

`--date=time` (`-d time`) とは別のタイムスタンプの指定方法. 絶対日時を指定するので `--reference=file` (`-r file`) と組み合わせる使い方がないのだと思われる.

> On systems predating POSIX 1003.1-2001, `touch` supports an obsolete syntax, as follows. If no timestamp is given with any of the `-d`, `-r`, or `-t` options, and if there are two or more *files* and the first *file* is of the form ‘`mmddhhmm[yy]`’ and this would be a valid argument to the `-t` option (if the *yy*, if any, were moved to the front), and if the represented year is in the range 1969–1999, that argument is interpreted as the time for the other files instead of as a file name. Although this obsolete behavior can be controlled with the `_POSIX2_VERSION` environment variable (see [Standards conformance](https://www.gnu.org/software/coreutils/manual/html_node/Standards-conformance.html)), portable scripts should avoid commands whose behavior depends on this variable. For example, use ‘`touch ./12312359 main.c`’ or ‘`touch -t 12312359 main.c`’ rather than the ambiguous ‘`touch 12312359 main.c`’. [^6]

はい, わかりました.

> An exit status of zero indicates success, and a nonzero value indicates failure.

は OK.

# 遊ぶ！遊ぶ！遊ぶ！

いろいろファイルやディレクトリやシンボリックリンク作って `touch` しまくって `ls` でタイムスタンプ見てなどなどやろうと思ってたんだけど, いつの間にか 4 時間も経ってて疲れたから公開して寝る.

[^1]: “A *file* argument string of ‘`-`’ is handled specially and causes touch to change the times of the file associated with standard output.”

[^2]: “The `touch` command cannot set a file’s status change timestamp to a user-specified value, and cannot change the file’s birth time (if supported) at all. Also, `touch` has issues similar to those affecting all programs that update file timestamps. For example, `touch` may set a file’s timestamp to a value that differs slightly from the requested time. See [File timestamps](https://www.gnu.org/software/coreutils/manual/html_node/File-timestamps.html).”

[^3]: “Timestamps assume the time zone rules specified by the `TZ` environment variable, or by the system default rules if `TZ` is not set. See [Specifying the Time Zone with `TZ`](https://www.gnu.org/software/libc/manual/html_node/TZ-Variable.html#TZ-Variable) in The GNU C Library Reference Manual. You can avoid ambiguities during daylight saving transitions by using UTC timestamps.”

[^4]: “The program accepts the following options. Also see [Common options](https://www.gnu.org/software/coreutils/manual/html_node/Common-options.html).”

[^5]: “Use *time* instead of the current time. It can contain month names, time zones, ‘`am`’ and ‘`pm`’, ‘`yesterday`’, etc. For example, `--date="2020-07-21 14:19:13.489392193 +0530"` specifies the instant of time that is 489,392,193 nanoseconds after July 21, 2020 at 2:19:13 PM in a time zone that is 5 hours and 30 minutes east of UTC. See [Date input formats](https://www.gnu.org/software/coreutils/manual/html_node/Date-input-formats.html). File systems that do not support high-resolution timestamps silently ignore any excess precision here.”

[^6]: On systems predating POSIX 1003.1-2001, `touch` supports an obsolete syntax, as follows. If no timestamp is given with any of the `-d`, `-r`, or `-t` options, and if there are two or more *files* and the first *file* is of the form ‘`mmddhhmm[yy]`’ and this would be a valid argument to the `-t` option (if the *yy*, if any, were moved to the front), and if the represented year is in the range 1969–1999, that argument is interpreted as the time for the other files instead of as a file name. Although this obsolete behavior can be controlled with the `_POSIX2_VERSION` environment variable (see [Standards conformance](https://www.gnu.org/software/coreutils/manual/html_node/Standards-conformance.html)), portable scripts should avoid commands whose behavior depends on this variable. For example, use ‘`touch ./12312359 main.c`’ or ‘`touch -t 12312359 main.c`’ rather than the ambiguous ‘`touch 12312359 main.c`’.