Time Utilities¶
Functions for managing time, parsing and formatting durations, and implementing timeout-based operations.
Usage Guide¶
Measuring Command Execution Time¶
Use L_time to measure and print execution time of a command.
L_time sleep 1
# Output:
# real=0m1.002581s user=0m0.002502s system=0m0.000000s [sleep 1]
Parsing and Converting Durations¶
Convert duration strings to microseconds with L_duration_to_usec, or convert microseconds back to duration strings with L_usec_to_duration.
# Parse 5m30s to microseconds
L_duration_to_usec "5m30s"
echo "Microseconds: $L_RET" # 330000000
# Convert back to Prometheus duration string
L_usec_to_duration 330000000
echo "Duration: $L_RET" # 5m30s
Date Formatting¶
Use L_date for date formatting, supporting %f (microseconds) and subsecond timepoints. It selects the optimal method based on available capabilities and the format string.
# Print current time with microseconds
L_date "%Y-%m-%d %H:%M:%S.%f"
echo "$L_RET"
# Format a specific unix timestamp
L_date "%H:%M:%S" 1700000000
echo "$L_RET"
Microsecond Epoch Time¶
Retrieve the current epoch time in microseconds. It works across different environments and Bash versions, including those where the native ${EPOCHREALTIME} variable is not available.
L_epochrealtime_usec
echo "Current epoch (usec): $L_RET"
Timeouts¶
Implement timeouts with helper functions:
# Initialize a 5-second timeout variable
L_timeout_init_into timeout 5
while ! L_timeout_is_expired "$timeout"; do
# Perform some task...
L_timeout_left "$timeout"
echo "Time remaining: $L_RET seconds"
sleep 0.5
done
API Reference¶
Measure time with the command, but include the command in the time message output and use %6l format.
Argument:
$@
command to measure.
Parse 1y2w3d4h5m6s7ms8us or 1.234 into number of microseconds.
Option:
-v <var>
Argument:
$1
Duration string.
See: https://prometheus.io/docs/prometheus/latest/configuration/configuration/#configuration-file
Shellcheck disable= SC2211 SC2035 SC2035 SC1102
Convert microseconds to Prometheus duration string using L_RET.
Option:
-v <var>
Argument:
$1
Microseconds (integer).
Print date in the format.
If the format string contains %N or the timepoint is not a number, use date command. Otherwise, try to use printf %(fmt)T.
Options:
-
-v <var>Store the output in variable instead of printing it. -
-hPrint this help and exit.
Arguments:
-
$1Format string, without leading +. -
[$2]Optional timepoint in seconds with optional digit or any date understood format.
Return time in microseconds.
The dot or comma is removed from EPOCHREALTIME. Uses EPOCHREALTIME in newer Bash. In older Bash tries GNU date, gdate, perl, /proc/uptime, python, busybox adjtimex.
Option:
-v <var>
Convert float seconds to microseconds.
Example
L_sec_to_usec 1.5 -> 1500000
Option:
-v <var>
Convert microseconds to seconds with 6 digits after comma.
Option:
-v <var>
Calculate timeout value.
The timeout value is stored in microseconds.
Arguments:
-
$1Variable to assign with the timeout value in usec. -
$2Timeout in seconds. May be a fraction.
See: L_epochrealtime_usec
Initialize a timer with a timeout in microseconds.
Arguments:
-
$1Variable to assign with the timeout value in usec. -
$2Timeout in microseconds.
Is the timeout expired?
Argument:
$1
timeout value in usec.
Get the number of microseconds left in the timer.
Option:
-v <var>
Store the output in variable instead of printing it.
Argument:
$1
timeout value in usec.
Get the number of seconds left in the timer.
Option:
-v <var>
Store the output in variable instead of printing it.
Argument:
$1
timeout value in usec.