currentSystemDefault

Queries the current system time zone.

If the current system time zone changes, this function can reflect this change on the next invocation.

It is recommended to call this function once at the start of an operation and reuse the result: querying the system time zone may involve heavy operations like reading the system files, and also, querying the system time zone multiple times in one operation may lead to inconsistent results if the system time zone changes in the middle of the operation.

How exactly the time zone is acquired is system-dependent. The current implementation:

• JVM: java.time.ZoneId.systemDefault() is queried.

• Kotlin/Native:

• Darwin: first, NSTimeZone.resetSystemTimeZone is called to clear the cache of the system timezone. Then, NSTimeZone.systemTimeZone.name is used to obtain the up-to-date timezone name.

• Linux: this function checks the /etc/localtime symbolic link. If the link is missing, UTC is used. If the file is not a link but a plain file, the contents of /etc/timezone are additionally checked for the timezone name. IllegalTimeZoneException is thrown if the timezone name cannot be determined or is invalid.

• Windows: the GetDynamicTimeZoneInformation function is used, with the native Windows timezone name being mapped to the corresponding IANA identifier. IllegalTimeZoneException is thrown if this mapping fails. See of for details.

• JavaScript and Wasm/JS:

• If the @js-joda/timezone library is loaded, Intl.DateTimeFormat().resolvedOptions().timeZone is used to obtain the timezone name. See https://github.com/Kotlin/kotlinx-datetime/blob/master/README.md#note-about-time-zones-in-js

• Otherwise, a time zone with the identifier "SYSTEM" is returned, and JS Date's getTimezoneOffset() is used to obtain the offset for the given moment.

• Wasm/WASI: always returns the UTC timezone, as the platform does not support retrieving system timezone information.

Note that the implementation of this function for various platforms may change in the future, in particular, the JavaScript and Wasm/JS platforms.

Samples

import kotlinx.datetime.*
import kotlinx.datetime.format.*
import kotlin.test.*
import kotlin.time.Instant
import kotlin.time.Clock

fun main() { 
   //sampleStart 
   // Obtaining the current system default time zone and using it for formatting
// a fixed-width format for log entries
val logTimeFormat = DateTimeComponents.Format {
    date(LocalDate.Formats.ISO)
    char(' ')
    hour(); char(':'); minute(); char(':'); second(); char('.'); secondFraction(3)
    offset(UtcOffset.Formats.FOUR_DIGITS)
}
fun logEntry(message: String, now: Instant = Clock.System.now()): String {
    val formattedTime = logTimeFormat.format {
        with(TimeZone.currentSystemDefault()) {
            setDateTime(now.toLocalDateTime())
            setOffset(offsetAt(now))
        }
    }
    return "[$formattedTime] $message"
}
// Outputs a text like `[2024-06-02 08:30:02.515+0200] Starting the application`
logEntry("Starting the application") 
   //sampleEnd
}