What is the Difference Between the `SECONDS()` and `UPTIME()` Functions?

Questions & Suggestions
1

What is the difference between these two functions?:

SECONDS Function

The SECONDS() function returns the time in fractional seconds since the Mac started.

UPTIME Function

The UPTIME() function returns the time in fractional seconds since the Mac booted.

The UPTIME() function was introduced in v11.0 while SECONDS() appears to have been around for a while. The manual pages link to each other, but they don't say that the functions are synonyms.

So what is the difference? And why is it not mentioned in the manual or in the v11.0 Release Notes? The Release Notes link to a Forum Thread that does not mention "uptime". Why was a new function needed? @peternlewis?

Is there a technical difference between when "the Mac started" and when "the Mac booted"? Since "restarting" causes a "reboot", presumably in that case the numbers would be similar. Maybe they count from different parts in the process, hardware vs. software and the difference could be a diagnostic tool. I'm totally guessing.

Are there conditions in which one of these functions starts over from zero but the other doesn't?

2

What is the difference between SECONDS() and UPTIME() ?

Does much turn on it ?

Either way around:

  • SECONDS() - UPTIME(), or
  • UPTIME() - SECONDS()

we get a negligibly small negative value, presumably corresponding to a tiny computation cost.

Here, for example, values like:

-0.00004025

Possibly worth losing about 1/10000 of a second of sleep over ?

3

This is core of my concern:

If so, then that determines which one I should use, depending on what I'm trying to do.

If not, then it doesn't matter which I use. But if it doesn't matter, why was UPTIME() introduced in v11.0? Did @peternlewis just forget that SECONDS() was already there? I doubt it.

4

I would imagine that he introduced UPTIME() because that's far more descriptive than SECONDS(). It probably has its own independent starting value that it initialized separately, which would explain the small difference.

I see your point about "are there any conditions in which one [resets]?" It's a valid point. The documentation for one says "since the Mac booted" and the other says "since the Mac started." In theory, there might be a way to restart macOS without rebooting it. I googled those words, and found no distinction. I also asked ChatGPT and it said they both refer to the same steps.

5

The UPTIME function returns NSProcessInfo.processInfo.systemUptime, the time that the Mac has been up since.

You should use that if what you want to know is how long since the Mac has been booted.

SECONDS function returns CACurrentMediaTime() (give or take a microsecond) which in turn is based on mach_absolute_time() which the according to the documentation says Returns current value of a clock that increments monotonically in tick units (starting at an arbitrary point), this clock does not increment while the system is asleep.

You should use that if you want to keep track of time differences for short periods (such as timing how long a macro takes to execute).

The purpose of the CACurrentMediaTime is related to media syncing/timing I believe.

That said, in any experiment I carry out, whether the Mac has slept or not, the two stay in sync. So take it up with Apple.

But basically, don't rely on the two being the same, use them for their respective purposes.

Don't rely on the precision of the UPTIME() function. Assume it might update only every second or two.

Similarly, don't rely on the long term value of the SECONDS() function. Assume it might lose time if the Mac slept.

4 Likes
6

Thanks. That's very useful. I'll update the Wiki if you'll give me temporary permission on those two pages.