~ubuntu-branches/ubuntu/maverick/eglibc/maverick-proposed

<tr><td align="left" valign="top"><a href="#Elapsed-Time">21.2 Elapsed Time</a></td><td>  </td><td align="left" valign="top"> Data types to represent elapsed times

</td></tr>

<tr><td align="left" valign="top"><a href="#Processor-And-CPU-Time">21.3 Processor And CPU Time</a></td><td>  </td><td align="left" valign="top"> Time a program has spent executing.

</td></tr>

<tr><td align="left" valign="top"><a href="#Calendar-Time">21.4 Calendar Time</a></td><td>  </td><td align="left" valign="top"> Manipulation of “real” dates and times.

</td></tr>

<tr><td align="left" valign="top"><a href="#Setting-an-Alarm">21.5 Setting an Alarm</a></td><td>  </td><td align="left" valign="top"> Sending a signal after a specified time.

100

</td></tr>

101

<tr><td align="left" valign="top"><a href="#Sleeping">21.6 Sleeping</a></td><td>  </td><td align="left" valign="top"> Waiting for a period of time.

102

</td></tr>

103

</table>

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

121

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

122

123

</tr></table>

124

125

<h2 class="section">21.1 Time Basics</h2>

126

127

128

Discussing time in a technical manual can be difficult because the word

129

“time” in English refers to lots of different things. In this manual,

130

we use a rigorous terminology to avoid confusion, and the only thing we

131

use the simple word “time” for is to talk about the abstract concept.

132

133

A calendar time is a point in the time continuum, for example

134

November 4, 1990 at 18:02.5 UTC. Sometimes this is called “absolute

135

time”.

136

137

138

We don’t speak of a “date”, because that is inherent in a calendar

139

time.

140

141

142

An interval is a contiguous part of the time continuum between two

143

calendar times, for example the hour between 9:00 and 10:00 on July 4,

144

1980.

145

146

147

An elapsed time is the length of an interval, for example, 35

148

minutes. People sometimes sloppily use the word “interval” to refer

149

to the elapsed time of some interval.

150

151

152

153

An amount of time is a sum of elapsed times, which need not be of

154

any specific intervals. For example, the amount of time it takes to

155

read a book might be 9 hours, independently of when and in how many

156

sittings it is read.

157

158

A period is the elapsed time of an interval between two events,

159

especially when they are part of a sequence of regularly repeating

160

events.

161

162

163

CPU time is like calendar time, except that it is based on the

164

subset of the time continuum when a particular process is actively

165

using a CPU. CPU time is, therefore, relative to a process.

166

167

168

Processor time is an amount of time that a CPU is in use. In

169

fact, it’s a basic system resource, since there’s a limit to how much

170

can exist in any given interval (that limit is the elapsed time of the

171

interval times the number of CPUs in the processor). People often call

172

this CPU time, but we reserve the latter term in this manual for the

173

definition above.

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

191

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

192

193

</tr></table>

194

195

<h2 class="section">21.2 Elapsed Time</h2>

196

197

198

One way to represent an elapsed time is with a simple arithmetic data

199

type, as with the following function to compute the elapsed time between

200

two calendar times. This function is declared in ‘<tt>time.h</tt>’.

201

202

<dl>

203

<dt><a name="index-difftime"></a>Function: double difftime (time_t <var>time1</var>, time_t <var>time0</var>)</dt>

204

<dd>The <code>difftime</code> function returns the number of seconds of elapsed

205

time between calendar time <var>time1</var> and calendar time <var>time0</var>, as

206

a value of type <code>double</code>. The difference ignores leap seconds

207

unless leap second support is enabled.

208

209

In the GNU system, you can simply subtract <code>time_t</code> values. But on

210

other systems, the <code>time_t</code> data type might use some other encoding

211

where subtraction doesn’t work directly.

212

</dd></dl>

213

214

The GNU C library provides two data types specifically for representing

215

an elapsed time. They are used by various GNU C library functions, and

216

you can use them for your own purposes too. They’re exactly the same

217

except that one has a resolution in microseconds, and the other, newer

218

one, is in nanoseconds.

219

220

<dl>

221

<dt><a name="index-struct-timeval"></a>Data Type: struct timeval</dt>

222

223

The <code>struct timeval</code> structure represents an elapsed time. It is

224

declared in ‘<tt>sys/time.h</tt>’ and has the following members:

225

226

227

228

<dd>This represents the number of whole seconds of elapsed time.

229

230

</dd>

231

232

<dd>This is the rest of the elapsed time (a fraction of a second),

233

represented as the number of microseconds. It is always less than one

234

million.

235

236

</dd>

237

</dl>

238

</dd></dl>

239

240

<dl>

241

<dt><a name="index-struct-timespec"></a>Data Type: struct timespec</dt>

242

243

The <code>struct timespec</code> structure represents an elapsed time. It is

244

declared in ‘<tt>time.h</tt>’ and has the following members:

245

246

247

248

<dd>This represents the number of whole seconds of elapsed time.

249

250

</dd>

251

252

<dd>This is the rest of the elapsed time (a fraction of a second),

253

represented as the number of nanoseconds. It is always less than one

254

billion.

255

256

</dd>

257

</dl>

258

</dd></dl>

259

260

It is often necessary to subtract two values of type <code>struct

261

timeval</code> or <code>struct timespec</code>. Here is the best way to do

262

this. It works even on some peculiar operating systems where the

263

<code>tv_sec</code> member has an unsigned type.

264

265

<table><tr><td> </td><td><pre class="smallexample">/* Subtract the `struct timeval' values X and Y,

266

storing the result in RESULT.

267

Return 1 if the difference is negative, otherwise 0. */

268

269

int

270

timeval_subtract (result, x, y)

271

struct timeval *result, *x, *y;

272

{

273

/* Perform the carry for the later subtraction by updating <var>y</var>. */

274

if (x->tv_usec < y->tv_usec) {

275

int nsec = (y->tv_usec - x->tv_usec) / 1000000 + 1;

276

y->tv_usec -= 1000000 * nsec;

277

y->tv_sec += nsec;

278

}

279

if (x->tv_usec - y->tv_usec > 1000000) {

280

int nsec = (x->tv_usec - y->tv_usec) / 1000000;

281

y->tv_usec += 1000000 * nsec;

282

y->tv_sec -= nsec;

283

}

284

285

/* Compute the time remaining to wait.

286

<code>tv_usec</code> is certainly positive. */

287

result->tv_sec = x->tv_sec - y->tv_sec;

288

result->tv_usec = x->tv_usec - y->tv_usec;

289

290

/* Return 1 if result is negative. */

291

return x->tv_sec < y->tv_sec;

292

}

293

</pre></td></tr></table>

294

295

Common functions that use <code>struct timeval</code> are <code>gettimeofday</code>

296

and <code>settimeofday</code>.

297

298

299

There are no GNU C library functions specifically oriented toward

300

dealing with elapsed times, but the calendar time, processor time, and

301

alarm and sleeping functions have a lot to do with them.

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

319

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

320

321

</tr></table>

322

323

<h2 class="section">21.3 Processor And CPU Time</h2>

324

325

If you’re trying to optimize your program or measure its efficiency,

326

it’s very useful to know how much processor time it uses. For that,

327

calendar time and elapsed times are useless because a process may spend

328

time waiting for I/O or for other processes to use the CPU. However,

329

you can get the information with the functions in this section.

330

331

CPU time (see section <a href="#Time-Basics">Time Basics</a>) is represented by the data type

332

<code>clock_t</code>, which is a number of clock ticks. It gives the

333

total amount of time a process has actively used a CPU since some

334

arbitrary event. On the GNU system, that event is the creation of the

335

process. While arbitrary in general, the event is always the same event

336

for any particular process, so you can always measure how much time on

337

the CPU a particular computation takes by examining the process’ CPU

338

time before and after the computation.

339

340

341

342

343

In the GNU system, <code>clock_t</code> is equivalent to <code>long int</code> and

344

<code>CLOCKS_PER_SEC</code> is an integer value. But in other systems, both

345

<code>clock_t</code> and the macro <code>CLOCKS_PER_SEC</code> can be either integer

346

or floating-point types. Casting CPU time values to <code>double</code>, as

347

in the example above, makes sure that operations such as arithmetic and

348

printing work properly and consistently no matter what the underlying

349

representation is.

350

351

Note that the clock can wrap around. On a 32bit system with

352

<code>CLOCKS_PER_SEC</code> set to one million this function will return the

353

same value approximately every 72 minutes.

354

355

For additional functions to examine a process’ use of processor time,

356

and to control it, see <a href="libc_22.html#Resource-Usage-And-Limitation">Resource Usage And Limitation</a>.

357

358

359

360

<tr><td align="left" valign="top"><a href="#CPU-Time">21.3.1 CPU Time Inquiry</a></td><td>  </td><td align="left" valign="top"> The <code>clock</code> function.

361

</td></tr>

362

<tr><td align="left" valign="top"><a href="#Processor-Time">21.3.2 Processor Time Inquiry</a></td><td>  </td><td align="left" valign="top"> The <code>times</code> function.

363

</td></tr>

364

</table>

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

381

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

382

383

</tr></table>

384

385

<h3 class="subsection">21.3.1 CPU Time Inquiry</h3>

386

387

To get a process’ CPU time, you can use the <code>clock</code> function. This

388

facility is declared in the header file ‘<tt>time.h</tt>’.

389

390

391

In typical usage, you call the <code>clock</code> function at the beginning

392

and end of the interval you want to time, subtract the values, and then

393

divide by <code>CLOCKS_PER_SEC</code> (the number of clock ticks per second)

394

to get processor time, like this:

395

396

<table><tr><td> </td><td><pre class="smallexample">#include <time.h>

397

398

clock_t start, end;

399

double cpu_time_used;

400

401

start = clock();

402

… /* Do the work. */

403

end = clock();

404

cpu_time_used = ((double) (end - start)) / CLOCKS_PER_SEC;

405

</pre></td></tr></table>

406

407

Do not use a single CPU time as an amount of time; it doesn’t work that

408

way. Either do a subtraction as shown above or query processor time

409

directly. See section <a href="#Processor-Time">Processor Time Inquiry</a>.

410

411

Different computers and operating systems vary wildly in how they keep

412

track of CPU time. It’s common for the internal processor clock

413

to have a resolution somewhere between a hundredth and millionth of a

414

second.

415

416

<dl>

417

<dt><a name="index-CLOCKS_005fPER_005fSEC"></a>Macro: int CLOCKS_PER_SEC</dt>

418

<dd>The value of this macro is the number of clock ticks per second measured

419

by the <code>clock</code> function. POSIX requires that this value be one

420

million independent of the actual resolution.

421

</dd></dl>

422

423

<dl>

424

<dt><a name="index-CLK_005fTCK"></a>Macro: int CLK_TCK</dt>

425

<dd>This is an obsolete name for <code>CLOCKS_PER_SEC</code>.

426

</dd></dl>

427

428

<dl>

429

<dt><a name="index-clock_005ft"></a>Data Type: clock_t</dt>

430

<dd>This is the type of the value returned by the <code>clock</code> function.

431

Values of type <code>clock_t</code> are numbers of clock ticks.

432

</dd></dl>

433

434

<dl>

435

<dt><a name="index-clock"></a>Function: clock_t clock (void)</dt>

436

<dd>This function returns the calling process’ current CPU time. If the CPU

437

time is not available or cannot be represented, <code>clock</code> returns the

438

value <code>(clock_t)(-1)</code>.

439

</dd></dl>

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

457

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

458

459

</tr></table>

460

461

<h3 class="subsection">21.3.2 Processor Time Inquiry</h3>

462

463

The <code>times</code> function returns information about a process’

464

consumption of processor time in a <code>struct tms</code> object, in

465

addition to the process’ CPU time. See section <a href="#Time-Basics">Time Basics</a>. You should

466

include the header file ‘<tt>sys/times.h</tt>’ to use this facility.

467

468

469

470

471

<dl>

472

<dt><a name="index-struct-tms"></a>Data Type: struct tms</dt>

473

<dd>The <code>tms</code> structure is used to return information about process

474

times. It contains at least the following members:

475

476

477

<dt> <code>clock_t tms_utime</code></dt>

478

<dd>This is the total processor time the calling process has used in

479

executing the instructions of its program.

480

481

</dd>

482

<dt> <code>clock_t tms_stime</code></dt>

483

<dd>This is the processor time the system has used on behalf of the calling

484

process.

485

486

</dd>

487

<dt> <code>clock_t tms_cutime</code></dt>

488

<dd>This is the sum of the <code>tms_utime</code> values and the <code>tms_cutime</code>

489

values of all terminated child processes of the calling process, whose

490

status has been reported to the parent process by <code>wait</code> or

491

<code>waitpid</code>; see <a href="libc_26.html#Process-Completion">Process Completion</a>. In other words, it

492

represents the total processor time used in executing the instructions

493

of all the terminated child processes of the calling process, excluding

494

child processes which have not yet been reported by <code>wait</code> or

495

<code>waitpid</code>.

496

497

498

</dd>

499

<dt> <code>clock_t tms_cstime</code></dt>

500

<dd>This is similar to <code>tms_cutime</code>, but represents the total processor

501

time system has used on behalf of all the terminated child processes

502

of the calling process.

503

</dd>

504

</dl>

505

506

All of the times are given in numbers of clock ticks. Unlike CPU time,

507

these are the actual amounts of time; not relative to any event.

508

See section <a href="libc_26.html#Creating-a-Process">Creating a Process</a>.

509

</dd></dl>

510

511

<dl>

512

<dt><a name="index-times"></a>Function: clock_t times (struct tms *<var>buffer</var>)</dt>

513

<dd>The <code>times</code> function stores the processor time information for

514

the calling process in <var>buffer</var>.

515

516

The return value is the calling process’ CPU time (the same value you

517

get from <code>clock()</code>. <code>times</code> returns <code>(clock_t)(-1)</code> to

518

indicate failure.

519

</dd></dl>

520

521

Portability Note: The <code>clock</code> function described in

522

<a href="#CPU-Time">CPU Time Inquiry</a> is specified by the ISO C standard. The

523

<code>times</code> function is a feature of POSIX.1. In the GNU system, the

524

CPU time is defined to be equivalent to the sum of the <code>tms_utime</code>

525

and <code>tms_stime</code> fields returned by <code>times</code>.

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

542

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

543

544

</tr></table>

545

546

<h2 class="section">21.4 Calendar Time</h2>

547

548

This section describes facilities for keeping track of calendar time.

549

See section <a href="#Time-Basics">Time Basics</a>.

550

551

The GNU C library represents calendar time three ways:

552

553

<ul>

554

<li>

555

Simple time (the <code>time_t</code> data type) is a compact

556

representation, typically giving the number of seconds of elapsed time

557

since some implementation-specific base time.

558

559

560

</li><li>

561

There is also a "high-resolution time" representation. Like simple

562

time, this represents a calendar time as an elapsed time since a base

563

time, but instead of measuring in whole seconds, it uses a <code>struct

564

timeval</code> data type, which includes fractions of a second. Use this time

565

representation instead of simple time when you need greater precision.

566

567

568

</li><li>

569

Local time or broken-down time (the <code>struct tm</code> data

570

type) represents a calendar time as a set of components specifying the

571

year, month, and so on in the Gregorian calendar, for a specific time

572

zone. This calendar time representation is usually used only to

573

communicate with people.

574

575

576

577

578

</li></ul>

579

580

581

<tr><td align="left" valign="top"><a href="#Simple-Calendar-Time">21.4.1 Simple Calendar Time</a></td><td>  </td><td align="left" valign="top"> Facilities for manipulating calendar time.

582

</td></tr>

583

<tr><td align="left" valign="top"><a href="#High_002dResolution-Calendar">21.4.2 High-Resolution Calendar</a></td><td>  </td><td align="left" valign="top"> A time representation with greater precision.

584

</td></tr>

585

<tr><td align="left" valign="top"><a href="#Broken_002ddown-Time">21.4.3 Broken-down Time</a></td><td>  </td><td align="left" valign="top"> Facilities for manipulating local time.

586

</td></tr>

587

<tr><td align="left" valign="top"><a href="#High-Accuracy-Clock">21.4.4 High Accuracy Clock</a></td><td>  </td><td align="left" valign="top"> Maintaining a high accuracy system clock.

588

</td></tr>

589

<tr><td align="left" valign="top"><a href="#Formatting-Calendar-Time">21.4.5 Formatting Calendar Time</a></td><td>  </td><td align="left" valign="top"> Converting times to strings.

590

</td></tr>

591

<tr><td align="left" valign="top"><a href="#Parsing-Date-and-Time">21.4.6 Convert textual time and date information back</a></td><td>  </td><td align="left" valign="top"> Convert textual time and date information back

592

into broken-down time values.

593

</td></tr>

594

<tr><td align="left" valign="top"><a href="#TZ-Variable">21.4.7 Specifying the Time Zone with <code>TZ</code></a></td><td>  </td><td align="left" valign="top"> How users specify the time zone.

595

</td></tr>

596

<tr><td align="left" valign="top"><a href="#Time-Zone-Functions">21.4.8 Functions and Variables for Time Zones</a></td><td>  </td><td align="left" valign="top"> Functions to examine or specify the time zone.

597

</td></tr>

598

<tr><td align="left" valign="top"><a href="#Time-Functions-Example">21.4.9 Time Functions Example</a></td><td>  </td><td align="left" valign="top"> An example program showing use of some of

599

the time functions.

600

</td></tr>

601

</table>

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

618

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

619

620

</tr></table>

621

622

<h3 class="subsection">21.4.1 Simple Calendar Time</h3>

623

624

This section describes the <code>time_t</code> data type for representing calendar

625

time as simple time, and the functions which operate on simple time objects.

626

These facilities are declared in the header file ‘<tt>time.h</tt>’.

627

628

629

630

<dl>

631

632

<dd>This is the data type used to represent simple time. Sometimes, it also

633

represents an elapsed time. When interpreted as a calendar time value,

634

it represents the number of seconds elapsed since 00:00:00 on January 1,

635

1970, Coordinated Universal Time. (This calendar time is sometimes

636

referred to as the epoch.) POSIX requires that this count not

637

include leap seconds, but on some systems this count includes leap seconds

638

if you set <code>TZ</code> to certain values (see section <a href="#TZ-Variable">Specifying the Time Zone with <code>TZ</code></a>).

639

640

Note that a simple time has no concept of local time zone. Calendar

641

Time <var>T</var> is the same instant in time regardless of where on the

642

globe the computer is.

643

644

In the GNU C library, <code>time_t</code> is equivalent to <code>long int</code>.

645

In other systems, <code>time_t</code> might be either an integer or

646

floating-point type.

647

</dd></dl>

648

649

The function <code>difftime</code> tells you the elapsed time between two

650

simple calendar times, which is not always as easy to compute as just

651

subtracting. See section <a href="#Elapsed-Time">Elapsed Time</a>.

652

653

<dl>

654

<dt><a name="index-time-1"></a>Function: time_t time (time_t *<var>result</var>)</dt>

655

<dd>The <code>time</code> function returns the current calendar time as a value of

656

type <code>time_t</code>. If the argument <var>result</var> is not a null pointer,

657

the calendar time value is also stored in <code>*<var>result</var></code>. If the

658

current calendar time is not available, the value

659

<code>(time_t)(-1)</code> is returned.

660

</dd></dl>

661

662

<dl>

663

<dt><a name="index-stime"></a>Function: int stime (time_t *<var>newtime</var>)</dt>

664

<dd><code>stime</code> sets the system clock, i.e., it tells the system that the

665

current calendar time is <var>newtime</var>, where <code>newtime</code> is

666

interpreted as described in the above definition of <code>time_t</code>.

667

668

<code>settimeofday</code> is a newer function which sets the system clock to

669

better than one second precision. <code>settimeofday</code> is generally a

670

better choice than <code>stime</code>. See section <a href="#High_002dResolution-Calendar">High-Resolution Calendar</a>.

671

672

Only the superuser can set the system clock.

673

674

If the function succeeds, the return value is zero. Otherwise, it is

675

<code>-1</code> and <code>errno</code> is set accordingly:

676

677

678

<dt> <code>EPERM</code></dt>

679

<dd>The process is not superuser.

680

</dd>

681

</dl>

682

</dd></dl>

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

701

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

702

703

</tr></table>

704

705

<h3 class="subsection">21.4.2 High-Resolution Calendar</h3>

706

707

The <code>time_t</code> data type used to represent simple times has a

708

resolution of only one second. Some applications need more precision.

709

710

So, the GNU C library also contains functions which are capable of

711

representing calendar times to a higher resolution than one second. The

712

functions and the associated data types described in this section are

713

declared in ‘<tt>sys/time.h</tt>’.

714

715

716

<dl>

717

<dt><a name="index-struct-timezone"></a>Data Type: struct timezone</dt>

718

<dd>The <code>struct timezone</code> structure is used to hold minimal information

719

about the local time zone. It has the following members:

720

721

722

<dt> <code>int tz_minuteswest</code></dt>

723

<dd>This is the number of minutes west of UTC.

724

725

</dd>

726

<dt> <code>int tz_dsttime</code></dt>

727

<dd>If nonzero, Daylight Saving Time applies during some part of the year.

728

</dd>

729

</dl>

730

731

The <code>struct timezone</code> type is obsolete and should never be used.

732

Instead, use the facilities described in <a href="#Time-Zone-Functions">Functions and Variables for Time Zones</a>.

733

</dd></dl>

734

735

<dl>

736

<dt><a name="index-gettimeofday"></a>Function: int gettimeofday (struct timeval *<var>tp</var>, struct timezone *<var>tzp</var>)</dt>

737

<dd>The <code>gettimeofday</code> function returns the current calendar time as

738

the elapsed time since the epoch in the <code>struct timeval</code> structure

739

indicated by <var>tp</var>. (see section <a href="#Elapsed-Time">Elapsed Time</a> for a description of

740

<code>struct timeval</code>). Information about the time zone is returned in

741

the structure pointed at <var>tzp</var>. If the <var>tzp</var> argument is a null

742

pointer, time zone information is ignored.

743

744

The return value is <code>0</code> on success and <code>-1</code> on failure. The

745

following <code>errno</code> error condition is defined for this function:

746

747

748

<dt> <code>ENOSYS</code></dt>

749

<dd>The operating system does not support getting time zone information, and

750

<var>tzp</var> is not a null pointer. The GNU operating system does not

751

support using <code>struct timezone</code> to represent time zone

752

information; that is an obsolete feature of 4.3 BSD.

753

Instead, use the facilities described in <a href="#Time-Zone-Functions">Functions and Variables for Time Zones</a>.

754

</dd>

755

</dl>

756

</dd></dl>

757

758

<dl>

759

<dt><a name="index-settimeofday"></a>Function: int settimeofday (const struct timeval *<var>tp</var>, const struct timezone *<var>tzp</var>)</dt>

760

<dd>The <code>settimeofday</code> function sets the current calendar time in the

761

system clock according to the arguments. As for <code>gettimeofday</code>,

762

the calendar time is represented as the elapsed time since the epoch.

763

As for <code>gettimeofday</code>, time zone information is ignored if

764

<var>tzp</var> is a null pointer.

765

766

You must be a privileged user in order to use <code>settimeofday</code>.

767

768

Some kernels automatically set the system clock from some source such as

769

a hardware clock when they start up. Others, including Linux, place the

770

system clock in an “invalid” state (in which attempts to read the clock

771

fail). A call of <code>stime</code> removes the system clock from an invalid

772

state, and system startup scripts typically run a program that calls

773

<code>stime</code>.

774

775

<code>settimeofday</code> causes a sudden jump forwards or backwards, which

776

can cause a variety of problems in a system. Use <code>adjtime</code> (below)

777

to make a smooth transition from one time to another by temporarily

778

speeding up or slowing down the clock.

779

780

With a Linux kernel, <code>adjtimex</code> does the same thing and can also

781

make permanent changes to the speed of the system clock so it doesn’t

782

need to be corrected as often.

783

784

The return value is <code>0</code> on success and <code>-1</code> on failure. The

785

following <code>errno</code> error conditions are defined for this function:

786

787

788

<dt> <code>EPERM</code></dt>

789

<dd>This process cannot set the clock because it is not privileged.

790

791

</dd>

792

<dt> <code>ENOSYS</code></dt>

793

<dd>The operating system does not support setting time zone information, and

794

<var>tzp</var> is not a null pointer.

795

</dd>

796

</dl>

797

</dd></dl>

798

799

<dl>

800

<dt><a name="index-adjtime"></a>Function: int adjtime (const struct timeval *<var>delta</var>, struct timeval *<var>olddelta</var>)</dt>

801

<dd>This function speeds up or slows down the system clock in order to make

802

a gradual adjustment. This ensures that the calendar time reported by

803

the system clock is always monotonically increasing, which might not

804

happen if you simply set the clock.

805

806

The <var>delta</var> argument specifies a relative adjustment to be made to

807

the clock time. If negative, the system clock is slowed down for a

808

while until it has lost this much elapsed time. If positive, the system

809

clock is speeded up for a while.

810

811

If the <var>olddelta</var> argument is not a null pointer, the <code>adjtime</code>

812

function returns information about any previous time adjustment that

813

has not yet completed.

814

815

This function is typically used to synchronize the clocks of computers

816

in a local network. You must be a privileged user to use it.

817

818

With a Linux kernel, you can use the <code>adjtimex</code> function to

819

permanently change the clock speed.

820

821

The return value is <code>0</code> on success and <code>-1</code> on failure. The

822

following <code>errno</code> error condition is defined for this function:

823

824

825

<dt> <code>EPERM</code></dt>

826

<dd>You do not have privilege to set the time.

827

</dd>

828

</dl>

829

</dd></dl>

830

831

Portability Note: The <code>gettimeofday</code>, <code>settimeofday</code>,

832

and <code>adjtime</code> functions are derived from BSD.

833

834

835

Symbols for the following function are declared in ‘<tt>sys/timex.h</tt>’.

836

837

<dl>

838

<dt><a name="index-adjtimex"></a>Function: int adjtimex (struct timex *<var>timex</var>)</dt>

839

<dd>

840

<code>adjtimex</code> is functionally identical to <code>ntp_adjtime</code>.

841

See section <a href="#High-Accuracy-Clock">High Accuracy Clock</a>.

842

843

This function is present only with a Linux kernel.

844

845

</dd></dl>

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

862

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

863

864

</tr></table>

865

866

<h3 class="subsection">21.4.3 Broken-down Time</h3>

867

868

869

870

Calendar time is represented by the usual GNU C library functions as an

871

elapsed time since a fixed base calendar time. This is convenient for

872

computation, but has no relation to the way people normally think of

873

calendar time. By contrast, broken-down time is a binary

874

representation of calendar time separated into year, month, day, and so

875

on. Broken-down time values are not useful for calculations, but they

876

are useful for printing human readable time information.

877

878

A broken-down time value is always relative to a choice of time

879

zone, and it also indicates which time zone that is.

880

881

The symbols in this section are declared in the header file ‘<tt>time.h</tt>’.

882

883

<dl>

884

<dt><a name="index-struct-tm"></a>Data Type: struct tm</dt>

885

<dd>This is the data type used to represent a broken-down time. The structure

886

contains at least the following members, which can appear in any order.

887

888

889

890

<dd>This is the number of full seconds since the top of the minute (normally

891

in the range <code>0</code> through <code>59</code>, but the actual upper limit is

892

<code>60</code>, to allow for leap seconds if leap second support is

893

available).

894

895

896

</dd>

897

898

<dd>This is the number of full minutes since the top of the hour (in the

899

range <code>0</code> through <code>59</code>).

900

901

</dd>

902

903

<dd>This is the number of full hours past midnight (in the range <code>0</code> through

904

<code>23</code>).

905

906

</dd>

907

908

<dd>This is the ordinal day of the month (in the range <code>1</code> through <code>31</code>).

909

Watch out for this one! As the only ordinal number in the structure, it is

910

inconsistent with the rest of the structure.

911

912

</dd>

913

914

<dd>This is the number of full calendar months since the beginning of the

915

year (in the range <code>0</code> through <code>11</code>). Watch out for this one!

916

People usually use ordinal numbers for month-of-year (where January = 1).

917

918

</dd>

919

920

<dd>This is the number of full calendar years since 1900.

921

922

</dd>

923

924

<dd>This is the number of full days since Sunday (in the range <code>0</code> through

925

<code>6</code>).

926

927

</dd>

928

929

<dd>This is the number of full days since the beginning of the year (in the

930

range <code>0</code> through <code>365</code>).

931

932

</dd>

933

<dt> <code>int tm_isdst</code></dt>

934

935

936

This is a flag that indicates whether Daylight Saving Time is (or was, or

937

will be) in effect at the time described. The value is positive if

938

Daylight Saving Time is in effect, zero if it is not, and negative if the

939

information is not available.

940

941

</dd>

942

<dt> <code>long int tm_gmtoff</code></dt>

943

<dd>This field describes the time zone that was used to compute this

944

broken-down time value, including any adjustment for daylight saving; it

945

is the number of seconds that you must add to UTC to get local time.

946

You can also think of this as the number of seconds east of UTC. For

947

example, for U.S. Eastern Standard Time, the value is <code>-5*60*60</code>.

948

The <code>tm_gmtoff</code> field is derived from BSD and is a GNU library

949

extension; it is not visible in a strict ISO C environment.

950

951

</dd>

952

<dt> <code>const char *tm_zone</code></dt>

953

<dd>This field is the name for the time zone that was used to compute this

954

broken-down time value. Like <code>tm_gmtoff</code>, this field is a BSD and

955

GNU extension, and is not visible in a strict ISO C environment.

956

</dd>

957

</dl>

958

</dd></dl>

959

960

961

<dl>

962

<dt><a name="index-localtime"></a>Function: struct tm * localtime (const time_t *<var>time</var>)</dt>

963

<dd>The <code>localtime</code> function converts the simple time pointed to by

964

<var>time</var> to broken-down time representation, expressed relative to the

965

user’s specified time zone.

966

967

The return value is a pointer to a static broken-down time structure, which

968

might be overwritten by subsequent calls to <code>ctime</code>, <code>gmtime</code>,

969

or <code>localtime</code>. (But no other library function overwrites the contents

970

of this object.)

971

972

The return value is the null pointer if <var>time</var> cannot be represented

973

as a broken-down time; typically this is because the year cannot fit into

974

an <code>int</code>.

975

976

Calling <code>localtime</code> has one other effect: it sets the variable

977

<code>tzname</code> with information about the current time zone. See section <a href="#Time-Zone-Functions">Functions and Variables for Time Zones</a>.

978

</dd></dl>

979

980

Using the <code>localtime</code> function is a big problem in multi-threaded

981

programs. The result is returned in a static buffer and this is used in

982

all threads. POSIX.1c introduced a variant of this function.

983

984

<dl>

985

<dt><a name="index-localtime_005fr"></a>Function: struct tm * localtime_r (const time_t *<var>time</var>, struct tm *<var>resultp</var>)</dt>

986

<dd>The <code>localtime_r</code> function works just like the <code>localtime</code>

987

function. It takes a pointer to a variable containing a simple time

988

and converts it to the broken-down time format.

989

990

But the result is not placed in a static buffer. Instead it is placed

991

in the object of type <code>struct tm</code> to which the parameter

992

<var>resultp</var> points.

993

994

If the conversion is successful the function returns a pointer to the

995

object the result was written into, i.e., it returns <var>resultp</var>.

996

</dd></dl>

997

998

999

<dl>

1000

<dt><a name="index-gmtime"></a>Function: struct tm * gmtime (const time_t *<var>time</var>)</dt>

1001

<dd>This function is similar to <code>localtime</code>, except that the broken-down

1002

time is expressed as Coordinated Universal Time (UTC) (formerly called

1003

Greenwich Mean Time (GMT)) rather than relative to a local time zone.

1004

1005

</dd></dl>

1006

1007

As for the <code>localtime</code> function we have the problem that the result

1008

is placed in a static variable. POSIX.1c also provides a replacement for

1009

<code>gmtime</code>.

1010

1011

<dl>

1012

<dt><a name="index-gmtime_005fr"></a>Function: struct tm * gmtime_r (const time_t *<var>time</var>, struct tm *<var>resultp</var>)</dt>

1013

<dd>This function is similar to <code>localtime_r</code>, except that it converts

1014

just like <code>gmtime</code> the given time as Coordinated Universal Time.

1015

1016

If the conversion is successful the function returns a pointer to the

1017

object the result was written into, i.e., it returns <var>resultp</var>.

1018

</dd></dl>

1019

1020

1021

<dl>

1022

<dt><a name="index-mktime"></a>Function: time_t mktime (struct tm *<var>brokentime</var>)</dt>

1023

<dd>The <code>mktime</code> function is used to convert a broken-down time structure

1024

to a simple time representation. It also “normalizes” the contents of

1025

the broken-down time structure, by filling in the day of week and day of

1026

year based on the other date and time components.

1027

1028

The <code>mktime</code> function ignores the specified contents of the

1029

<code>tm_wday</code> and <code>tm_yday</code> members of the broken-down time

1030

structure. It uses the values of the other components to determine the

1031

calendar time; it’s permissible for these components to have

1032

unnormalized values outside their normal ranges. The last thing that

1033

<code>mktime</code> does is adjust the components of the <var>brokentime</var>

1034

structure (including the <code>tm_wday</code> and <code>tm_yday</code>).

1035

1036

If the specified broken-down time cannot be represented as a simple time,

1037

<code>mktime</code> returns a value of <code>(time_t)(-1)</code> and does not modify

1038

the contents of <var>brokentime</var>.

1039

1040

Calling <code>mktime</code> also sets the variable <code>tzname</code> with

1041

information about the current time zone. See section <a href="#Time-Zone-Functions">Functions and Variables for Time Zones</a>.

1042

</dd></dl>

1043

1044

<dl>

1045

<dt><a name="index-timelocal"></a>Function: time_t timelocal (struct tm *<var>brokentime</var>)</dt>

1046

<dd>

1047

<code>timelocal</code> is functionally identical to <code>mktime</code>, but more

1048

mnemonically named. Note that it is the inverse of the <code>localtime</code>

1049

function.

1050

1051

Portability note: <code>mktime</code> is essentially universally

1052

available. <code>timelocal</code> is rather rare.

1053

1054

</dd></dl>

1055

1056

<dl>

1057

<dt><a name="index-timegm"></a>Function: time_t timegm (struct tm *<var>brokentime</var>)</dt>

1058

<dd>

1059

<code>timegm</code> is functionally identical to <code>mktime</code> except it

1060

always takes the input values to be Coordinated Universal Time (UTC)

1061

regardless of any local time zone setting.

1062

1063

Note that <code>timegm</code> is the inverse of <code>gmtime</code>.

1064

1065

Portability note: <code>mktime</code> is essentially universally

1066

available. <code>timegm</code> is rather rare. For the most portable

1067

conversion from a UTC broken-down time to a simple time, set

1068

the <code>TZ</code> environment variable to UTC, call <code>mktime</code>, then set

1069

<code>TZ</code> back.

1070

1071

</dd></dl>

1072

1073

1074

1075

1076

1077

1078

1079

1080

1081

1082

1083

1084

1085

1086

1087

1088

1089

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1090

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

1091

1092

</tr></table>

1093

1094

<h3 class="subsection">21.4.4 High Accuracy Clock</h3>

1095

1096

1097

1098

1099

The <code>ntp_gettime</code> and <code>ntp_adjtime</code> functions provide an

1100

interface to monitor and manipulate the system clock to maintain high

1101

accuracy time. For example, you can fine tune the speed of the clock

1102

or synchronize it with another time source.

1103

1104

A typical use of these functions is by a server implementing the Network

1105

Time Protocol to synchronize the clocks of multiple systems and high

1106

precision clocks.

1107

1108

These functions are declared in ‘<tt>sys/timex.h</tt>’.

1109

1110

1111

<dl>

1112

<dt><a name="index-struct-ntptimeval-1"></a>Data Type: struct ntptimeval</dt>

1113

<dd>This structure is used for information about the system clock. It

1114

contains the following members:

1115

1116

<dt> <code>struct timeval time</code></dt>

1117

<dd>This is the current calendar time, expressed as the elapsed time since

1118

the epoch. The <code>struct timeval</code> data type is described in

1119

<a href="#Elapsed-Time">Elapsed Time</a>.

1120

1121

</dd>

1122

<dt> <code>long int maxerror</code></dt>

1123

<dd>This is the maximum error, measured in microseconds. Unless updated

1124

via <code>ntp_adjtime</code> periodically, this value will reach some

1125

platform-specific maximum value.

1126

1127

</dd>

1128

<dt> <code>long int esterror</code></dt>

1129

<dd>This is the estimated error, measured in microseconds. This value can

1130

be set by <code>ntp_adjtime</code> to indicate the estimated offset of the

1131

system clock from the true calendar time.

1132

</dd>

1133

</dl>

1134

</dd></dl>

1135

1136

<dl>

1137

<dt><a name="index-ntp_005fgettime"></a>Function: int ntp_gettime (struct ntptimeval *<var>tptr</var>)</dt>

1138

<dd>The <code>ntp_gettime</code> function sets the structure pointed to by

1139

<var>tptr</var> to current values. The elements of the structure afterwards

1140

contain the values the timer implementation in the kernel assumes. They

1141

might or might not be correct. If they are not a <code>ntp_adjtime</code>

1142

call is necessary.

1143

1144

The return value is <code>0</code> on success and other values on failure. The

1145

following <code>errno</code> error conditions are defined for this function:

1146

1147

1148

<dt> <code>TIME_ERROR</code></dt>

1149

<dd>The precision clock model is not properly set up at the moment, thus the

1150

clock must be considered unsynchronized, and the values should be

1151

treated with care.

1152

</dd>

1153

</dl>

1154

</dd></dl>

1155

1156

1157

<dl>

1158

<dt><a name="index-struct-timex-1"></a>Data Type: struct timex</dt>

1159

<dd>This structure is used to control and monitor the system clock. It

1160

contains the following members:

1161

1162

<dt> <code>unsigned int modes</code></dt>

1163

<dd>This variable controls whether and which values are set. Several

1164

symbolic constants have to be combined with binary or to specify

1165

the effective mode. These constants start with <code>MOD_</code>.

1166

1167

</dd>

1168

<dt> <code>long int offset</code></dt>

1169

<dd>This value indicates the current offset of the system clock from the true

1170

calendar time. The value is given in microseconds. If bit

1171

<code>MOD_OFFSET</code> is set in <code>modes</code>, the offset (and possibly other

1172

dependent values) can be set. The offset’s absolute value must not

1173

exceed <code>MAXPHASE</code>.

1174

1175

1176

</dd>

1177

<dt> <code>long int frequency</code></dt>

1178

<dd>This value indicates the difference in frequency between the true

1179

calendar time and the system clock. The value is expressed as scaled

1180

PPM (parts per million, 0.0001%). The scaling is <code>1 <<

1181

SHIFT_USEC</code>. The value can be set with bit <code>MOD_FREQUENCY</code>, but

1182

the absolute value must not exceed <code>MAXFREQ</code>.

1183

1184

</dd>

1185

<dt> <code>long int maxerror</code></dt>

1186

<dd>This is the maximum error, measured in microseconds. A new value can be

1187

set using bit <code>MOD_MAXERROR</code>. Unless updated via

1188

<code>ntp_adjtime</code> periodically, this value will increase steadily

1189

and reach some platform-specific maximum value.

1190

1191

</dd>

1192

<dt> <code>long int esterror</code></dt>

1193

<dd>This is the estimated error, measured in microseconds. This value can

1194

be set using bit <code>MOD_ESTERROR</code>.

1195

1196

</dd>

1197

<dt> <code>int status</code></dt>

1198

<dd>This variable reflects the various states of the clock machinery. There

1199

are symbolic constants for the significant bits, starting with

1200

<code>STA_</code>. Some of these flags can be updated using the

1201

<code>MOD_STATUS</code> bit.

1202

1203

</dd>

1204

<dt> <code>long int constant</code></dt>

1205

<dd>This value represents the bandwidth or stiffness of the PLL (phase

1206

locked loop) implemented in the kernel. The value can be changed using

1207

bit <code>MOD_TIMECONST</code>.

1208

1209

</dd>

1210

<dt> <code>long int precision</code></dt>

1211

<dd>This value represents the accuracy or the maximum error when reading the

1212

system clock. The value is expressed in microseconds.

1213

1214

</dd>

1215

<dt> <code>long int tolerance</code></dt>

1216

<dd>This value represents the maximum frequency error of the system clock in

1217

scaled PPM. This value is used to increase the <code>maxerror</code> every

1218

second.

1219

1220

</dd>

1221

<dt> <code>struct timeval time</code></dt>

1222

<dd>The current calendar time.

1223

1224

</dd>

1225

1226

<dd>The elapsed time between clock ticks in microseconds. A clock tick is a

1227

periodic timer interrupt on which the system clock is based.

1228

1229

</dd>

1230

<dt> <code>long int ppsfreq</code></dt>

1231

<dd>This is the first of a few optional variables that are present only if

1232

the system clock can use a PPS (pulse per second) signal to discipline

1233

the system clock. The value is expressed in scaled PPM and it denotes

1234

the difference in frequency between the system clock and the PPS signal.

1235

1236

</dd>

1237

<dt> <code>long int jitter</code></dt>

1238

<dd>This value expresses a median filtered average of the PPS signal’s

1239

dispersion in microseconds.

1240

1241

</dd>

1242

<dt> <code>int shift</code></dt>

1243

<dd>This value is a binary exponent for the duration of the PPS calibration

1244

interval, ranging from <code>PPS_SHIFT</code> to <code>PPS_SHIFTMAX</code>.

1245

1246

</dd>

1247

<dt> <code>long int stabil</code></dt>

1248

<dd>This value represents the median filtered dispersion of the PPS

1249

frequency in scaled PPM.

1250

1251

</dd>

1252

<dt> <code>long int jitcnt</code></dt>

1253

<dd>This counter represents the number of pulses where the jitter exceeded

1254

the allowed maximum <code>MAXTIME</code>.

1255

1256

</dd>

1257

<dt> <code>long int calcnt</code></dt>

1258

<dd>This counter reflects the number of successful calibration intervals.

1259

1260

</dd>

1261

<dt> <code>long int errcnt</code></dt>

1262

<dd>This counter represents the number of calibration errors (caused by

1263

large offsets or jitter).

1264

1265

</dd>

1266

<dt> <code>long int stbcnt</code></dt>

1267

<dd>This counter denotes the number of calibrations where the stability

1268

exceeded the threshold.

1269

</dd>

1270

</dl>

1271

</dd></dl>

1272

1273

<dl>

1274

<dt><a name="index-ntp_005fadjtime"></a>Function: int ntp_adjtime (struct timex *<var>tptr</var>)</dt>

1275

<dd>The <code>ntp_adjtime</code> function sets the structure specified by

1276

<var>tptr</var> to current values.

1277

1278

In addition, <code>ntp_adjtime</code> updates some settings to match what you

1279

pass to it in *<var>tptr</var>. Use the <code>modes</code> element of *<var>tptr</var>

1280

to select what settings to update. You can set <code>offset</code>,

1281

<code>freq</code>, <code>maxerror</code>, <code>esterror</code>, <code>status</code>,

1282

<code>constant</code>, and <code>tick</code>.

1283

1284

<code>modes</code> = zero means set nothing.

1285

1286

Only the superuser can update settings.

1287

1288

1289

The return value is <code>0</code> on success and other values on failure. The

1290

following <code>errno</code> error conditions are defined for this function:

1291

1292

1293

<dt> <code>TIME_ERROR</code></dt>

1294

<dd>The high accuracy clock model is not properly set up at the moment, thus the

1295

clock must be considered unsynchronized, and the values should be

1296

treated with care. Another reason could be that the specified new values

1297

are not allowed.

1298

1299

</dd>

1300

<dt> <code>EPERM</code></dt>

1301

<dd>The process specified a settings update, but is not superuser.

1302

1303

</dd>

1304

</dl>

1305

1306

For more details see RFC1305 (Network Time Protocol, Version 3) and

1307

related documents.

1308

1309

Portability note: Early versions of the GNU C library did not

1310

have this function but did have the synonymous <code>adjtimex</code>.

1311

1312

</dd></dl>

1313

1314

1315

1316

1317

1318

1319

1320

1321

1322

1323

1324

1325

1326

1327

1328

1329

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1330

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

1331

1332

</tr></table>

1333

1334

<h3 class="subsection">21.4.5 Formatting Calendar Time</h3>

1335

1336

The functions described in this section format calendar time values as

1337

strings. These functions are declared in the header file ‘<tt>time.h</tt>’.

1338

1339

1340

<dl>

1341

<dt><a name="index-asctime"></a>Function: char * asctime (const struct tm *<var>brokentime</var>)</dt>

1342

<dd>The <code>asctime</code> function converts the broken-down time value that

1343

<var>brokentime</var> points to into a string in a standard format:

1344

1345

<table><tr><td> </td><td><pre class="smallexample">"Tue May 21 13:46:22 1991\n"

1346

</pre></td></tr></table>

1347

1348

The abbreviations for the days of week are: ‘<samp>Sun</samp>’, ‘<samp>Mon</samp>’,

1349

‘<samp>Tue</samp>’, ‘<samp>Wed</samp>’, ‘<samp>Thu</samp>’, ‘<samp>Fri</samp>’, and ‘<samp>Sat</samp>’.

1350

1351

The abbreviations for the months are: ‘<samp>Jan</samp>’, ‘<samp>Feb</samp>’,

1352

‘<samp>Mar</samp>’, ‘<samp>Apr</samp>’, ‘<samp>May</samp>’, ‘<samp>Jun</samp>’, ‘<samp>Jul</samp>’, ‘<samp>Aug</samp>’,

1353

‘<samp>Sep</samp>’, ‘<samp>Oct</samp>’, ‘<samp>Nov</samp>’, and ‘<samp>Dec</samp>’.

1354

1355

The return value points to a statically allocated string, which might be

1356

overwritten by subsequent calls to <code>asctime</code> or <code>ctime</code>.

1357

(But no other library function overwrites the contents of this

1358

string.)

1359

</dd></dl>

1360

1361

<dl>

1362

<dt><a name="index-asctime_005fr"></a>Function: char * asctime_r (const struct tm *<var>brokentime</var>, char *<var>buffer</var>)</dt>

1363

<dd>This function is similar to <code>asctime</code> but instead of placing the

1364

result in a static buffer it writes the string in the buffer pointed to

1365

by the parameter <var>buffer</var>. This buffer should have room

1366

for at least 26 bytes, including the terminating null.

1367

1368

If no error occurred the function returns a pointer to the string the

1369

result was written into, i.e., it returns <var>buffer</var>. Otherwise

1370

return <code>NULL</code>.

1371

</dd></dl>

1372

1373

1374

<dl>

1375

<dt><a name="index-ctime"></a>Function: char * ctime (const time_t *<var>time</var>)</dt>

1376

<dd>The <code>ctime</code> function is similar to <code>asctime</code>, except that you

1377

specify the calendar time argument as a <code>time_t</code> simple time value

1378

rather than in broken-down local time format. It is equivalent to

1379

1380

<table><tr><td> </td><td><pre class="smallexample">asctime (localtime (<var>time</var>))

1381

</pre></td></tr></table>

1382

1383

<code>ctime</code> sets the variable <code>tzname</code>, because <code>localtime</code>

1384

does so. See section <a href="#Time-Zone-Functions">Functions and Variables for Time Zones</a>.

1385

</dd></dl>

1386

1387

<dl>

1388

<dt><a name="index-ctime_005fr"></a>Function: char * ctime_r (const time_t *<var>time</var>, char *<var>buffer</var>)</dt>

1389

<dd>This function is similar to <code>ctime</code>, but places the result in the

1390

string pointed to by <var>buffer</var>. It is equivalent to (written using

1391

gcc extensions, see <a href="../gcc/Statement-Exprs.html#Statement-Exprs">(gcc)Statement Exprs</a> section ‘Statement Exprs’ in <cite>Porting and Using gcc</cite>):

1392

1393

<table><tr><td> </td><td><pre class="smallexample">({ struct tm tm; asctime_r (localtime_r (time, &tm), buf); })

1394

</pre></td></tr></table>

1395

1396

If no error occurred the function returns a pointer to the string the

1397

result was written into, i.e., it returns <var>buffer</var>. Otherwise

1398

return <code>NULL</code>.

1399

</dd></dl>

1400

1401

1402

<dl>

1403

<dt><a name="index-strftime"></a>Function: size_t strftime (char *<var>s</var>, size_t <var>size</var>, const char *<var>template</var>, const struct tm *<var>brokentime</var>)</dt>

1404

<dd>This function is similar to the <code>sprintf</code> function (see section <a href="libc_12.html#Formatted-Input">Formatted Input</a>), but the conversion specifications that can appear in the format

1405

template <var>template</var> are specialized for printing components of the date

1406

and time <var>brokentime</var> according to the locale currently specified for

1407

time conversion (see section <a href="libc_7.html#Locales">Locales and Internationalization</a>).

1408

1409

Ordinary characters appearing in the <var>template</var> are copied to the

1410

output string <var>s</var>; this can include multibyte character sequences.

1411

Conversion specifiers are introduced by a ‘<samp>%</samp>’ character, followed

1412

by an optional flag which can be one of the following. These flags

1413

are all GNU extensions. The first three affect only the output of

1414

numbers:

1415

1416

1417

1418

<dd>The number is padded with spaces.

1419

1420

</dd>

1421

1422

<dd>The number is not padded at all.

1423

1424

</dd>

1425

1426

<dd>The number is padded with zeros even if the format specifies padding

1427

with spaces.

1428

1429

</dd>

1430

1431

<dd>The output uses uppercase characters, but only if this is possible

1432

(see section <a href="libc_4.html#Case-Conversion">Case Conversion</a>).

1433

</dd>

1434

</dl>

1435

1436

The default action is to pad the number with zeros to keep it a constant

1437

width. Numbers that do not have a range indicated below are never

1438

padded, since there is no natural width for them.

1439

1440

Following the flag an optional specification of the width is possible.

1441

This is specified in decimal notation. If the natural size of the

1442

output is of the field has less than the specified number of characters,

1443

the result is written right adjusted and space padded to the given

1444

size.

1445

1446

An optional modifier can follow the optional flag and width

1447

specification. The modifiers, which were first standardized by

1448

POSIX.2-1992 and by ISO C99, are:

1449

1450

1451

1452

<dd>Use the locale’s alternate representation for date and time. This

1453

modifier applies to the <code>%c</code>, <code>%C</code>, <code>%x</code>, <code>%X</code>,

1454

<code>%y</code> and <code>%Y</code> format specifiers. In a Japanese locale, for

1455

example, <code>%Ex</code> might yield a date format based on the Japanese

1456

Emperors’ reigns.

1457

1458

</dd>

1459

1460

<dd>Use the locale’s alternate numeric symbols for numbers. This modifier

1461

applies only to numeric format specifiers.

1462

</dd>

1463

</dl>

1464

1465

If the format supports the modifier but no alternate representation

1466

is available, it is ignored.

1467

1468

The conversion specifier ends with a format specifier taken from the

1469

following list. The whole ‘<samp>%</samp>’ sequence is replaced in the output

1470

string as follows:

1471

1472

1473

1474

<dd>The abbreviated weekday name according to the current locale.

1475

1476

</dd>

1477

1478

<dd>The full weekday name according to the current locale.

1479

1480

</dd>

1481

1482

<dd>The abbreviated month name according to the current locale.

1483

1484

</dd>

1485

1486

<dd>The full month name according to the current locale.

1487

1488

Using <code>%B</code> together with <code>%d</code> produces grammatically

1489

incorrect results for some locales.

1490

1491

</dd>

1492

1493

<dd>The preferred calendar time representation for the current locale.

1494

1495

</dd>

1496

1497

<dd>The century of the year. This is equivalent to the greatest integer not

1498

greater than the year divided by 100.

1499

1500

This format was first standardized by POSIX.2-1992 and by ISO C99.

1501

1502

</dd>

1503

1504

<dd>The day of the month as a decimal number (range <code>01</code> through <code>31</code>).

1505

1506

</dd>

1507

1508

<dd>The date using the format <code>%m/%d/%y</code>.

1509

1510

This format was first standardized by POSIX.2-1992 and by ISO C99.

1511

1512

</dd>

1513

1514

<dd>The day of the month like with <code>%d</code>, but padded with blank (range

1515

<code> 1</code> through <code>31</code>).

1516

1517

This format was first standardized by POSIX.2-1992 and by ISO C99.

1518

1519

</dd>

1520

1521

<dd>The date using the format <code>%Y-%m-%d</code>. This is the form specified

1522

in the ISO 8601 standard and is the preferred form for all uses.

1523

1524

This format was first standardized by ISO C99 and by POSIX.1-2001.

1525

1526

</dd>

1527

1528

<dd>The year corresponding to the ISO week number, but without the century

1529

(range <code>00</code> through <code>99</code>). This has the same format and value

1530

as <code>%y</code>, except that if the ISO week number (see <code>%V</code>) belongs

1531

to the previous or next year, that year is used instead.

1532

1533

This format was first standardized by ISO C99 and by POSIX.1-2001.

1534

1535

</dd>

1536

1537

<dd>The year corresponding to the ISO week number. This has the same format

1538

and value as <code>%Y</code>, except that if the ISO week number (see

1539

<code>%V</code>) belongs to the previous or next year, that year is used

1540

instead.

1541

1542

This format was first standardized by ISO C99 and by POSIX.1-2001

1543

but was previously available as a GNU extension.

1544

1545

</dd>

1546

1547

<dd>The abbreviated month name according to the current locale. The action

1548

is the same as for <code>%b</code>.

1549

1550

This format was first standardized by POSIX.2-1992 and by ISO C99.

1551

1552

</dd>

1553

1554

<dd>The hour as a decimal number, using a 24-hour clock (range <code>00</code> through

1555

<code>23</code>).

1556

1557

</dd>

1558

1559

<dd>The hour as a decimal number, using a 12-hour clock (range <code>01</code> through

1560

<code>12</code>).

1561

1562

</dd>

1563

1564

<dd>The day of the year as a decimal number (range <code>001</code> through <code>366</code>).

1565

1566

</dd>

1567

1568

<dd>The hour as a decimal number, using a 24-hour clock like <code>%H</code>, but

1569

padded with blank (range <code> 0</code> through <code>23</code>).

1570

1571

This format is a GNU extension.

1572

1573

</dd>

1574

1575

<dd>The hour as a decimal number, using a 12-hour clock like <code>%I</code>, but

1576

padded with blank (range <code> 1</code> through <code>12</code>).

1577

1578

This format is a GNU extension.

1579

1580

</dd>

1581

1582

<dd>The month as a decimal number (range <code>01</code> through <code>12</code>).

1583

1584

</dd>

1585

1586

<dd>The minute as a decimal number (range <code>00</code> through <code>59</code>).

1587

1588

</dd>

1589

1590

<dd>A single ‘<samp>\n</samp>’ (newline) character.

1591

1592

This format was first standardized by POSIX.2-1992 and by ISO C99.

1593

1594

</dd>

1595

1596

<dd>Either ‘<samp>AM</samp>’ or ‘<samp>PM</samp>’, according to the given time value; or the

1597

corresponding strings for the current locale. Noon is treated as

1598

‘<samp>PM</samp>’ and midnight as ‘<samp>AM</samp>’. In most locales

1599

‘<samp>AM</samp>’/‘<samp>PM</samp>’ format is not supported, in such cases <code>"%p"</code>

1600

yields an empty string.

1601

1602

</dd>

1603

1604

<dd>Either ‘<samp>am</samp>’ or ‘<samp>pm</samp>’, according to the given time value; or the

1605

corresponding strings for the current locale, printed in lowercase

1606

characters. Noon is treated as ‘<samp>pm</samp>’ and midnight as ‘<samp>am</samp>’. In

1607

most locales ‘<samp>AM</samp>’/‘<samp>PM</samp>’ format is not supported, in such cases

1608

<code>"%P"</code> yields an empty string.

1609

1610

This format is a GNU extension.

1611

1612

</dd>

1613

1614

<dd>The complete calendar time using the AM/PM format of the current locale.

1615

1616

This format was first standardized by POSIX.2-1992 and by ISO C99.

1617

In the POSIX locale, this format is equivalent to <code>%I:%M:%S %p</code>.

1618

1619

</dd>

1620

1621

<dd>The hour and minute in decimal numbers using the format <code>%H:%M</code>.

1622

1623

This format was first standardized by ISO C99 and by POSIX.1-2001

1624

but was previously available as a GNU extension.

1625

1626

</dd>

1627

1628

<dd>The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.

1629

Leap seconds are not counted unless leap second support is available.

1630

1631

This format is a GNU extension.

1632

1633

</dd>

1634

1635

<dd>The seconds as a decimal number (range <code>00</code> through <code>60</code>).

1636

1637

</dd>

1638

1639

<dd>A single ‘<samp>\t</samp>’ (tabulator) character.

1640

1641

This format was first standardized by POSIX.2-1992 and by ISO C99.

1642

1643

</dd>

1644

1645

<dd>The time of day using decimal numbers using the format <code>%H:%M:%S</code>.

1646

1647

This format was first standardized by POSIX.2-1992 and by ISO C99.

1648

1649

</dd>

1650

1651

<dd>The day of the week as a decimal number (range <code>1</code> through

1652

<code>7</code>), Monday being <code>1</code>.

1653

1654

This format was first standardized by POSIX.2-1992 and by ISO C99.

1655

1656

</dd>

1657

1658

<dd>The week number of the current year as a decimal number (range <code>00</code>

1659

through <code>53</code>), starting with the first Sunday as the first day of

1660

the first week. Days preceding the first Sunday in the year are

1661

considered to be in week <code>00</code>.

1662

1663

</dd>

1664

1665

<dd>The ISO 8601:1988 week number as a decimal number (range <code>01</code>

1666

through <code>53</code>). ISO weeks start with Monday and end with Sunday.

1667

Week <code>01</code> of a year is the first week which has the majority of its

1668

days in that year; this is equivalent to the week containing the year’s

1669

first Thursday, and it is also equivalent to the week containing January

1670

4. Week <code>01</code> of a year can contain days from the previous year.

1671

The week before week <code>01</code> of a year is the last week (<code>52</code> or

1672

<code>53</code>) of the previous year even if it contains days from the new

1673

year.

1674

1675

This format was first standardized by POSIX.2-1992 and by ISO C99.

1676

1677

</dd>

1678

1679

<dd>The day of the week as a decimal number (range <code>0</code> through

1680

<code>6</code>), Sunday being <code>0</code>.

1681

1682

</dd>

1683

1684

<dd>The week number of the current year as a decimal number (range <code>00</code>

1685

through <code>53</code>), starting with the first Monday as the first day of

1686

the first week. All days preceding the first Monday in the year are

1687

considered to be in week <code>00</code>.

1688

1689

</dd>

1690

1691

<dd>The preferred date representation for the current locale.

1692

1693

</dd>

1694

1695

<dd>The preferred time of day representation for the current locale.

1696

1697

</dd>

1698

1699

<dd>The year without a century as a decimal number (range <code>00</code> through

1700

<code>99</code>). This is equivalent to the year modulo 100.

1701

1702

</dd>

1703

1704

<dd>The year as a decimal number, using the Gregorian calendar. Years

1705

before the year <code>1</code> are numbered <code>0</code>, <code>-1</code>, and so on.

1706

1707

</dd>

1708

1709

<dd>RFC 822/ISO 8601:1988 style numeric time zone (e.g.,

1710

<code>-0600</code> or <code>+0100</code>), or nothing if no time zone is

1711

determinable.

1712

1713

This format was first standardized by ISO C99 and by POSIX.1-2001

1714

but was previously available as a GNU extension.

1715

1716

In the POSIX locale, a full RFC 822 timestamp is generated by the format

1717

‘<samp>"%a, %d %b %Y %H:%M:%S %z"</samp>’ (or the equivalent

1718

‘<samp>"%a, %d %b %Y %T %z"</samp>’).

1719

1720

</dd>

1721

1722

<dd>The time zone abbreviation (empty if the time zone can’t be determined).

1723

1724

</dd>

1725

1726

<dd>A literal ‘<samp>%</samp>’ character.

1727

</dd>

1728

</dl>

1729

1730

The <var>size</var> parameter can be used to specify the maximum number of

1731

characters to be stored in the array <var>s</var>, including the terminating

1732

null character. If the formatted time requires more than <var>size</var>

1733

characters, <code>strftime</code> returns zero and the contents of the array

1734

<var>s</var> are undefined. Otherwise the return value indicates the

1735

number of characters placed in the array <var>s</var>, not including the

1736

terminating null character.

1737

1738

Warning: This convention for the return value which is prescribed

1739

in ISO C can lead to problems in some situations. For certain

1740

format strings and certain locales the output really can be the empty

1741

string and this cannot be discovered by testing the return value only.

1742

E.g., in most locales the AM/PM time format is not supported (most of

1743

the world uses the 24 hour time representation). In such locales

1744

<code>"%p"</code> will return the empty string, i.e., the return value is

1745

zero. To detect situations like this something similar to the following

1746

code should be used:

1747

1748

<table><tr><td> </td><td><pre class="smallexample">buf[0] = '\1';

1749

len = strftime (buf, bufsize, format, tp);

1750

if (len == 0 && buf[0] != '\0')

1751

{

1752

/* Something went wrong in the strftime call. */

1753

…

1754

}

1755

</pre></td></tr></table>

1756

1757

If <var>s</var> is a null pointer, <code>strftime</code> does not actually write

1758

anything, but instead returns the number of characters it would have written.

1759

1760

According to POSIX.1 every call to <code>strftime</code> implies a call to

1761

<code>tzset</code>. So the contents of the environment variable <code>TZ</code>

1762

is examined before any output is produced.

1763

1764

For an example of <code>strftime</code>, see <a href="#Time-Functions-Example">Time Functions Example</a>.

1765

</dd></dl>

1766

1767

<dl>

1768

<dt><a name="index-wcsftime"></a>Function: size_t wcsftime (wchar_t *<var>s</var>, size_t <var>size</var>, const wchar_t *<var>template</var>, const struct tm *<var>brokentime</var>)</dt>

1769

<dd>The <code>wcsftime</code> function is equivalent to the <code>strftime</code>

1770

function with the difference that it operates on wide character

1771

strings. The buffer where the result is stored, pointed to by <var>s</var>,

1772

must be an array of wide characters. The parameter <var>size</var> which

1773

specifies the size of the output buffer gives the number of wide

1774

character, not the number of bytes.

1775

1776

Also the format string <var>template</var> is a wide character string. Since

1777

all characters needed to specify the format string are in the basic

1778

character set it is portably possible to write format strings in the C

1779

source code using the <code>L"…"</code> notation. The parameter

1780

<var>brokentime</var> has the same meaning as in the <code>strftime</code> call.

1781

1782

The <code>wcsftime</code> function supports the same flags, modifiers, and

1783

format specifiers as the <code>strftime</code> function.

1784

1785

The return value of <code>wcsftime</code> is the number of wide characters

1786

stored in <code>s</code>. When more characters would have to be written than

1787

can be placed in the buffer <var>s</var> the return value is zero, with the

1788

same problems indicated in the <code>strftime</code> documentation.

1789

</dd></dl>

1790

1791

1792

1793

1794

1795

1796

1797

1798

1799

1800

1801

1802

1803

1804

1805

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1806

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

1807

1808

</tr></table>

1809

1810

<h3 class="subsection">21.4.6 Convert textual time and date information back</h3>

1811

1812

The ISO C standard does not specify any functions which can convert

1813

the output of the <code>strftime</code> function back into a binary format.

1814

This led to a variety of more-or-less successful implementations with

1815

different interfaces over the years. Then the Unix standard was

1816

extended by the addition of two functions: <code>strptime</code> and

1817

<code>getdate</code>. Both have strange interfaces but at least they are

1818

widely available.

1819

1820

1821

<tr><td align="left" valign="top"><a href="#Low_002dLevel-Time-String-Parsing">21.4.6.1 Interpret string according to given format</a></td><td>  </td><td align="left" valign="top"></td></tr>

1822

<tr><td align="left" valign="top"><a href="#General-Time-String-Parsing">21.4.6.2 A More User-friendly Way to Parse Times and Dates</a></td><td>  </td><td align="left" valign="top"> User-friendly function to parse data and

1823

time strings.

1824

</td></tr>

1825

</table>

1826

1827

1828

1829

1830

1831

1832

1833

1834

1835

1836

1837

1838

1839

1840

1841

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

1842

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

1843

1844

</tr></table>

1845

1846

<h4 class="subsubsection">21.4.6.1 Interpret string according to given format</h4>

1847

1848

The first function is rather low-level. It is nevertheless frequently

1849

used in software since it is better known. Its interface and

1850

implementation are heavily influenced by the <code>getdate</code> function,

1851

which is defined and implemented in terms of calls to <code>strptime</code>.

1852

1853

<dl>

1854

<dt><a name="index-strptime"></a>Function: char * strptime (const char *<var>s</var>, const char *<var>fmt</var>, struct tm *<var>tp</var>)</dt>

1855

<dd>The <code>strptime</code> function parses the input string <var>s</var> according

1856

to the format string <var>fmt</var> and stores its results in the

1857

structure <var>tp</var>.

1858

1859

The input string could be generated by a <code>strftime</code> call or

1860

obtained any other way. It does not need to be in a human-recognizable

1861

format; e.g. a date passed as <code>"02:1999:9"</code> is acceptable, even

1862

though it is ambiguous without context. As long as the format string

1863

<var>fmt</var> matches the input string the function will succeed.

1864

1865

The user has to make sure, though, that the input can be parsed in a

1866

unambiguous way. The string <code>"1999112"</code> can be parsed using the

1867

format <code>"%Y%m%d"</code> as 1999-1-12, 1999-11-2, or even 19991-1-2. It

1868

is necessary to add appropriate separators to reliably get results.

1869

1870

The format string consists of the same components as the format string

1871

of the <code>strftime</code> function. The only difference is that the flags

1872

<code>_</code>, <code>-</code>, <code>0</code>, and <code>^</code> are not allowed.

1873

Several of the distinct formats of <code>strftime</code> do the same work in

1874

<code>strptime</code> since differences like case of the input do not matter.

1875

For reasons of symmetry all formats are supported, though.

1876

1877

The modifiers <code>E</code> and <code>O</code> are also allowed everywhere the

1878

<code>strftime</code> function allows them.

1879

1880

The formats are:

1881

1882

1883

1884

1885

<dd>The weekday name according to the current locale, in abbreviated form or

1886

the full name.

1887

1888

</dd>

1889

1890

1891

1892

<dd>The month name according to the current locale, in abbreviated form or

1893

the full name.

1894

1895

</dd>

1896

1897

<dd>The date and time representation for the current locale.

1898

1899

</dd>

1900

1901

<dd>Like <code>%c</code> but the locale’s alternative date and time format is used.

1902

1903

</dd>

1904

1905

<dd>The century of the year.

1906

1907

It makes sense to use this format only if the format string also

1908

contains the <code>%y</code> format.

1909

1910

</dd>

1911

1912

<dd>The locale’s representation of the period.

1913

1914

Unlike <code>%C</code> it sometimes makes sense to use this format since some

1915

cultures represent years relative to the beginning of eras instead of

1916

using the Gregorian years.

1917

1918

</dd>

1919

1920

1921

<dd>The day of the month as a decimal number (range <code>1</code> through <code>31</code>).

1922

Leading zeroes are permitted but not required.

1923

1924

</dd>

1925

1926

1927

<dd>Same as <code>%d</code> but using the locale’s alternative numeric symbols.

1928

1929

Leading zeroes are permitted but not required.

1930

1931

</dd>

1932

1933

<dd>Equivalent to <code>%m/%d/%y</code>.

1934

1935

</dd>

1936

1937

<dd>Equivalent to <code>%Y-%m-%d</code>, which is the ISO 8601 date

1938

format.

1939

1940

This is a GNU extension following an ISO C99 extension to

1941

<code>strftime</code>.

1942

1943

</dd>

1944

1945

<dd>The year corresponding to the ISO week number, but without the century

1946

(range <code>00</code> through <code>99</code>).

1947

1948

Note: Currently, this is not fully implemented. The format is

1949

recognized, input is consumed but no field in <var>tm</var> is set.

1950

1951

This format is a GNU extension following a GNU extension of <code>strftime</code>.

1952

1953

</dd>

1954

1955

<dd>The year corresponding to the ISO week number.

1956

1957

Note: Currently, this is not fully implemented. The format is

1958

recognized, input is consumed but no field in <var>tm</var> is set.

1959

1960

This format is a GNU extension following a GNU extension of <code>strftime</code>.

1961

1962

</dd>

1963

1964

1965

<dd>The hour as a decimal number, using a 24-hour clock (range <code>00</code> through

1966

<code>23</code>).

1967

1968

<code>%k</code> is a GNU extension following a GNU extension of <code>strftime</code>.

1969

1970

</dd>

1971

1972

<dd>Same as <code>%H</code> but using the locale’s alternative numeric symbols.

1973

1974

</dd>

1975

1976

1977

<dd>The hour as a decimal number, using a 12-hour clock (range <code>01</code> through

1978

<code>12</code>).

1979

1980

<code>%l</code> is a GNU extension following a GNU extension of <code>strftime</code>.

1981

1982

</dd>

1983

1984

<dd>Same as <code>%I</code> but using the locale’s alternative numeric symbols.

1985

1986

</dd>

1987

1988

<dd>The day of the year as a decimal number (range <code>1</code> through <code>366</code>).

1989

1990

Leading zeroes are permitted but not required.

1991

1992

</dd>

1993

1994

<dd>The month as a decimal number (range <code>1</code> through <code>12</code>).

1995

1996

Leading zeroes are permitted but not required.

1997

1998

</dd>

1999

2000

<dd>Same as <code>%m</code> but using the locale’s alternative numeric symbols.

2001

2002

</dd>

2003

2004

<dd>The minute as a decimal number (range <code>0</code> through <code>59</code>).

2005

2006

Leading zeroes are permitted but not required.

2007

2008

</dd>

2009

2010

<dd>Same as <code>%M</code> but using the locale’s alternative numeric symbols.

2011

2012

</dd>

2013

2014

2015

<dd>Matches any white space.

2016

2017

</dd>

2018

2019

2020

<dd>The locale-dependent equivalent to ‘<samp>AM</samp>’ or ‘<samp>PM</samp>’.

2021

2022

This format is not useful unless <code>%I</code> or <code>%l</code> is also used.

2023

Another complication is that the locale might not define these values at

2024

all and therefore the conversion fails.

2025

2026

<code>%P</code> is a GNU extension following a GNU extension to <code>strftime</code>.

2027

2028

</dd>

2029

2030

<dd>The complete time using the AM/PM format of the current locale.

2031

2032

A complication is that the locale might not define this format at all

2033

and therefore the conversion fails.

2034

2035

</dd>

2036

2037

<dd>The hour and minute in decimal numbers using the format <code>%H:%M</code>.

2038

2039

<code>%R</code> is a GNU extension following a GNU extension to <code>strftime</code>.

2040

2041

</dd>

2042

2043

<dd>The number of seconds since the epoch, i.e., since 1970-01-01 00:00:00 UTC.

2044

Leap seconds are not counted unless leap second support is available.

2045

2046

<code>%s</code> is a GNU extension following a GNU extension to <code>strftime</code>.

2047

2048

</dd>

2049

2050

<dd>The seconds as a decimal number (range <code>0</code> through <code>60</code>).

2051

2052

Leading zeroes are permitted but not required.

2053

2054

NB: The Unix specification says the upper bound on this value

2055

is <code>61</code>, a result of a decision to allow double leap seconds. You

2056

will not see the value <code>61</code> because no minute has more than one

2057

leap second, but the myth persists.

2058

2059

</dd>

2060

2061

<dd>Same as <code>%S</code> but using the locale’s alternative numeric symbols.

2062

2063

</dd>

2064

2065

<dd>Equivalent to the use of <code>%H:%M:%S</code> in this place.

2066

2067

</dd>

2068

2069

<dd>The day of the week as a decimal number (range <code>1</code> through

2070

<code>7</code>), Monday being <code>1</code>.

2071

2072

Leading zeroes are permitted but not required.

2073

2074

Note: Currently, this is not fully implemented. The format is

2075

recognized, input is consumed but no field in <var>tm</var> is set.

2076

2077

</dd>

2078

2079

<dd>The week number of the current year as a decimal number (range <code>0</code>

2080

through <code>53</code>).

2081

2082

Leading zeroes are permitted but not required.

2083

2084

</dd>

2085

2086

<dd>Same as <code>%U</code> but using the locale’s alternative numeric symbols.

2087

2088

</dd>

2089

2090

<dd>The ISO 8601:1988 week number as a decimal number (range <code>1</code>

2091

through <code>53</code>).

2092

2093

Leading zeroes are permitted but not required.

2094

2095

Note: Currently, this is not fully implemented. The format is

2096

recognized, input is consumed but no field in <var>tm</var> is set.

2097

2098

</dd>

2099

2100

<dd>The day of the week as a decimal number (range <code>0</code> through

2101

<code>6</code>), Sunday being <code>0</code>.

2102

2103

Leading zeroes are permitted but not required.

2104

2105

Note: Currently, this is not fully implemented. The format is

2106

recognized, input is consumed but no field in <var>tm</var> is set.

2107

2108

</dd>

2109

2110

<dd>Same as <code>%w</code> but using the locale’s alternative numeric symbols.

2111

2112

</dd>

2113

2114

<dd>The week number of the current year as a decimal number (range <code>0</code>

2115

through <code>53</code>).

2116

2117

Leading zeroes are permitted but not required.

2118

2119

Note: Currently, this is not fully implemented. The format is

2120

recognized, input is consumed but no field in <var>tm</var> is set.

2121

2122

</dd>

2123

2124

<dd>Same as <code>%W</code> but using the locale’s alternative numeric symbols.

2125

2126

</dd>

2127

2128

<dd>The date using the locale’s date format.

2129

2130

</dd>

2131

2132

<dd>Like <code>%x</code> but the locale’s alternative data representation is used.

2133

2134

</dd>

2135

2136

<dd>The time using the locale’s time format.

2137

2138

</dd>

2139

2140

<dd>Like <code>%X</code> but the locale’s alternative time representation is used.

2141

2142

</dd>

2143

2144

<dd>The year without a century as a decimal number (range <code>0</code> through

2145

<code>99</code>).

2146

2147

Leading zeroes are permitted but not required.

2148

2149

Note that it is questionable to use this format without

2150

the <code>%C</code> format. The <code>strptime</code> function does regard input

2151

values in the range 68 to 99 as the years 1969 to

2152

1999 and the values 0 to 68 as the years

2153

2000 to 2068. But maybe this heuristic fails for some

2154

input data.

2155

2156

Therefore it is best to avoid <code>%y</code> completely and use <code>%Y</code>

2157

instead.

2158

2159

</dd>

2160

2161

<dd>The offset from <code>%EC</code> in the locale’s alternative representation.

2162

2163

</dd>

2164

2165

<dd>The offset of the year (from <code>%C</code>) using the locale’s alternative

2166

numeric symbols.

2167

2168

</dd>

2169

2170

<dd>The year as a decimal number, using the Gregorian calendar.

2171

2172

</dd>

2173

2174

<dd>The full alternative year representation.

2175

2176

</dd>

2177

2178

<dd>The offset from GMT in ISO 8601/RFC822 format.

2179

2180

</dd>

2181

2182

<dd>The timezone name.

2183

2184

Note: Currently, this is not fully implemented. The format is

2185

recognized, input is consumed but no field in <var>tm</var> is set.

2186

2187

</dd>

2188

2189

<dd>A literal ‘<samp>%</samp>’ character.

2190

</dd>

2191

</dl>

2192

2193

All other characters in the format string must have a matching character

2194

in the input string. Exceptions are white spaces in the input string

2195

which can match zero or more whitespace characters in the format string.

2196

2197

Portability Note: The XPG standard advises applications to use

2198

at least one whitespace character (as specified by <code>isspace</code>) or

2199

other non-alphanumeric characters between any two conversion

2200

specifications. The GNU C Library does not have this limitation but

2201

other libraries might have trouble parsing formats like

2202

<code>"%d%m%Y%H%M%S"</code>.

2203

2204

The <code>strptime</code> function processes the input string from right to

2205

left. Each of the three possible input elements (white space, literal,

2206

or format) are handled one after the other. If the input cannot be

2207

matched to the format string the function stops. The remainder of the

2208

format and input strings are not processed.

2209

2210

The function returns a pointer to the first character it was unable to

2211

process. If the input string contains more characters than required by

2212

the format string the return value points right after the last consumed

2213

input character. If the whole input string is consumed the return value

2214

points to the <code>NULL</code> byte at the end of the string. If an error

2215

occurs, i.e., <code>strptime</code> fails to match all of the format string,

2216

the function returns <code>NULL</code>.

2217

</dd></dl>

2218

2219

The specification of the function in the XPG standard is rather vague,

2220

leaving out a few important pieces of information. Most importantly, it

2221

does not specify what happens to those elements of <var>tm</var> which are

2222

not directly initialized by the different formats. The

2223

implementations on different Unix systems vary here.

2224

2225

The GNU libc implementation does not touch those fields which are not

2226

directly initialized. Exceptions are the <code>tm_wday</code> and

2227

<code>tm_yday</code> elements, which are recomputed if any of the year, month,

2228

or date elements changed. This has two implications:

2229

2230

<ul>

2231

<li>

2232

Before calling the <code>strptime</code> function for a new input string, you

2233

should prepare the <var>tm</var> structure you pass. Normally this will mean

2234

initializing all values are to zero. Alternatively, you can set all

2235

fields to values like <code>INT_MAX</code>, allowing you to determine which

2236

elements were set by the function call. Zero does not work here since

2237

it is a valid value for many of the fields.

2238

2239

Careful initialization is necessary if you want to find out whether a

2240

certain field in <var>tm</var> was initialized by the function call.

2241

2242

</li><li>

2243

You can construct a <code>struct tm</code> value with several consecutive

2244

<code>strptime</code> calls. A useful application of this is e.g. the parsing

2245

of two separate strings, one containing date information and the other

2246

time information. By parsing one after the other without clearing the

2247

structure in-between, you can construct a complete broken-down time.

2248

</li></ul>

2249

2250

The following example shows a function which parses a string which is

2251

contains the date information in either US style or ISO 8601 form:

2252

2253

<table><tr><td> </td><td><pre class="smallexample">const char *

2254

parse_date (const char *input, struct tm *tm)

2255

{

2256

const char *cp;

2257

2258

/* First clear the result structure. */

2259

memset (tm, '\0', sizeof (*tm));

2260

2261

/* Try the ISO format first. */

2262

cp = strptime (input, "%F", tm);

2263

if (cp == NULL)

2264

{

2265

/* Does not match. Try the US form. */

2266

cp = strptime (input, "%D", tm);

2267

}

2268

2269

return cp;

2270

}

2271

</pre></td></tr></table>

2272

2273

2274

2275

2276

2277

2278

2279

2280

2281

2282

2283

2284

2285

2286

2287

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2288

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2289

2290

</tr></table>

2291

2292

<h4 class="subsubsection">21.4.6.2 A More User-friendly Way to Parse Times and Dates</h4>

2293

2294

The Unix standard defines another function for parsing date strings.

2295

The interface is weird, but if the function happens to suit your

2296

application it is just fine. It is problematic to use this function

2297

in multi-threaded programs or libraries, since it returns a pointer to

2298

a static variable, and uses a global variable and global state (an

2299

environment variable).

2300

2301

<dl>

2302

<dt><a name="index-getdate_005ferr"></a>Variable: getdate_err</dt>

2303

<dd>This variable of type <code>int</code> contains the error code of the last

2304

unsuccessful call to <code>getdate</code>. Defined values are:

2305

2306

2307

2308

<dd>The environment variable <code>DATEMSK</code> is not defined or null.

2309

</dd>

2310

2311

<dd>The template file denoted by the <code>DATEMSK</code> environment variable

2312

cannot be opened.

2313

</dd>

2314

2315

<dd>Information about the template file cannot retrieved.

2316

</dd>

2317

2318

<dd>The template file is not a regular file.

2319

</dd>

2320

2321

<dd>An I/O error occurred while reading the template file.

2322

</dd>

2323

2324

<dd>Not enough memory available to execute the function.

2325

</dd>

2326

2327

<dd>The template file contains no matching template.

2328

</dd>

2329

2330

<dd>The input date is invalid, but would match a template otherwise. This

2331

includes dates like February 31st, and dates which cannot be represented

2332

in a <code>time_t</code> variable.

2333

</dd>

2334

</dl>

2335

</dd></dl>

2336

2337

<dl>

2338

<dt><a name="index-getdate"></a>Function: struct tm * getdate (const char *<var>string</var>)</dt>

2339

<dd>The interface to <code>getdate</code> is the simplest possible for a function

2340

to parse a string and return the value. <var>string</var> is the input

2341

string and the result is returned in a statically-allocated variable.

2342

2343

The details about how the string is processed are hidden from the user.

2344

In fact, they can be outside the control of the program. Which formats

2345

are recognized is controlled by the file named by the environment

2346

variable <code>DATEMSK</code>. This file should contain

2347

lines of valid format strings which could be passed to <code>strptime</code>.

2348

2349

The <code>getdate</code> function reads these format strings one after the

2350

other and tries to match the input string. The first line which

2351

completely matches the input string is used.

2352

2353

Elements not initialized through the format string retain the values

2354

present at the time of the <code>getdate</code> function call.

2355

2356

The formats recognized by <code>getdate</code> are the same as for

2357

<code>strptime</code>. See above for an explanation. There are only a few

2358

extensions to the <code>strptime</code> behavior:

2359

2360

<ul>

2361

<li>

2362

If the <code>%Z</code> format is given the broken-down time is based on the

2363

current time of the timezone matched, not of the current timezone of the

2364

runtime environment.

2365

2366

Note: This is not implemented (currently). The problem is that

2367

timezone names are not unique. If a fixed timezone is assumed for a

2368

given string (say <code>EST</code> meaning US East Coast time), then uses for

2369

countries other than the USA will fail. So far we have found no good

2370

solution to this.

2371

2372

</li><li>

2373

If only the weekday is specified the selected day depends on the current

2374

date. If the current weekday is greater or equal to the <code>tm_wday</code>

2375

value the current week’s day is chosen, otherwise the day next week is chosen.

2376

2377

</li><li>

2378

A similar heuristic is used when only the month is given and not the

2379

year. If the month is greater than or equal to the current month, then

2380

the current year is used. Otherwise it wraps to next year. The first

2381

day of the month is assumed if one is not explicitly specified.

2382

2383

</li><li>

2384

The current hour, minute, and second are used if the appropriate value is

2385

not set through the format.

2386

2387

</li><li>

2388

If no date is given tomorrow’s date is used if the time is

2389

smaller than the current time. Otherwise today’s date is taken.

2390

</li></ul>

2391

2392

It should be noted that the format in the template file need not only

2393

contain format elements. The following is a list of possible format

2394

strings (taken from the Unix standard):

2395

2396

<table><tr><td> </td><td><pre class="smallexample">%m

2397

%A %B %d, %Y %H:%M:%S

2398

2399

2400

%m/%d/%y %I %p

2401

%d,%m,%Y %H:%M

2402

at %A the %dst of %B in %Y

2403

run job at %I %p,%B %dnd

2404

%A den %d. %B %Y %H.%M Uhr

2405

</pre></td></tr></table>

2406

2407

As you can see, the template list can contain very specific strings like

2408

<code>run job at %I %p,%B %dnd</code>. Using the above list of templates and

2409

assuming the current time is Mon Sep 22 12:19:47 EDT 1986 we can obtain the

2410

following results for the given input.

2411

2412

<table>

2413

<tr><td>Input</td><td>Match</td><td>Result</td></tr>

2414

2415

2416

2417

<tr><td>September</td><td>%B</td><td>Mon Sep 1 12:19:47 EDT 1986</td></tr>

2418

<tr><td>January</td><td>%B</td><td>Thu Jan 1 12:19:47 EST 1987</td></tr>

2419

<tr><td>December</td><td>%B</td><td>Mon Dec 1 12:19:47 EST 1986</td></tr>

2420

2421

2422

2423

2424

2425

2426

2427

2428

</table>

2429

2430

The return value of the function is a pointer to a static variable of

2431

type <code>struct tm</code>, or a null pointer if an error occurred. The

2432

result is only valid until the next <code>getdate</code> call, making this

2433

function unusable in multi-threaded applications.

2434

2435

The <code>errno</code> variable is not changed. Error conditions are

2436

stored in the global variable <code>getdate_err</code>. See the

2437

description above for a list of the possible error values.

2438

2439

Warning: The <code>getdate</code> function should never be

2440

used in SUID-programs. The reason is obvious: using the

2441

<code>DATEMSK</code> environment variable you can get the function to open

2442

any arbitrary file and chances are high that with some bogus input

2443

(such as a binary file) the program will crash.

2444

</dd></dl>

2445

2446

<dl>

2447

<dt><a name="index-getdate_005fr"></a>Function: int getdate_r (const char *<var>string</var>, struct tm *<var>tp</var>)</dt>

2448

<dd>The <code>getdate_r</code> function is the reentrant counterpart of

2449

<code>getdate</code>. It does not use the global variable <code>getdate_err</code>

2450

to signal an error, but instead returns an error code. The same error

2451

codes as described in the <code>getdate_err</code> documentation above are

2452

used, with 0 meaning success.

2453

2454

Moreover, <code>getdate_r</code> stores the broken-down time in the variable

2455

of type <code>struct tm</code> pointed to by the second argument, rather than

2456

in a static variable.

2457

2458

This function is not defined in the Unix standard. Nevertheless it is

2459

available on some other Unix systems as well.

2460

2461

The warning against using <code>getdate</code> in SUID-programs applies to

2462

<code>getdate_r</code> as well.

2463

</dd></dl>

2464

2465

2466

2467

2468

2469

2470

2471

2472

2473

2474

2475

2476

2477

2478

2479

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2480

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2481

2482

</tr></table>

2483

2484

<h3 class="subsection">21.4.7 Specifying the Time Zone with <code>TZ</code></h3>

2485

2486

In POSIX systems, a user can specify the time zone by means of the

2487

<code>TZ</code> environment variable. For information about how to set

2488

environment variables, see <a href="libc_25.html#Environment-Variables">Environment Variables</a>. The functions

2489

for accessing the time zone are declared in ‘<tt>time.h</tt>’.

2490

2491

2492

2493

You should not normally need to set <code>TZ</code>. If the system is

2494

configured properly, the default time zone will be correct. You might

2495

set <code>TZ</code> if you are using a computer over a network from a

2496

different time zone, and would like times reported to you in the time

2497

zone local to you, rather than what is local to the computer.

2498

2499

In POSIX.1 systems the value of the <code>TZ</code> variable can be in one of

2500

three formats. With the GNU C library, the most common format is the

2501

last one, which can specify a selection from a large database of time

2502

zone information for many regions of the world. The first two formats

2503

are used to describe the time zone information directly, which is both

2504

more cumbersome and less precise. But the POSIX.1 standard only

2505

specifies the details of the first two formats, so it is good to be

2506

familiar with them in case you come across a POSIX.1 system that doesn’t

2507

support a time zone information database.

2508

2509

The first format is used when there is no Daylight Saving Time (or

2510

summer time) in the local time zone:

2511

2512

<table><tr><td> </td><td><pre class="smallexample"><var>std</var> <var>offset</var>

2513

</pre></td></tr></table>

2514

2515

The <var>std</var> string specifies the name of the time zone. It must be

2516

three or more characters long and must not contain a leading colon,

2517

embedded digits, commas, nor plus and minus signs. There is no space

2518

character separating the time zone name from the <var>offset</var>, so these

2519

restrictions are necessary to parse the specification correctly.

2520

2521

The <var>offset</var> specifies the time value you must add to the local time

2522

to get a Coordinated Universal Time value. It has syntax like

2523

[<code>+</code>|<code>-</code>]<var>hh</var>[<code>:</code><var>mm</var>[<code>:</code><var>ss</var>]]. This

2524

is positive if the local time zone is west of the Prime Meridian and

2525

negative if it is east. The hour must be between <code>0</code> and

2526

<code>23</code>, and the minute and seconds between <code>0</code> and <code>59</code>.

2527

2528

For example, here is how we would specify Eastern Standard Time, but

2529

without any Daylight Saving Time alternative:

2530

2531

<table><tr><td> </td><td><pre class="smallexample">EST+5

2532

</pre></td></tr></table>

2533

2534

The second format is used when there is Daylight Saving Time:

2535

2536

<table><tr><td> </td><td><pre class="smallexample"><var>std</var> <var>offset</var> <var>dst</var> [<var>offset</var>]<code>,</code><var>start</var>[<code>/</code><var>time</var>]<code>,</code><var>end</var>[<code>/</code><var>time</var>]

2537

</pre></td></tr></table>

2538

2539

The initial <var>std</var> and <var>offset</var> specify the standard time zone, as

2540

described above. The <var>dst</var> string and <var>offset</var> specify the name

2541

and offset for the corresponding Daylight Saving Time zone; if the

2542

<var>offset</var> is omitted, it defaults to one hour ahead of standard time.

2543

2544

The remainder of the specification describes when Daylight Saving Time is

2545

in effect. The <var>start</var> field is when Daylight Saving Time goes into

2546

effect and the <var>end</var> field is when the change is made back to standard

2547

time. The following formats are recognized for these fields:

2548

2549

2550

2551

<dd>This specifies the Julian day, with <var>n</var> between <code>1</code> and <code>365</code>.

2552

February 29 is never counted, even in leap years.

2553

2554

</dd>

2555

2556

<dd>This specifies the Julian day, with <var>n</var> between <code>0</code> and <code>365</code>.

2557

February 29 is counted in leap years.

2558

2559

</dd>

2560

2561

<dd>This specifies day <var>d</var> of week <var>w</var> of month <var>m</var>. The day

2562

<var>d</var> must be between <code>0</code> (Sunday) and <code>6</code>. The week

2563

<var>w</var> must be between <code>1</code> and <code>5</code>; week <code>1</code> is the

2564

first week in which day <var>d</var> occurs, and week <code>5</code> specifies the

2565

last <var>d</var> day in the month. The month <var>m</var> should be

2566

between <code>1</code> and <code>12</code>.

2567

</dd>

2568

</dl>

2569

2570

The <var>time</var> fields specify when, in the local time currently in

2571

effect, the change to the other time occurs. If omitted, the default is

2572

<code>02:00:00</code>.

2573

2574

For example, here is how you would specify the Eastern time zone in the

2575

United States, including the appropriate Daylight Saving Time and its dates

2576

of applicability. The normal offset from UTC is 5 hours; since this is

2577

west of the prime meridian, the sign is positive. Summer time begins on

2578

the first Sunday in April at 2:00am, and ends on the last Sunday in October

2579

at 2:00am.

2580

2581

<table><tr><td> </td><td><pre class="smallexample">EST+5EDT,M4.1.0/2,M10.5.0/2

2582

</pre></td></tr></table>

2583

2584

The schedule of Daylight Saving Time in any particular jurisdiction has

2585

changed over the years. To be strictly correct, the conversion of dates

2586

and times in the past should be based on the schedule that was in effect

2587

then. However, this format has no facilities to let you specify how the

2588

schedule has changed from year to year. The most you can do is specify

2589

one particular schedule—usually the present day schedule—and this is

2590

used to convert any date, no matter when. For precise time zone

2591

specifications, it is best to use the time zone information database

2592

(see below).

2593

2594

The third format looks like this:

2595

2596

<table><tr><td> </td><td><pre class="smallexample">:<var>characters</var>

2597

</pre></td></tr></table>

2598

2599

Each operating system interprets this format differently; in the GNU C

2600

library, <var>characters</var> is the name of a file which describes the time

2601

zone.

2602

2603

2604

2605

If the <code>TZ</code> environment variable does not have a value, the

2606

operation chooses a time zone by default. In the GNU C library, the

2607

default time zone is like the specification ‘<samp>TZ=:/etc/localtime</samp>’

2608

(or ‘<samp>TZ=:/usr/local/etc/localtime</samp>’, depending on how GNU C library

2609

was configured; see section <a href="libc_36.html#Installation">Installing the GNU C Library</a>). Other C libraries use their own

2610

rule for choosing the default time zone, so there is little we can say

2611

about them.

2612

2613

2614

2615

2616

If <var>characters</var> begins with a slash, it is an absolute file name;

2617

otherwise the library looks for the file

2618

‘<tt>/share/lib/zoneinfo/<var>characters</var></tt>’. The ‘<tt>zoneinfo</tt>’

2619

directory contains data files describing local time zones in many

2620

different parts of the world. The names represent major cities, with

2621

subdirectories for geographical areas; for example,

2622

‘<tt>America/New_York</tt>’, ‘<tt>Europe/London</tt>’, ‘<tt>Asia/Hong_Kong</tt>’.

2623

These data files are installed by the system administrator, who also

2624

sets ‘<tt>/etc/localtime</tt>’ to point to the data file for the local time

2625

zone. The GNU C library comes with a large database of time zone

2626

information for most regions of the world, which is maintained by a

2627

community of volunteers and put in the public domain.

2628

2629

2630

2631

2632

2633

2634

2635

2636

2637

2638

2639

2640

2641

2642

2643

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2644

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2645

2646

</tr></table>

2647

2648

<h3 class="subsection">21.4.8 Functions and Variables for Time Zones</h3>

2649

2650

<dl>

2651

<dt><a name="index-tzname"></a>Variable: char * tzname [2]</dt>

2652

<dd>The array <code>tzname</code> contains two strings, which are the standard

2653

names of the pair of time zones (standard and Daylight

2654

Saving) that the user has selected. <code>tzname[0]</code> is the name of

2655

the standard time zone (for example, <code>"EST"</code>), and <code>tzname[1]</code>

2656

is the name for the time zone when Daylight Saving Time is in use (for

2657

example, <code>"EDT"</code>). These correspond to the <var>std</var> and <var>dst</var>

2658

strings (respectively) from the <code>TZ</code> environment variable. If

2659

Daylight Saving Time is never used, <code>tzname[1]</code> is the empty string.

2660

2661

The <code>tzname</code> array is initialized from the <code>TZ</code> environment

2662

variable whenever <code>tzset</code>, <code>ctime</code>, <code>strftime</code>,

2663

<code>mktime</code>, or <code>localtime</code> is called. If multiple abbreviations

2664

have been used (e.g. <code>"EWT"</code> and <code>"EDT"</code> for U.S. Eastern War

2665

Time and Eastern Daylight Time), the array contains the most recent

2666

abbreviation.

2667

2668

The <code>tzname</code> array is required for POSIX.1 compatibility, but in

2669

GNU programs it is better to use the <code>tm_zone</code> member of the

2670

broken-down time structure, since <code>tm_zone</code> reports the correct

2671

abbreviation even when it is not the latest one.

2672

2673

Though the strings are declared as <code>char *</code> the user must refrain

2674

from modifying these strings. Modifying the strings will almost certainly

2675

lead to trouble.

2676

2677

</dd></dl>

2678

2679

<dl>

2680

<dt><a name="index-tzset"></a>Function: void tzset (void)</dt>

2681

<dd>The <code>tzset</code> function initializes the <code>tzname</code> variable from

2682

the value of the <code>TZ</code> environment variable. It is not usually

2683

necessary for your program to call this function, because it is called

2684

automatically when you use the other time conversion functions that

2685

depend on the time zone.

2686

</dd></dl>

2687

2688

The following variables are defined for compatibility with System V

2689

Unix. Like <code>tzname</code>, these variables are set by calling

2690

<code>tzset</code> or the other time conversion functions.

2691

2692

<dl>

2693

<dt><a name="index-timezone"></a>Variable: long int timezone</dt>

2694

<dd>This contains the difference between UTC and the latest local standard

2695

time, in seconds west of UTC. For example, in the U.S. Eastern time

2696

zone, the value is <code>5*60*60</code>. Unlike the <code>tm_gmtoff</code> member

2697

of the broken-down time structure, this value is not adjusted for

2698

daylight saving, and its sign is reversed. In GNU programs it is better

2699

to use <code>tm_gmtoff</code>, since it contains the correct offset even when

2700

it is not the latest one.

2701

</dd></dl>

2702

2703

<dl>

2704

<dt><a name="index-daylight"></a>Variable: int daylight</dt>

2705

<dd>This variable has a nonzero value if Daylight Saving Time rules apply.

2706

A nonzero value does not necessarily mean that Daylight Saving Time is

2707

now in effect; it means only that Daylight Saving Time is sometimes in

2708

effect.

2709

</dd></dl>

2710

2711

2712

2713

2714

2715

2716

2717

2718

2719

2720

2721

2722

2723

2724

2725

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2726

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2727

2728

</tr></table>

2729

2730

<h3 class="subsection">21.4.9 Time Functions Example</h3>

2731

2732

Here is an example program showing the use of some of the calendar time

2733

functions.

2734

2735

<table><tr><td> </td><td><pre class="smallexample">#include <time.h>

2736

#include <stdio.h>

2737

2738

#define SIZE 256

2739

2740

int

2741

main (void)

2742

{

2743

char buffer[SIZE];

2744

time_t curtime;

2745

struct tm *loctime;

2746

2747

/* Get the current time. */

2748

curtime = time (NULL);

2749

2750

/* Convert it to local time representation. */

2751

loctime = localtime (&curtime);

2752

2753

/* Print out the date and time in the standard format. */

2754

fputs (asctime (loctime), stdout);

2755

2756

</pre><pre class="smallexample"> /* Print it out in a nice format. */

2757

strftime (buffer, SIZE, "Today is %A, %B %d.\n", loctime);

2758

fputs (buffer, stdout);

2759

strftime (buffer, SIZE, "The time is %I:%M %p.\n", loctime);

2760

fputs (buffer, stdout);

2761

2762

return 0;

2763

}

2764

</pre></td></tr></table>

2765

2766

It produces output like this:

2767

2768

<table><tr><td> </td><td><pre class="smallexample">Wed Jul 31 13:02:36 1991

2769

Today is Wednesday, July 31.

2770

The time is 01:02 PM.

2771

</pre></td></tr></table>

2772

2773

2774

2775

2776

2777

2778

2779

2780

2781

2782

2783

2784

2785

2786

2787

2788

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2789

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2790

2791

</tr></table>

2792

2793

<h2 class="section">21.5 Setting an Alarm</h2>

2794

2795

The <code>alarm</code> and <code>setitimer</code> functions provide a mechanism for a

2796

process to interrupt itself in the future. They do this by setting a

2797

timer; when the timer expires, the process receives a signal.

2798

2799

2800

2801

2802

2803

Each process has three independent interval timers available:

2804

2805

<ul>

2806

<li>

2807

A real-time timer that counts elapsed time. This timer sends a

2808

<code>SIGALRM</code> signal to the process when it expires.

2809

2810

2811

2812

</li><li>

2813

A virtual timer that counts processor time used by the process. This timer

2814

sends a <code>SIGVTALRM</code> signal to the process when it expires.

2815

2816

2817

2818

</li><li>

2819

A profiling timer that counts both processor time used by the process,

2820

and processor time spent in system calls on behalf of the process. This

2821

timer sends a <code>SIGPROF</code> signal to the process when it expires.

2822

2823

2824

2825

This timer is useful for profiling in interpreters. The interval timer

2826

mechanism does not have the fine granularity necessary for profiling

2827

native code.

2828

</li></ul>

2829

2830

You can only have one timer of each kind set at any given time. If you

2831

set a timer that has not yet expired, that timer is simply reset to the

2832

new value.

2833

2834

You should establish a handler for the appropriate alarm signal using

2835

<code>signal</code> or <code>sigaction</code> before issuing a call to

2836

<code>setitimer</code> or <code>alarm</code>. Otherwise, an unusual chain of events

2837

could cause the timer to expire before your program establishes the

2838

handler. In this case it would be terminated, since termination is the

2839

default action for the alarm signals. See section <a href="libc_24.html#Signal-Handling">Signal Handling</a>.

2840

2841

To be able to use the alarm function to interrupt a system call which

2842

might block otherwise indefinitely it is important to not set the

2843

<code>SA_RESTART</code> flag when registering the signal handler using

2844

<code>sigaction</code>. When not using <code>sigaction</code> things get even

2845

uglier: the <code>signal</code> function has to fixed semantics with respect

2846

to restarts. The BSD semantics for this function is to set the flag.

2847

Therefore, if <code>sigaction</code> for whatever reason cannot be used, it is

2848

necessary to use <code>sysv_signal</code> and not <code>signal</code>.

2849

2850

The <code>setitimer</code> function is the primary means for setting an alarm.

2851

This facility is declared in the header file ‘<tt>sys/time.h</tt>’. The

2852

<code>alarm</code> function, declared in ‘<tt>unistd.h</tt>’, provides a somewhat

2853

simpler interface for setting the real-time timer.

2854

2855

2856

2857

<dl>

2858

<dt><a name="index-struct-itimerval"></a>Data Type: struct itimerval</dt>

2859

<dd>This structure is used to specify when a timer should expire. It contains

2860

the following members:

2861

2862

<dt> <code>struct timeval it_interval</code></dt>

2863

<dd>This is the period between successive timer interrupts. If zero, the

2864

alarm will only be sent once.

2865

2866

</dd>

2867

<dt> <code>struct timeval it_value</code></dt>

2868

<dd>This is the period between now and the first timer interrupt. If zero,

2869

the alarm is disabled.

2870

</dd>

2871

</dl>

2872

2873

The <code>struct timeval</code> data type is described in <a href="#Elapsed-Time">Elapsed Time</a>.

2874

</dd></dl>

2875

2876

<dl>

2877

<dt><a name="index-setitimer"></a>Function: int setitimer (int <var>which</var>, struct itimerval *<var>new</var>, struct itimerval *<var>old</var>)</dt>

2878

<dd>The <code>setitimer</code> function sets the timer specified by <var>which</var>

2879

according to <var>new</var>. The <var>which</var> argument can have a value of

2880

<code>ITIMER_REAL</code>, <code>ITIMER_VIRTUAL</code>, or <code>ITIMER_PROF</code>.

2881

2882

If <var>old</var> is not a null pointer, <code>setitimer</code> returns information

2883

about any previous unexpired timer of the same kind in the structure it

2884

points to.

2885

2886

The return value is <code>0</code> on success and <code>-1</code> on failure. The

2887

following <code>errno</code> error conditions are defined for this function:

2888

2889

2890

<dt> <code>EINVAL</code></dt>

2891

<dd>The timer period is too large.

2892

</dd>

2893

</dl>

2894

</dd></dl>

2895

2896

<dl>

2897

<dt><a name="index-getitimer"></a>Function: int getitimer (int <var>which</var>, struct itimerval *<var>old</var>)</dt>

2898

<dd>The <code>getitimer</code> function stores information about the timer specified

2899

by <var>which</var> in the structure pointed at by <var>old</var>.

2900

2901

The return value and error conditions are the same as for <code>setitimer</code>.

2902

</dd></dl>

2903

2904

2905

<dt> <code>ITIMER_REAL</code>

2906

2907

</dt>

2908

<dd>This constant can be used as the <var>which</var> argument to the

2909

<code>setitimer</code> and <code>getitimer</code> functions to specify the real-time

2910

timer.

2911

2912

</dd>

2913

<dt> <code>ITIMER_VIRTUAL</code>

2914

2915

</dt>

2916

<dd>This constant can be used as the <var>which</var> argument to the

2917

<code>setitimer</code> and <code>getitimer</code> functions to specify the virtual

2918

timer.

2919

2920

</dd>

2921

<dt> <code>ITIMER_PROF</code>

2922

2923

</dt>

2924

<dd>This constant can be used as the <var>which</var> argument to the

2925

<code>setitimer</code> and <code>getitimer</code> functions to specify the profiling

2926

timer.

2927

</dd>

2928

</dl>

2929

2930

<dl>

2931

<dt><a name="index-alarm"></a>Function: unsigned int alarm (unsigned int <var>seconds</var>)</dt>

2932

<dd>The <code>alarm</code> function sets the real-time timer to expire in

2933

<var>seconds</var> seconds. If you want to cancel any existing alarm, you

2934

can do this by calling <code>alarm</code> with a <var>seconds</var> argument of

2935

zero.

2936

2937

The return value indicates how many seconds remain before the previous

2938

alarm would have been sent. If there is no previous alarm, <code>alarm</code>

2939

returns zero.

2940

</dd></dl>

2941

2942

The <code>alarm</code> function could be defined in terms of <code>setitimer</code>

2943

like this:

2944

2945

<table><tr><td> </td><td><pre class="smallexample">unsigned int

2946

alarm (unsigned int seconds)

2947

{

2948

struct itimerval old, new;

2949

new.it_interval.tv_usec = 0;

2950

new.it_interval.tv_sec = 0;

2951

new.it_value.tv_usec = 0;

2952

new.it_value.tv_sec = (long int) seconds;

2953

if (setitimer (ITIMER_REAL, &new, &old) < 0)

2954

return 0;

2955

else

2956

return old.it_value.tv_sec;

2957

}

2958

</pre></td></tr></table>

2959

2960

There is an example showing the use of the <code>alarm</code> function in

2961

<a href="libc_24.html#Handler-Returns">Signal Handlers that Return</a>.

2962

2963

If you simply want your process to wait for a given number of seconds,

2964

you should use the <code>sleep</code> function. See section <a href="#Sleeping">Sleeping</a>.

2965

2966

You shouldn’t count on the signal arriving precisely when the timer

2967

expires. In a multiprocessing environment there is typically some

2968

amount of delay involved.

2969

2970

Portability Note: The <code>setitimer</code> and <code>getitimer</code>

2971

functions are derived from BSD Unix, while the <code>alarm</code> function is

2972

specified by the POSIX.1 standard. <code>setitimer</code> is more powerful than

2973

<code>alarm</code>, but <code>alarm</code> is more widely used.

2974

2975

2976

2977

2978

2979

2980

2981

2982

2983

2984

2985

2986

2987

2988

2989

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

2990

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

2991

2992

</tr></table>

2993

2994

<h2 class="section">21.6 Sleeping</h2>

2995

2996

The function <code>sleep</code> gives a simple way to make the program wait

2997

for a short interval. If your program doesn’t use signals (except to

2998

terminate), then you can expect <code>sleep</code> to wait reliably throughout

2999

the specified interval. Otherwise, <code>sleep</code> can return sooner if a

3000

signal arrives; if you want to wait for a given interval regardless of

3001

signals, use <code>select</code> (see section <a href="libc_13.html#Waiting-for-I_002fO">Waiting for Input or Output</a>) and don’t specify

3002

any descriptors to wait for.

3003

3004

<dl>

3005

<dt><a name="index-sleep"></a>Function: unsigned int sleep (unsigned int <var>seconds</var>)</dt>

3006

<dd>The <code>sleep</code> function waits for <var>seconds</var> or until a signal

3007

is delivered, whichever happens first.

3008

3009

If <code>sleep</code> function returns because the requested interval is over,

3010

it returns a value of zero. If it returns because of delivery of a

3011

signal, its return value is the remaining time in the sleep interval.

3012

3013

The <code>sleep</code> function is declared in ‘<tt>unistd.h</tt>’.

3014

</dd></dl>

3015

3016

Resist the temptation to implement a sleep for a fixed amount of time by

3017

using the return value of <code>sleep</code>, when nonzero, to call

3018

<code>sleep</code> again. This will work with a certain amount of accuracy as

3019

long as signals arrive infrequently. But each signal can cause the

3020

eventual wakeup time to be off by an additional second or so. Suppose a

3021

few signals happen to arrive in rapid succession by bad luck—there is

3022

no limit on how much this could shorten or lengthen the wait.

3023

3024

Instead, compute the calendar time at which the program should stop

3025

waiting, and keep trying to wait until that calendar time. This won’t

3026

be off by more than a second. With just a little more work, you can use

3027

<code>select</code> and make the waiting period quite accurate. (Of course,

3028

heavy system load can cause additional unavoidable delays—unless the

3029

machine is dedicated to one application, there is no way you can avoid

3030

this.)

3031

3032

On some systems, <code>sleep</code> can do strange things if your program uses

3033

<code>SIGALRM</code> explicitly. Even if <code>SIGALRM</code> signals are being

3034

ignored or blocked when <code>sleep</code> is called, <code>sleep</code> might

3035

return prematurely on delivery of a <code>SIGALRM</code> signal. If you have

3036

established a handler for <code>SIGALRM</code> signals and a <code>SIGALRM</code>

3037

signal is delivered while the process is sleeping, the action taken

3038

might be just to cause <code>sleep</code> to return instead of invoking your

3039

handler. And, if <code>sleep</code> is interrupted by delivery of a signal

3040

whose handler requests an alarm or alters the handling of <code>SIGALRM</code>,

3041

this handler and <code>sleep</code> will interfere.

3042

3043

On the GNU system, it is safe to use <code>sleep</code> and <code>SIGALRM</code> in

3044

the same program, because <code>sleep</code> does not work by means of

3045

<code>SIGALRM</code>.

3046

3047

<dl>

3048

<dt><a name="index-nanosleep"></a>Function: int nanosleep (const struct timespec *<var>requested_time</var>, struct timespec *<var>remaining</var>)</dt>

3049

<dd>If resolution to seconds is not enough the <code>nanosleep</code> function can

3050

be used. As the name suggests the sleep interval can be specified in

3051

nanoseconds. The actual elapsed time of the sleep interval might be

3052

longer since the system rounds the elapsed time you request up to the

3053

next integer multiple of the actual resolution the system can deliver.

3054

3055

*<code>requested_time</code> is the elapsed time of the interval you want to

3056

sleep.

3057

3058

The function returns as *<code>remaining</code> the elapsed time left in the

3059

interval for which you requested to sleep. If the interval completed

3060

without getting interrupted by a signal, this is zero.

3061

3062

<code>struct timespec</code> is described in See section <a href="#Elapsed-Time">Elapsed Time</a>.

3063

3064

If the function returns because the interval is over the return value is

3065

zero. If the function returns -1 the global variable <var>errno</var>

3066

is set to the following values:

3067

3068

3069

<dt> <code>EINTR</code></dt>

3070

<dd>The call was interrupted because a signal was delivered to the thread.

3071

If the <var>remaining</var> parameter is not the null pointer the structure

3072

pointed to by <var>remaining</var> is updated to contain the remaining

3073

elapsed time.

3074

3075

</dd>

3076

<dt> <code>EINVAL</code></dt>

3077

<dd>The nanosecond value in the <var>requested_time</var> parameter contains an

3078

illegal value. Either the value is negative or greater than or equal to

3079

1000 million.

3080

</dd>

3081

</dl>

3082

3083

This function is a cancellation point in multi-threaded programs. This

3084

is a problem if the thread allocates some resources (like memory, file

3085

descriptors, semaphores or whatever) at the time <code>nanosleep</code> is

3086

called. If the thread gets canceled these resources stay allocated

3087

until the program ends. To avoid this calls to <code>nanosleep</code> should

3088

be protected using cancellation handlers.

3089

3090

The <code>nanosleep</code> function is declared in ‘<tt>time.h</tt>’.

3091

</dd></dl>

3092

3093

3094

3095

3096

3097

3098

3099

3100

3101

3102

<td valign="middle" align="left">[<a href="libc_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>

3103

<td valign="middle" align="left">[<a href="libc_42.html#Concept-Index" title="Index">Index</a>]</td>

3104

3105

</tr></table>

3106

3107

3108

This document was generated by root on May 20, 2010 using <a href="http://www.nongnu.org/texi2html/">texi2html 1.82</a>.

3109

3110

3111

3112

3113

</body>

3114

</html>

Older »