.\" rtc.4 .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) .\" .\" %%%LICENSE_START(GPLv2+_DOC_FULL) .\" This is free documentation; you can redistribute it and/or .\" modify it under the terms of the GNU General Public License as .\" published by the Free Software Foundation; either version 2 of .\" the License, or (at your option) any later version. .\" .\" The GNU General Public License's references to "object code" .\" and "executables" are to be interpreted as the output of any .\" document formatting or typesetting system, including .\" intermediate and printed output. .\" .\" This manual is distributed in the hope that it will be useful, .\" but WITHOUT ANY WARRANTY; without even the implied warranty of .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the .\" GNU General Public License for more details. .\" .\" You should have received a copy of the GNU General Public .\" License along with this manual; if not, see .\" . .\" %%%LICENSE_END .\" .\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ .\" .\" 2006-02-08 Various additions by mtk .\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .\" .\" Japanese Version Copyright (c) 2006-2007 Yuichi SATO .\" all rights reserved. .\" Translated 2006-07-12 by Yuichi SATO . LDP v2.29 .\" Updated & Modified 2007-01-08 by Yuichi SATO. LDP v2.43 .\" .TH RTC 4 " 2017\-09\-15" Linux "Linux Programmer's Manual" .SH 名前 rtc \- リアルタイムクロック .SH 書式 #include .PP \fBint ioctl(\fP\fIfd\fP\fB, RTC_\fP\fIrequest\fP\fB, \fP\fIparam\fP\fB);\fP .SH 説明 これはリアルタイムクロック (RTC) のドライバのインターフェースである。 .PP 多くのコンピュータは、現在の「壁時計」時刻 ("wall clock" time) を記録する、 ハードウェアクロックを 1 個以上持っている。 これらは「リアルタイムクロック」(RTC) と呼ばれる。 これらの時計のうち 1 つは、通常は電池でバックアップして駆動されるので、 コンピュータのスイッチを切っても、時刻を保持できる。 多くの場合、RTC はアラームやその他の割り込みの機能を提供する。 .PP 全ての i386 PC と ACPI ベースのシステムには RTC がある。 この RTC は、元々の PC/AT に存在した Motorola MC146818 チップと互換性がある。 このような RTC は、今日ではマザーボードの チップセット (サウスブリッジ) 内で実装されていることが多く、 交換可能な硬貨くらいの大きさのバックアップ電池を使っている。 .PP システムオンチップ (system\-on\-chip) プロセッサを使って作られた 組み込みシステムといった、PC 以外のシステムでは、別な実装を用いている。 このようなシステムでは、PC/AT の RTC と同じ機能を提供していない場合が多い。 .SS "RTC とシステムクロックの違い" RTC をシステムクロックと混同すべきではない。 システムクロックは、カーネルに管理されるソフトウェアクロックであり、 ファイルによるタイムスタンプ設定などとともに、 \fBgettimeofday\fP(2) や \fBtime\fP(2) を実装するのに使用されている。 システムクロックは、POSIX における紀元 (Epoch; 1970\-01\-01 00:00:00 +0000 (UTC)) からの秒とミリ秒を表す。 1 つの一般的な実装ではタイマー割り込みを、"jiffy" 毎に 1 回、 100, 250, 1000 Hz という周波数でカウントする。 .PP RTC とシステムクロックの重要な違いは、 RTC はシステムが低電力状態 (「オフ」の場合も含む) でも動作するのに対し、 システムクロックは動作しない点である。 システムクロックは、初期化が行われるまでは、 POSIX 紀元からではなくシステムのブート時からの時刻しか返せない。 そのため、ブート時やシステムの低電力状態からの復帰 (resume) 後には、 システムクロックは RTC を使って現在の壁時計時刻に設定される場合が多い。 RTC を持たないシステムでは、 他の時計を使ってシステムクロックを設定する必要があり、 ネットワークにアクセスしたり、(時刻) データを手動で入力したりするだろう。 .SS "RTC の機能" RTC は \fBhwclock\fP(8) または下記の \fBioctl\fP(2) リクエストで読み書きができる。 .PP 日付と時間をカウントするのに加えて、 多くの RTC は以下のように割り込みを発生できる。 .IP * 3 クロックの更新毎 (つまり 1 秒毎)。 .IP * 2 Hz から 8192 Hz までの 2 の乗数の周波数で、定期的な間隔。 .IP * 前もって指定したアラーム時刻に達した時。 .PP これらの割り込み元は、個別に有効にしたり無効にしたりできる。 多くのシステムでは、アラーム割り込みをシステムの ウェイクアップイベントとして設定できる。 このイベントは、RAM へのサスペンド (STR, ACPI システムで S3 と呼ばれる) や ハイバーネーション (ACPI システムで S4 と呼ばれる) といった低電力状態や、 「オフ」(ACPI システムで S5 と呼ばれる) からでも、システムを復帰できる。 電池でバックアップされた RTC が割り込みを発生できるシステムと、 できないシステムがある。 .PP \fI/dev/rtc\fP (または \fI/dev/rtc0\fP, \fI/dev/rtc1\fP などの) デバイスは (クローズされるまで) 1 回しかオープンすることができず、 読み込み専用である。 \fBread\fP(2) と \fBselect\fP(2) を呼び出したプロセスは、 RTC からの割り込みを受け取るまで停止 (block) される。 割り込みの後、プロセスは long 型整数を読み出すことができる。 この整数の最下位バイトは発生した割り込みの種別を コード化したビットマスクであり、 残りの 3 バイトは最後の \fBread\fP(2) 以降に発生した割り込みの回数である。 .SS "ioctl(2) インターフェース" 以下の \fBioctl\fP(2) リクエストが RTC デバイスの接続された ファイルディスクリプターに対して定義されている: .TP \fBRTC_RD_TIME\fP RTC の時刻を以下の構造体で返す: .IP .in +4n .EX struct rtc_time { int tm_sec; int tm_min; int tm_hour; int tm_mday; int tm_mon; int tm_year; int tm_wday; /* 未使用 */ int tm_yday; /* 未使用 */ int tm_isdst; /* 未使用 */ }; .EE .in .IP この構造体のフィールドは \fBgmtime\fP(3) で説明されている \fItm\fP 構造体のフィールドと同じ意味で同じ範囲である。 この構造体へのポインターを \fBioctl\fP(2) の第 3 引数として渡す。 .TP \fBRTC_SET_TIME\fP \fBioctl\fP(2) の第 3 引数が指す \fIrtc_time\fP 構造体の値を RTC 時刻に設定する。 RTC 時刻の設定する場合、プロセスは特権 (つまり \fBCAP_SYS_TIME\fP ケーパビリティ) を持たなければならない。 .TP \fBRTC_ALM_READ\fP, \fBRTC_ALM_SET\fP アラームがサポートされている RTC に対して、 アラーム時刻の読み込みと設定を行う。 アラーム割り込みは、 \fBRTC_AIE_ON\fP, \fBRTC_AIE_OFF\fP を使って、これとは別に有効または無効にしなければならない。 \fBioctl\fP(2) の第 3 引数は、 \fIrtc_time\fP 構造体へのポインターでなければならない。 この構造体の \fItm_sec\fP, \fItm_min\fP, \fItm_hour\fP フィールドのみが使用される。 .TP \fBRTC_IRQP_READ\fP, \fBRTC_IRQP_SET\fP 周期的な割り込みがサポートされている RTC に対して、 周期的な割り込みの周波数の読み込みと設定を行う。 周期的な割り込みは、 \fBRTC_PIE_ON\fP, \fBRTC_PIE_OFF\fP を使って、これとは別に有効または無効にしなければならない。 \fBioctl\fP(2) の第 3 引数は、それぞれ \fIunsigned long\ *\fP と \fIunsigned long\fP である。 この値は 1 秒当たりの割り込みの回数である。 指定可能な周波数は、2 の乗数で 2 から 8192 の範囲である。 特権プロセス (つまり \fBCAP_SYS_RESOURCE\fP ケーパビリティを持つプロセス) のみが、 \fI/proc/sys/dev/rtc/max\-user\-freq\fP に書かれた上記の周波数を設定できる。 (このファイルにはデフォルトで 64 という値が書かれている)。 .TP \fBRTC_AIE_ON\fP, \fBRTC_AIE_OFF\fP アラームがサポートされている RTC に対して、 アラーム割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3 引数は無視される。 .TP \fBRTC_UIE_ON\fP, \fBRTC_UIE_OFF\fP 1 秒毎の割り込みがサポートされている RTC に対して、 クロック更新毎の割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3 引数は無視される。 .TP \fBRTC_PIE_ON\fP, \fBRTC_PIE_OFF\fP 周期的な割り込みがサポートされている RTC に対して、 周期的な割り込みを有効または無効にする。 \fBioctl\fP(2) の第 3 引数は無視される。 特権プロセス (つまり \fBCAP_SYS_RESOURCE\fP ケーパビリティを持つプロセス) のみが、 その時点で \fI/proc/sys/dev/rtc/max\-user\-freq\fP に周期が上記の値に指定されている場合に、 周期的な割り込みを有効にできる。 .TP \fBRTC_EPOCH_READ\fP, \fBRTC_EPOCH_SET\fP 多くの RTC は年を 8 ビットのレジスターにコード化する。 年は 8 ビットのバイナリ数または BCD 数に変換される。 どちらの場合でも、その数値は RTC の紀元から相対値に変換される。 多くのシステムでは RTC の紀元は 1900 に初期化されるが、 Alpha と MIPS では、RTC レジスターの年の値に応じて、 1952, 1980, 2000 の何れかに初期化される。 これらの操作でそれぞれ RTC の紀元の読み込みと設定が可能な RTC もある。 \fBioctl\fP(2) の第 3 引数は、それぞれ \fIunsigned long\ *\fP と \fIunsigned long\fP である。 返される値 (または指定される値) は紀元である。 RTC の紀元を設定する場合、プロセスは特権 (つまり \fBCAP_SYS_TIME\fP ケーパビリティ) を持たなければならない。 .TP \fBRTC_WKALM_RD\fP, \fBRTC_WKALM_SET\fP RTC の中にはより強力なアラームインターフェースをサポートするものもあり、 これらの ioctl を使うことで、以下のような構造体で RTC のアラーム時刻を (それぞれ) 読み書きできる: .PP .RS .in +4n .EX struct rtc_wkalrm { unsigned char enabled; unsigned char pending; struct rtc_time time; }; .EE .in .RE .IP \fIenabled\fP フラグはアラーム割り込みを有効または無効したり、 現在の状態を読み込むのに使用される。 これらのフラグを使う場合、 \fBRTC_AIE_ON\fP と \fBRTC_AIE_OFF\fP は使用されない。 \fIpending\fP フラグは \fBRTC_WKALM_RD\fP で使用され、処理待ちの割り込みを表示する (EFI ファームウェアで管理される RTC と通信するとき以外、 Linux ではほとんど役に立たない)。 \fItime\fP フィールドは \fBRTC_ALM_READ\fP や \fBRTC_ALM_SET\fP の場合と同じように使用されるが、 \fItm_mday\fP, \fItm_mon\fP, \fItm_year\fP フィールドも有効であるという点が異なる。 この構造体へのポインターを \fBioctl\fP(2) の第 3 引数として渡さなければならない。 .SH ファイル .TP \fI/dev/rtc\fP, \fI/dev/rtc0\fP, \fI/dev/rtc1\fP など。 RTC 特殊キャラクターデバイスファイル。 .TP \fI/proc/driver/rtc\fP (1 つ目の) RTC の状態 .SH 注意 カーネルのシステムクロックを \fBadjtimex\fP(2) を使って外部参照で同期させる場合、 \fBadjtimex\fP(2) は指定された RTC を 11 分毎に定期的に更新する。 これを行うためカーネルは周期的な割り込みを短期間無効にする必要がある。 これは RTC を使うプログラムに影響を与える。 .PP RTC の紀元は、システムクロックでのみ使用される POSIX の紀元とは何の関係もない。 .PP RTC の紀元と年のレジスターに基づく年が 1970 未満である場合、 100 年後、つまり 2000 から 2069 であると仮定される。 .PP RTC の中にはアラームフィールドに 「ワイルドカード」の値をサポートするものもあり、 毎時 15 分や各月の初日など、定期的なアラームを行うシナリオをサポートする。 このような使い方は移植性がない。 移植性の高いユーザー空間コードでは、単独のアラーム割り込みだけを想定し、 割り込みの受信後にアラームを無効または再初期化すべきである。 .PP 以下の機能をサポートする RTC もある。 1 秒の分数ではなく、1 秒の倍数を周期とする周期的な割り込み。 複数のアラーム。 プログラム可能な出力クロックシグナル。 不揮発性 (nonvolatile) メモリー。 この API で現在提供していない、その他のハードウェア機能。 .SH 関連項目 \fBdate\fP(1), \fBadjtimex\fP(2), \fBgettimeofday\fP(2), \fBsettimeofday\fP(2), \fBstime\fP(2), \fBtime\fP(2), \fBgmtime\fP(3), \fBtime\fP(7), \fBhwclock\fP(8) .PP Linux カーネルソース内の \fIDocumentation/rtc.txt\fP .SH この文書について この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は \%https://www.kernel.org/doc/man\-pages/ に書かれている。