← Back to branch summary

~ubuntu-branches/ubuntu/trusty/util-linux/trusty-proposed

« back to all changes in this revision

Viewing changes to hwclock/hwclock.8

  • Committer: Package Import Robot
  • Author(s): LaMont Jones
  • Date: 2011-11-03 15:38:23 UTC
  • mto: (4.5.5 sid) (1.6.4)
  • mto: This revision was merged to the branch mainline in revision 85.
  • Revision ID: package-import@ubuntu.com-20111103153823-10sx16jprzxlhkqf
Import upstream version 2.20.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
hwclock/hwclock.8
1
 
.TH HWCLOCK 8 "06 August 2008"
 
1
.TH HWCLOCK 8 "August 2011" "util-linux" "System Administration"
2
2
.SH NAME
3
 
hwclock \- query and set the hardware clock (RTC)
 
3
hwclock \- query or set the hardware clock (RTC)
4
4
.SH SYNOPSIS
5
5
.B hwclock
6
 
.RI [ functions ]
7
 
.RI [ options ]
 
6
.RI [ function ]
 
7
.RI [ option ...]
8
8
 
9
9
.SH DESCRIPTION
10
10
.B hwclock
11
11
is a tool for accessing the Hardware Clock.  You can display the
12
12
current time, set the Hardware Clock to a specified time, set the
13
 
Hardware Clock to the System Time, and set the System Time from the
 
13
Hardware Clock from the System Time, or set the System Time from the
14
14
Hardware Clock.
15
15
.PP
16
16
You can also run
17
17
.B hwclock
18
 
periodically to insert or remove time from the Hardware Clock to
19
 
compensate for systematic drift (where the clock consistently gains or
20
 
loses time at a certain rate if left to run).
 
18
periodically to add or subtract time from the Hardware Clock to
 
19
compensate for systematic drift (where the clock consistently loses or
 
20
gains time at a certain rate when left to run).
21
21
 
22
22
.SH FUNCTIONS
23
23
You need exactly one of the following options to tell
26
26
.PP
27
27
.TP
28
28
.BR \-r , \ \-\-show
29
 
Read the Hardware Clock and print the time on Standard Output.
 
29
Read the Hardware Clock and print the time on standard output.
30
30
The time shown is always in local time, even if you keep your Hardware Clock
31
31
in Coordinated Universal Time.  See the
32
32
.B \-\-utc
33
33
option.
 
34
Showing the Hardware Clock time is the default when no function is specified.
34
35
 
35
36
.TP
36
37
.B \-\-set
48
49
.BR tzset (3)
49
50
would interpret them.
50
51
The obsolete tz_dsttime field of the kernel's timezone value is set
51
 
to DST_NONE. (For details on what this field used to mean, see
 
52
to DST_NONE.  (For details on what this field used to mean, see
52
53
.BR settimeofday (2).)
53
54
 
54
55
This is a good option to use in one of the system startup scripts.
66
67
.BR tzset (3)
67
68
would interpret them.
68
69
The obsolete tz_dsttime field of the kernel's timezone value is set
69
 
to DST_NONE. (For details on what this field used to mean, see
 
70
to DST_NONE.  (For details on what this field used to mean, see
70
71
.BR settimeofday (2).)
71
72
 
72
73
This is an alternate option to
85
86
This is the number of years into AD to which a zero year value in the
86
87
Hardware Clock refers.  For example, if you are using the convention
87
88
that the year counter in your Hardware Clock contains the number of
88
 
full years since 1952, then the kernel's Hardware Counter epoch value
 
89
full years since 1952, then the kernel's Hardware Clock epoch value
89
90
must be 1952.
90
91
 
91
 
This epoch value is used whenever hwclock reads or sets the Hardware Clock.
 
92
This epoch value is used whenever
 
93
.B hwclock
 
94
reads or sets the Hardware Clock.
92
95
.TP
93
96
.B \-\-setepoch
94
97
Set the kernel's Hardware Clock epoch value to the value specified by the
96
99
option.  See the
97
100
.B \-\-getepoch
98
101
option for details.
99
 
.TP
100
 
.BR \-v , \ \-\-version
101
 
Print the version of
 
102
 
 
103
.TP
 
104
.BI \-\-predict
 
105
Predict what the RTC will read at time given by the
 
106
.B \-\-date
 
107
option based on the adjtime file. This is useful for example if you
 
108
need to set an RTC wakeup time to distant future and want to account
 
109
for the RTC drift.
 
110
.TP
 
111
.BR \-h , \ \-\-help
 
112
Display a help text and exit.
 
113
.TP
 
114
.BR \-V , \ \-\-version
 
115
Display the version of
102
116
.B hwclock
103
 
on Standard Output.
 
117
and exit.
 
118
 
 
119
.SH OPTIONS
 
120
.PP
 
121
The first two options apply to just a few specific functions,
 
122
the others apply to most functions.
104
123
.TP
105
124
.BI \-\-date= date_string
106
125
You need this option if you specify the
107
126
.B \-\-set
108
 
option.  Otherwise, it is ignored.
109
 
This specifies the time to which to set the Hardware Clock.
 
127
or
 
128
.B \-\-predict
 
129
functions, otherwise it is ignored.
 
130
It specifies the time to which to set the Hardware Clock, or the
 
131
time for which to predict the Hardware Clock reading.
110
132
The value of this option is an argument to the
111
133
.BR date (1)
112
134
program.
113
 
For example,
114
 
.sp
115
 
.I hwclock --set --date="9/22/96 16:45:05"
116
 
.sp
117
 
The argument is in local time, even if you keep your Hardware Clock in
 
135
For example:
 
136
.sp
 
137
.B "    hwclock" --set --date="2011-08-14 16:45:05"
 
138
.sp
 
139
The argument must be in local time, even if you keep your Hardware Clock in
118
140
Coordinated Universal time.  See the
119
141
.B \-\-utc
120
142
option.
122
144
.TP
123
145
.BI \-\-epoch= year
124
146
Specifies the year which is the beginning of the Hardware Clock's
125
 
epoch.  I.e. the number of years into AD to which a zero value in the
126
 
Hardware Clock's year counter refers. It is used together with
127
 
the \-\-setepoch option to set the kernel's idea of the epoch of the
 
147
epoch, that is the number of years into AD to which a zero value in the
 
148
Hardware Clock's year counter refers.  It is used together with
 
149
the \fB\-\-setepoch\fR option to set the kernel's idea of the epoch of the
128
150
Hardware Clock, or otherwise to specify the epoch for use with
129
151
direct ISA access.
130
152
 
131
153
For example, on a Digital Unix machine:
132
154
.sp
133
 
.I hwclock --setepoch --epoch=1952
134
 
 
135
 
.TP
136
 
.BI \-\-predict
137
 
Predict what the RTC will read at time given by the
138
 
.B \-\-date
139
 
option based on the adjtime file. This is useful for example if you
140
 
need to set an RTC wakeup time to distant future and want to account
141
 
for the RTC drift.
142
 
 
143
 
.SH OPTIONS
144
 
.PP
145
 
The following options apply to most functions.
 
155
.B "    hwclock" --setepoch --epoch=1952
 
156
 
146
157
.TP
147
158
.BR \-u , \ \-\-utc
148
159
.TP
160
171
If you specify neither
161
172
.B \-\-utc
162
173
nor
163
 
.B \-\-localtime
164
 
, the default is whichever was specified the last time
165
 
.B hwclock
166
 
was used to set the clock (i.e. hwclock was successfully run with the
 
174
.BR \-\-localtime ,
 
175
the default is whichever was specified the last time
 
176
.B hwclock
 
177
was used to set the clock (i.e.
 
178
.B hwclock
 
179
was successfully run with the
167
180
.BR \-\-set ,
168
181
.BR \-\-systohc ,
169
182
or
170
183
.B \-\-adjust
171
184
options), as recorded in the adjtime file.  If the adjtime file doesn't
172
 
exist, the default is local time.
 
185
exist, the default is UTC time.
173
186
 
174
187
.TP
175
188
.B \-\-noadjfile
176
 
disables the facilities provided by
 
189
Disables the facilities provided by
177
190
.IR /etc/adjtime .
178
191
.B hwclock
179
 
will not read nor write to that file with this option. Either
 
192
will not read nor write to that file with this option.  Either
180
193
.B \-\-utc
181
194
or
182
195
.B \-\-localtime
184
197
 
185
198
.TP
186
199
.BI \-\-adjfile= filename
187
 
overrides the default /etc/adjtime.
 
200
Overrides the default /etc/adjtime.
188
201
 
189
202
.TP
190
203
.BR \-f , \ \-\-rtc=\fIfilename\fB
191
 
overrides the default /dev file name, which is
 
204
Overrides the default /dev file name, which is
192
205
.IR /dev/rtc
193
206
on many platforms but may be
194
207
.IR /dev/rtc0 ,
197
210
 
198
211
.TP
199
212
.B \-\-directisa
200
 
is meaningful only on an ISA machine or an Alpha (which implements enough
201
 
of ISA to be, roughly speaking, an ISA machine for
 
213
This option is meaningful only on an ISA machine or an Alpha (which implements
 
214
enough of ISA to be, roughly speaking, an ISA machine for
202
215
.BR hwclock 's
203
216
purposes).  For other machines, it has no effect.  This option tells
204
217
.B hwclock
206
219
Without this option,
207
220
.B hwclock
208
221
will try to use the /dev/rtc device (which it assumes to be driven by the
209
 
rtc device driver).  If it is unable to open the device (for read), it will
 
222
RTC device driver).  If it is unable to open the device (for reading), it will
210
223
use the explicit I/O instructions anyway.
211
224
 
212
 
The rtc device driver was new in Linux Release 2.
213
225
.TP
214
226
.B \-\-badyear
215
227
Indicates that the Hardware Clock is incapable of storing years outside
231
243
the Hardware Clock value and instead tries to guess the year based on the
232
244
last calibrated date in the adjtime file, by assuming that that date is
233
245
within the past year.  For this to work, you had better do a
234
 
.I hwclock \-\-set
 
246
.B hwclock \-\-set
235
247
or
236
 
.I hwclock \-\-systohc
 
248
.B hwclock \-\-systohc
237
249
at least once a year!
238
250
 
239
251
Though
278
290
(If you find you need one of these options to make
279
291
.B hwclock
280
292
work, contact the maintainer to see if the program can be improved
281
 
to detect your system automatically. Output of `hwclock --debug'
 
293
to detect your system automatically.  Output of `hwclock --debug'
282
294
and `cat /proc/cpuinfo' may be of interest.)
283
295
 
 
296
Option
284
297
.B \-\-jensen
285
 
means you are running on a Jensen model.
286
 
 
 
298
means you are running on a Jensen model.  And
287
299
.B \-\-funky\-toy
288
 
means that on your machine, one has to use the UF bit instead
 
300
means that on your machine one has to use the UF bit instead
289
301
of the UIP bit in the Hardware Clock to detect a time transition.  "Toy"
290
302
in the option name refers to the Time Of Year facility of the machine.
291
303