Debian Codegraph @

upstream/debian-unstable/man3/time.3am

raw
1 .TH TIME 3am "Nov 13 2024" "Free Software Foundation" "GNU Awk Extension Modules"
2 .SH NAME
3 time \- time functions for gawk
4 .SH SYNOPSIS
5 .ft CW
6 @load "time"
7 .sp
8 time = gettimeofday()
9 .br
10 ret = sleep(amount)
11 .br
12 timeval = strptime(string, format)
13 .ft R
14 .SH DESCRIPTION
15 The
16 .I time
17 extension adds three functions named
18 .B gettimeofday()
19 .BR sleep() ,
20 and
21 .BR strptime() ,
22 as follows.
23 .TP
24 .B gettimeofday()
25 This function returns the number of seconds since the Epoch
26 as a floating-point value. It should have subsecond precision.
27 It returns \-1 upon error and sets
28 .B ERRNO
29 to indicate the problem.
30 .TP
31 .BI sleep( seconds )
32 This function attempts to sleep for the given amount of seconds, which
33 may include a fractional portion.
34 If
35 .I seconds
36 is negative, or the attempt to sleep fails,
37 then it returns \-1 and sets
38 .BR ERRNO .
39 Otherwise, the function should return 0 after sleeping
40 for the indicated amount of time.
41 .TP
42 .B strptime()
43 This function takes two arguments, a string representing a date and time,
44 and a format string describing the data in the string. It calls the
45 C library
46 .IR strptime (3)
47 function with the given values.
48 If the parsing succeeds, the results are passed to the C library
49 .IR mktime (3)
50 function, and its result is returned, expressing the time in seconds
51 since the epoch in the current local timezone, regardless
52 of any timezone specified in the string arguments.
53 (This is the same as
54 .IR gawk 's
55 built-in
56 .B systime()
57 function.)
58 Otherwise it returns \-1 upon error. In the latter case,
59 .B ERRNO
60 indicates the problem.
61 .\" .SH NOTES
62 .SH BUGS
63 The underlying
64 .IR strptime (3)
65 C library routine apparently ignores any time zone indication
66 in the date string, producing values relative to the current time zone.
67 It might be better to have this routine return a string similar
68 to what
69 .IR gawk 's
70 .B mktime()
71 function expects, but we ran out of energy.
72 .SH EXAMPLE
73 .ft CW
74 .nf
75 @load "time"
76 \&...
77 printf "It is now %g seconds since the Epoch\en", gettimeofday()
78 \&...
79 printf "Pausing for a while... " ; sleep(2.5) ; print "done"
80 \&...
81 format = "%b %d %H:%M:%S %Z %Y"
82 now = systime()
83 print now, "<" (result = strftime(format, now)) ">",
84 then = strptime(result, format)
85 print strftime(format, then)
86 .fi
87 .ft R
88 .SH "SEE ALSO"
89 .IR "GAWK: Effective AWK Programming" ,
90 .IR filefuncs (3am),
91 .IR fnmatch (3am),
92 .IR fork (3am),
93 .IR inplace (3am),
94 .IR ordchr (3am),
95 .IR readdir (3am),
96 .IR readfile (3am),
97 .IR revoutput (3am),
98 .IR rwarray (3am).
99 .PP
100 .IR gettimeofday (2),
101 .IR nanosleep (2),
102 .IR select (2),
103 and
104 .IR strptime (3).
105 .SH AUTHOR
106 Arnold Robbins,
107 .BR [email protected] .
108 .SH COPYING PERMISSIONS
109 Copyright \(co 2012, 2013, 2018, 2022, 2023, 2024,
110 Free Software Foundation, Inc.
111 .br
112 Copyright \(co 2019,
113 Arnold David Robbins.
114 .PP
115 Permission is granted to make and distribute verbatim copies of
116 this manual page provided the copyright notice and this permission
117 notice are preserved on all copies.
118 .ig
119 Permission is granted to process this file through troff and print the
120 results, provided the printed document carries copying permission
121 notice identical to this one except for the removal of this paragraph
122 (this paragraph not being relevant to the printed manual page).
123 ..
124 .PP
125 Permission is granted to copy and distribute modified versions of this
126 manual page under the conditions for verbatim copying, provided that
127 the entire resulting derived work is distributed under the terms of a
128 permission notice identical to this one.
129 .PP
130 Permission is granted to copy and distribute translations of this
131 manual page into another language, under the above conditions for
132 modified versions, except that this permission notice may be stated in
133 a translation approved by the Foundation.
134 .\" vim: set filetype=nroff :