diff options
Diffstat (limited to 'man/man8')
| -rw-r--r-- | man/man8/iconvconfig.8 | 92 | ||||
| -rw-r--r-- | man/man8/intro.8 | 29 | ||||
| -rw-r--r-- | man/man8/ld-linux.8 | 1 | ||||
| -rw-r--r-- | man/man8/ld-linux.so.8 | 1 | ||||
| -rw-r--r-- | man/man8/ld.so.8 | 929 | ||||
| -rw-r--r-- | man/man8/ldconfig.8 | 204 | ||||
| -rw-r--r-- | man/man8/nscd.8 | 84 | ||||
| -rw-r--r-- | man/man8/sln.8 | 44 | ||||
| -rw-r--r-- | man/man8/tzselect.8 | 125 | ||||
| -rw-r--r-- | man/man8/zdump.8 | 230 | ||||
| -rw-r--r-- | man/man8/zic.8 | 894 |
11 files changed, 2633 insertions, 0 deletions
diff --git a/man/man8/iconvconfig.8 b/man/man8/iconvconfig.8 new file mode 100644 index 0000000..c7e962e --- /dev/null +++ b/man/man8/iconvconfig.8 @@ -0,0 +1,92 @@ +.\" Copyright (C) 2014 Marko Myllynen <myllynen@redhat.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.TH iconvconfig 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +iconvconfig \- create iconv module configuration cache +.SH SYNOPSIS +.B iconvconfig +.RI [ options ] +.RI [ directory ]... +.SH DESCRIPTION +The +.BR iconv (3) +function internally uses +.I gconv +modules to convert to and from a character set. +A configuration file is used to determine the needed modules +for a conversion. +Loading and parsing such a configuration file would slow down +programs that use +.BR iconv (3), +so a caching mechanism is employed. +.P +The +.B iconvconfig +program reads iconv module configuration files and writes +a fast-loading gconv module configuration cache file. +.P +In addition to the system provided gconv modules, the user can specify +custom gconv module directories with the environment variable +.BR GCONV_PATH . +However, iconv module configuration caching is used only when +the environment variable +.B GCONV_PATH +is not set. +.SH OPTIONS +.TP +.B "\-\-nostdlib" +Do not search the system default gconv directory, +only the directories provided on the command line. +.TP +.BI \-\-output= outputfile +.TQ +.BI \-o\~ outputfile +Use +.I outputfile +for output instead of the system default cache location. +.TP +.BI \-\-prefix= pathname +Set the prefix to be prepended to the system pathnames. +See FILES, below. +By default, the prefix is empty. +Setting the prefix to +.IR foo , +the gconv module configuration would be read from +.I foo/usr/lib/gconv/gconv\-modules +and the cache would be written to +.IR foo/usr/lib/gconv/gconv\-modules.cache . +.TP +.B \-\-help +.TQ +.B \-? +Print a usage summary and exit. +.TP +.B \-\-usage +Print a short usage summary and exit. +.TP +.B \-\-version +.TQ +.B \-V +Print the version number, license, and disclaimer of warranty for +.BR iconv . +.SH EXIT STATUS +Zero on success, nonzero on errors. +.SH FILES +.TP +.I /usr/lib/gconv +Usual default gconv module path. +.TP +.I /usr/lib/gconv/gconv\-modules +Usual system default gconv module configuration file. +.TP +.I /usr/lib/gconv/gconv\-modules.cache +Usual system gconv module configuration cache. +.P +Depending on the architecture, +the above files may instead be located at directories with the path prefix +.IR /usr/lib64 . +.SH SEE ALSO +.BR iconv (1), +.BR iconv (3) diff --git a/man/man8/intro.8 b/man/man8/intro.8 new file mode 100644 index 0000000..1affa45 --- /dev/null +++ b/man/man8/intro.8 @@ -0,0 +1,29 @@ +.\" Copyright (c) 1993 Michael Haardt (michael@moria.de), +.\" Fri Apr 2 11:32:09 MET DST 1993 +.\" and Copyright (C) 2007 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified Sat Jul 24 17:35:48 1993 by Rik Faith (faith@cs.unc.edu) +.\" 2007-10-23 mtk: minor rewrites, and added paragraph on exit status +.\" +.TH intro 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +intro \- introduction to administration and privileged commands +.SH DESCRIPTION +Section 8 of the manual describes commands +which either can be or are used only by the superuser, +like system-administration commands, daemons, +and hardware-related commands. +.P +As with the commands described in Section 1, the commands described +in this section terminate with an exit status that indicates +whether the command succeeded or failed. +See +.BR intro (1) +for more information. +.SH NOTES +.SS Authors and copyright conditions +Look at the header of the manual page source for the author(s) and copyright +conditions. +Note that these can be different from page to page! diff --git a/man/man8/ld-linux.8 b/man/man8/ld-linux.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man/man8/ld-linux.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man/man8/ld-linux.so.8 b/man/man8/ld-linux.so.8 new file mode 100644 index 0000000..c575620 --- /dev/null +++ b/man/man8/ld-linux.so.8 @@ -0,0 +1 @@ +.so man8/ld.so.8 diff --git a/man/man8/ld.so.8 b/man/man8/ld.so.8 new file mode 100644 index 0000000..b464448 --- /dev/null +++ b/man/man8/ld.so.8 @@ -0,0 +1,929 @@ +.\" %%%LICENSE_START(PUBLIC_DOMAIN) +.\" This is in the public domain +.\" %%%LICENSE_END +.\" Various parts: +.\" Copyright (C) 2007-9, 2013, 2016 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.TH ld.so 8 2024-05-08 "Linux man-pages (unreleased)" +.SH NAME +ld.so, ld\-linux.so \- dynamic linker/loader +.SH SYNOPSIS +The dynamic linker can be run either indirectly by running some +dynamically linked program or shared object +(in which case no command-line options +to the dynamic linker can be passed and, in the ELF case, the dynamic linker +which is stored in the +.B .interp +section of the program is executed) or directly by running: +.P +.I /lib/ld\-linux.so.* +[OPTIONS] [PROGRAM [ARGUMENTS]] +.SH DESCRIPTION +The programs +.B ld.so +and +.B ld\-linux.so* +find and load the shared objects (shared libraries) needed by a program, +prepare the program to run, and then run it. +.P +Linux binaries require dynamic linking (linking at run time) +unless the +.B \-static +option was given to +.BR ld (1) +during compilation. +.P +The program +.B ld.so +handles a.out binaries, a binary format used long ago. +The program +.B ld\-linux.so* +(\fI/lib/ld\-linux.so.1\fP for libc5, \fI/lib/ld\-linux.so.2\fP for glibc2) +handles binaries that are in the more modern ELF format. +Both programs have the same behavior, and use the same +support files and programs +.RB ( ldd (1), +.BR ldconfig (8), +and +.IR /etc/ld.so.conf ). +.P +When resolving shared object dependencies, +the dynamic linker first inspects each dependency +string to see if it contains a slash (this can occur if +a shared object pathname containing slashes was specified at link time). +If a slash is found, then the dependency string is interpreted as +a (relative or absolute) pathname, +and the shared object is loaded using that pathname. +.P +If a shared object dependency does not contain a slash, +then it is searched for in the following order: +.IP (1) 5 +Using the directories specified in the +DT_RPATH dynamic section attribute +of the binary if present and DT_RUNPATH attribute does not exist. +.IP (2) +Using the environment variable +.BR LD_LIBRARY_PATH , +unless the executable is being run in secure-execution mode (see below), +in which case this variable is ignored. +.IP (3) +Using the directories specified in the +DT_RUNPATH dynamic section attribute +of the binary if present. +Such directories are searched only to +find those objects required by DT_NEEDED (direct dependencies) entries +and do not apply to those objects' children, +which must themselves have their own DT_RUNPATH entries. +This is unlike DT_RPATH, which is applied +to searches for all children in the dependency tree. +.IP (4) +From the cache file +.IR /etc/ld.so.cache , +which contains a compiled list of candidate shared objects previously found +in the augmented library path. +If, however, the binary was linked with the +.B \-z nodefaultlib +linker option, shared objects in the default paths are skipped. +Shared objects installed in hardware capability directories (see below) +are preferred to other shared objects. +.IP (5) +In the default path +.IR /lib , +and then +.IR /usr/lib . +(On some 64-bit architectures, the default paths for 64-bit shared objects are +.IR /lib64 , +and then +.IR /usr/lib64 .) +If the binary was linked with the +.B \-z nodefaultlib +linker option, this step is skipped. +.\" +.SS Dynamic string tokens +In several places, the dynamic linker expands dynamic string tokens: +.IP \[bu] 3 +In the environment variables +.BR LD_LIBRARY_PATH , +.BR LD_PRELOAD , +and +.BR LD_AUDIT , +.IP \[bu] +inside the values of the dynamic section tags +.BR DT_NEEDED , +.BR DT_RPATH , +.BR DT_RUNPATH , +.BR DT_AUDIT , +and +.B DT_DEPAUDIT +of ELF binaries, +.IP \[bu] +in the arguments to the +.B ld.so +command line options +.BR \-\-audit , +.BR \-\-library\-path , +and +.B \-\-preload +(see below), and +.IP \[bu] +in the filename arguments to the +.BR dlopen (3) +and +.BR dlmopen (3) +functions. +.P +The substituted tokens are as follows: +.TP +.IR $ORIGIN " (or equivalently " ${ORIGIN} ) +This expands to +the directory containing the program or shared object. +Thus, an application located in +.I somedir/app +could be compiled with +.IP +.in +4n +.EX +gcc \-Wl,\-rpath,\[aq]$ORIGIN/../lib\[aq] +.EE +.in +.IP +so that it finds an associated shared object in +.I somedir/lib +no matter where +.I somedir +is located in the directory hierarchy. +This facilitates the creation of "turn-key" applications that +do not need to be installed into special directories, +but can instead be unpacked into any directory +and still find their own shared objects. +.TP +.IR $LIB " (or equivalently " ${LIB} ) +This expands to +.I lib +or +.I lib64 +depending on the architecture +(e.g., on x86-64, it expands to +.I lib64 +and +on x86-32, it expands to +.IR lib ). +.TP +.IR $PLATFORM " (or equivalently " ${PLATFORM} ) +This expands to a string corresponding to the processor type +of the host system (e.g., "x86_64"). +On some architectures, the Linux kernel doesn't provide a platform +string to the dynamic linker. +The value of this string is taken from the +.B AT_PLATFORM +value in the auxiliary vector (see +.BR getauxval (3)). +.\" To get an idea of the places that $PLATFORM would match, +.\" look at the output of the following: +.\" +.\" mkdir /tmp/d +.\" LD_LIBRARY_PATH=/tmp/d strace -e open /bin/date 2>&1 | grep /tmp/d +.\" +.\" ld.so lets names be abbreviated, so $O will work for $ORIGIN; +.\" Don't do this!! +.P +Note that the dynamic string tokens have to be quoted properly when +set from a shell, +to prevent their expansion as shell or environment variables. +.SH OPTIONS +.TP +.BR \-\-argv0 " \fIstring\fP (since glibc 2.33)" +Set +.I argv[0] +to the value +.I string +before running the program. +.TP +.BI \-\-audit " list" +Use objects named in +.I list +as auditors. +The objects in +.I list +are delimited by colons. +.TP +.BI \-\-glibc-hwcaps-mask " list" +only search built-in subdirectories if in +.IR list . +.TP +.BI \-\-glibc-hwcaps-prepend " list" +Search glibc-hwcaps subdirectories in +.IR list . +.TP +.B \-\-inhibit\-cache +Do not use +.IR /etc/ld.so.cache . +.TP +.BI \-\-library\-path " path" +Use +.I path +instead of +.B LD_LIBRARY_PATH +environment variable setting (see below). +The names +.IR ORIGIN , +.IR LIB , +and +.I PLATFORM +are interpreted as for the +.B LD_LIBRARY_PATH +environment variable. +.TP +.BI \-\-inhibit\-rpath " list" +Ignore RPATH and RUNPATH information in object names in +.IR list . +This option is ignored when running in secure-execution mode (see below). +The objects in +.I list +are delimited by colons or spaces. +.TP +.B \-\-list +List all dependencies and how they are resolved. +.TP +.BR \-\-list\-diagnostics " (since glibc 2.33)" +Print system diagnostic information in a machine-readable format, +such as some internal loader variables, +the auxiliary vector +(see +.BR getauxval (3)), +and the environment variables. +On some architectures, +the command might print additional information +(like the cpu features used in GNU indirect function selection on x86). +.BR \-\-list\-tunables " (since glibc 2.33)" +Print the names and values of all tunables, +along with the minimum and maximum allowed values. +.TP +.BR \-\-preload " \fIlist\fP (since glibc 2.30)" +Preload the objects specified in +.IR list . +The objects in +.I list +are delimited by colons or spaces. +The objects are preloaded as explained in the description of the +.B LD_PRELOAD +environment variable below. +.IP +By contrast with +.BR LD_PRELOAD , +the +.B \-\-preload +option provides a way to perform preloading for a single executable +without affecting preloading performed in any child process that executes +a new program. +.TP +.B \-\-verify +Verify that program is dynamically linked and this dynamic linker can handle +it. +.SH ENVIRONMENT +Various environment variables influence the operation of the dynamic linker. +.\" +.SS Secure-execution mode +For security reasons, +if the dynamic linker determines that a binary should be +run in secure-execution mode, +the effects of some environment variables are voided or modified, +and furthermore those environment variables are stripped from the environment, +so that the program does not even see the definitions. +Some of these environment variables affect the operation of +the dynamic linker itself, and are described below. +Other environment variables treated in this way include: +.BR GCONV_PATH , +.BR GETCONF_DIR , +.BR HOSTALIASES , +.BR LOCALDOMAIN , +.BR LD_AUDIT , +.BR LD_DEBUG , +.BR LD_DEBUG_OUTPUT , +.BR LD_DYNAMIC_WEAK , +.BR LD_HWCAP_MASK , +.BR LD_LIBRARY_PATH , +.BR LD_ORIGIN_PATH , +.BR LD_PRELOAD , +.BR LD_PROFILE , +.BR LD_SHOW_AUXV , +.BR LOCALDOMAIN , +.BR LOCPATH , +.BR MALLOC_TRACE , +.BR NIS_PATH , +.BR NLSPATH , +.BR RESOLV_HOST_CONF , +.BR RES_OPTIONS , +.BR TMPDIR , +and +.BR TZDIR . +.P +A binary is executed in secure-execution mode if the +.B AT_SECURE +entry in the auxiliary vector (see +.BR getauxval (3)) +has a nonzero value. +This entry may have a nonzero value for various reasons, including: +.IP \[bu] 3 +The process's real and effective user IDs differ, +or the real and effective group IDs differ. +This typically occurs as a result of executing +a set-user-ID or set-group-ID program. +.IP \[bu] +A process with a non-root user ID executed a binary that +conferred capabilities to the process. +.IP \[bu] +A nonzero value may have been set by a Linux Security Module. +.\" +.SS Environment variables +Among the more important environment variables are the following: +.TP +.BR LD_ASSUME_KERNEL " (from glibc 2.2.3 to glibc 2.36)" +Each shared object can inform the dynamic linker of the minimum kernel ABI +version that it requires. +(This requirement is encoded in an ELF note section that is viewable via +.I readelf\~\-n +as a section labeled +.BR NT_GNU_ABI_TAG .) +At run time, +the dynamic linker determines the ABI version of the running kernel and +will reject loading shared objects that specify minimum ABI versions +that exceed that ABI version. +.IP +.B LD_ASSUME_KERNEL +can be used to +cause the dynamic linker to assume that it is running on a system with +a different kernel ABI version. +For example, the following command line causes the +dynamic linker to assume it is running on Linux 2.2.5 when loading +the shared objects required by +.IR myprog : +.IP +.in +4n +.EX +$ \fBLD_ASSUME_KERNEL=2.2.5 ./myprog\fP +.EE +.in +.IP +On systems that provide multiple versions of a shared object +(in different directories in the search path) that have +different minimum kernel ABI version requirements, +.B LD_ASSUME_KERNEL +can be used to select the version of the object that is used +(dependent on the directory search order). +.IP +Historically, the most common use of the +.B LD_ASSUME_KERNEL +feature was to manually select the older +LinuxThreads POSIX threads implementation on systems that provided both +LinuxThreads and NPTL +(which latter was typically the default on such systems); +see +.BR pthreads (7). +.TP +.BR LD_BIND_NOW " (since glibc 2.1.1)" +If set to a nonempty string, +causes the dynamic linker to resolve all symbols +at program startup instead of deferring function call resolution to the point +when they are first referenced. +This is useful when using a debugger. +.TP +.B LD_LIBRARY_PATH +A list of directories in which to search for +ELF libraries at execution time. +The items in the list are separated by either colons or semicolons, +and there is no support for escaping either separator. +A zero-length directory name indicates the current working directory. +.IP +This variable is ignored in secure-execution mode. +.IP +Within the pathnames specified in +.BR LD_LIBRARY_PATH , +the dynamic linker expands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +Thus, for example, +the following would cause a library to be searched for in either the +.I lib +or +.I lib64 +subdirectory below the directory containing the program to be executed: +.IP +.in +4n +.EX +$ \fBLD_LIBRARY_PATH=\[aq]$ORIGIN/$LIB\[aq] prog\fP +.EE +.in +.IP +(Note the use of single quotes, which prevent expansion of +.I $ORIGIN +and +.I $LIB +as shell variables!) +.TP +.B LD_PRELOAD +A list of additional, user-specified, ELF shared +objects to be loaded before all others. +This feature can be used to selectively override functions +in other shared objects. +.IP +The items of the list can be separated by spaces or colons, +and there is no support for escaping either separator. +The objects are searched for using the rules given under DESCRIPTION. +Objects are searched for and added to the link map in the left-to-right +order specified in the list. +.IP +In secure-execution mode, +preload pathnames containing slashes are ignored. +Furthermore, shared objects are preloaded only +from the standard search directories and only +if they have set-user-ID mode bit enabled (which is not typical). +.IP +Within the names specified in the +.B LD_PRELOAD +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.\" Tested with the following: +.\" +.\" LD_PRELOAD='$LIB/libmod.so' LD_LIBRARY_PATH=. ./prog +.\" +.\" which will preload the libmod.so in 'lib' or 'lib64', using it +.\" in preference to the version in '.'. +.IP +There are various methods of specifying libraries to be preloaded, +and these are handled in the following order: +.RS +.IP (1) 5 +The +.B LD_PRELOAD +environment variable. +.IP (2) +The +.B \-\-preload +command-line option when invoking the dynamic linker directly. +.IP (3) +The +.I /etc/ld.so.preload +file (described below). +.RE +.TP +.B LD_TRACE_LOADED_OBJECTS +If set (to any value), causes the program to list its dynamic +dependencies, as if run by +.BR ldd (1), +instead of running normally. +.P +Then there are lots of more or less obscure variables, +many obsolete or only for internal use. +.TP +.BR LD_AUDIT " (since glibc 2.4)" +A list of user-specified, ELF shared objects +to be loaded before all others in a separate linker namespace +(i.e., one that does not intrude upon the normal symbol bindings that +would occur in the process) +These objects can be used to audit the operation of the dynamic linker. +The items in the list are colon-separated, +and there is no support for escaping the separator. +.IP +.B LD_AUDIT +is ignored in secure-execution mode. +.IP +The dynamic linker will notify the audit +shared objects at so-called auditing checkpoints\[em]for example, +loading a new shared object, resolving a symbol, +or calling a symbol from another shared object\[em]by +calling an appropriate function within the audit shared object. +For details, see +.BR rtld\-audit (7). +The auditing interface is largely compatible with that provided on Solaris, +as described in its +.IR "Linker and Libraries Guide" , +in the chapter +.IR "Runtime Linker Auditing Interface" . +.IP +Within the names specified in the +.B LD_AUDIT +list, the dynamic linker understands the tokens +.IR $ORIGIN , +.IR $LIB , +and +.I $PLATFORM +(or the versions using curly braces around the names) +as described above in +.IR "Dynamic string tokens" . +(See also the discussion of quoting under the description of +.BR LD_LIBRARY_PATH .) +.IP +Since glibc 2.13, +.\" commit 8e9f92e9d5d7737afdacf79b76d98c4c42980508 +in secure-execution mode, +names in the audit list that contain slashes are ignored, +and only shared objects in the standard search directories that +have the set-user-ID mode bit enabled are loaded. +.TP +.BR LD_BIND_NOT " (since glibc 2.1.95)" +If this environment variable is set to a nonempty string, +do not update the GOT (global offset table) and PLT (procedure linkage table) +after resolving a function symbol. +By combining the use of this variable with +.B LD_DEBUG +(with the categories +.I bindings +and +.IR symbols ), +one can observe all run-time function bindings. +.TP +.BR LD_DEBUG " (since glibc 2.1)" +Output verbose debugging information about operation of the dynamic linker. +The content of this variable is one of more of the following categories, +separated by colons, commas, or (if the value is quoted) spaces: +.RS +.TP 12 +.I help +Specifying +.I help +in the value of this variable does not run the specified program, +and displays a help message about which categories can be specified in this +environment variable. +.TP +.I all +Print all debugging information (except +.I statistics +and +.IR unused ; +see below). +.TP +.I bindings +Display information about which definition each symbol is bound to. +.TP +.I files +Display progress for input file. +.TP +.I libs +Display library search paths. +.TP +.I reloc +Display relocation processing. +.TP +.I scopes +Display scope information. +.TP +.I statistics +Display relocation statistics. +.TP +.I symbols +Display search paths for each symbol look-up. +.TP +.I unused +Determine unused DSOs. +.TP +.I versions +Display version dependencies. +.RE +.IP +Since glibc 2.3.4, +.B LD_DEBUG +is ignored in secure-execution mode, unless the file +.I /etc/suid\-debug +exists (the content of the file is irrelevant). +.TP +.BR LD_DEBUG_OUTPUT " (since glibc 2.1)" +By default, +.B LD_DEBUG +output is written to standard error. +If +.B LD_DEBUG_OUTPUT +is defined, then output is written to the pathname specified by its value, +with the suffix "." (dot) followed by the process ID appended to the pathname. +.IP +.B LD_DEBUG_OUTPUT +is ignored in secure-execution mode. +.TP +.BR LD_DYNAMIC_WEAK " (since glibc 2.1.91)" +By default, when searching shared libraries to resolve a symbol reference, +the dynamic linker will resolve to the first definition it finds. +.IP +Old glibc versions (before glibc 2.2), provided a different behavior: +if the linker found a symbol that was weak, +it would remember that symbol and +keep searching in the remaining shared libraries. +If it subsequently found a strong definition of the same symbol, +then it would instead use that definition. +(If no further symbol was found, +then the dynamic linker would use the weak symbol that it initially found.) +.IP +The old glibc behavior was nonstandard. +(Standard practice is that the distinction between +weak and strong symbols should have effect only at static link time.) +In glibc 2.2, +.\" More precisely 2.1.92 +.\" See weak handling +.\" https://www.sourceware.org/ml/libc-hacker/2000-06/msg00029.html +.\" To: GNU libc hacker <libc-hacker at sourceware dot cygnus dot com> +.\" Subject: weak handling +.\" From: Ulrich Drepper <drepper at redhat dot com> +.\" Date: 07 Jun 2000 20:08:12 -0700 +.\" Reply-To: drepper at cygnus dot com (Ulrich Drepper) +the dynamic linker was modified to provide the current behavior +(which was the behavior that was provided by most other implementations +at that time). +.IP +Defining the +.B LD_DYNAMIC_WEAK +environment variable (with any value) provides +the old (nonstandard) glibc behavior, +whereby a weak symbol in one shared library may be overridden by +a strong symbol subsequently discovered in another shared library. +(Note that even when this variable is set, +a strong symbol in a shared library will not override +a weak definition of the same symbol in the main program.) +.IP +Since glibc 2.3.4, +.B LD_DYNAMIC_WEAK +is ignored in secure-execution mode. +.TP +.BR LD_HWCAP_MASK " (from glibc 2.1 to glibc 2.38)" +Mask for hardware capabilities. +Since glibc 2.26, +the option might be ignored +if glibc does not support tunables. +.TP +.BR LD_ORIGIN_PATH " (since glibc 2.1)" +Path where the binary is found. +.\" Used only if $ORIGIN can't be determined by normal means +.\" (from the origin path saved at load time, or from /proc/self/exe)? +.IP +Since glibc 2.4, +.B LD_ORIGIN_PATH +is ignored in secure-execution mode. +.TP +.BR LD_POINTER_GUARD " (from glibc 2.4 to glibc 2.22)" +Set to 0 to disable pointer guarding. +Any other value enables pointer guarding, which is also the default. +Pointer guarding is a security mechanism whereby some pointers to code +stored in writable program memory (return addresses saved by +.BR setjmp (3) +or function pointers used by various glibc internals) are mangled +semi-randomly to make it more difficult for an attacker to hijack +the pointers for use in the event of a buffer overrun or +stack-smashing attack. +Since glibc 2.23, +.\" commit a014cecd82b71b70a6a843e250e06b541ad524f7 +.B LD_POINTER_GUARD +can no longer be used to disable pointer guarding, +which is now always enabled. +.TP +.BR LD_PROFILE " (since glibc 2.1)" +The name of a (single) shared object to be profiled, +specified either as a pathname or a soname. +Profiling output is appended to the file whose name is: +.RI \%$LD_PROFILE_OUTPUT /\: $LD_PROFILE .profile . +.IP +Since glibc 2.2.5, +.B LD_PROFILE +uses a different default path in secure-execution mode. +.TP +.BR LD_PROFILE_OUTPUT " (since glibc 2.1)" +Directory where +.B LD_PROFILE +output should be written. +If this variable is not defined, or is defined as an empty string, +then the default is +.IR /var/tmp . +.IP +.B LD_PROFILE_OUTPUT +is ignored in secure-execution mode; instead +.I /var/profile +is always used. +.TP +.BR LD_SHOW_AUXV " (since glibc 2.1)" +If this environment variable is defined (with any value), +show the auxiliary array passed up from the kernel (see also +.BR getauxval (3)). +.IP +Since glibc 2.3.4, +.B LD_SHOW_AUXV +is ignored in secure-execution mode. +.TP +.BR LD_TRACE_PRELINKING " (from glibc 2.4 to glibc 2.35)" +If this environment variable is defined, +trace prelinking of the object whose name is assigned to +this environment variable. +(Use +.BR ldd (1) +to get a list of the objects that might be traced.) +If the object name is not recognized, +.\" (This is what seems to happen, from experimenting) +then all prelinking activity is traced. +.TP +.BR LD_USE_LOAD_BIAS " (from glibc 2.3.3 to glibc 2.35)" +.\" http://sources.redhat.com/ml/libc-hacker/2003-11/msg00127.html +.\" Subject: [PATCH] Support LD_USE_LOAD_BIAS +.\" Jakub Jelinek +By default (i.e., if this variable is not defined), +executables and prelinked +shared objects will honor base addresses of their dependent shared objects +and (nonprelinked) position-independent executables (PIEs) +and other shared objects will not honor them. +If +.B LD_USE_LOAD_BIAS +is defined with the value 1, both executables and PIEs +will honor the base addresses. +If +.B LD_USE_LOAD_BIAS +is defined with the value 0, +neither executables nor PIEs will honor the base addresses. +.IP +Since glibc 2.3.3, this variable is ignored in secure-execution mode. +.TP +.BR LD_VERBOSE " (since glibc 2.1)" +If set to a nonempty string, +output symbol versioning information about the +program if the +.B LD_TRACE_LOADED_OBJECTS +environment variable has been set. +.TP +.BR LD_WARN " (since glibc 2.1.3)" +If set to a nonempty string, warn about unresolved symbols. +.TP +.BR LD_PREFER_MAP_32BIT_EXEC " (x86-64 only; since glibc 2.23)" +According to the Intel Silvermont software optimization guide, for 64-bit +applications, branch prediction performance can be negatively impacted +when the target of a branch is more than 4\ GB away from the branch. +If this environment variable is set (to any value), +the dynamic linker +will first try to map executable pages using the +.BR mmap (2) +.B MAP_32BIT +flag, and fall back to mapping without that flag if that attempt fails. +NB: MAP_32BIT will map to the low 2\ GB (not 4\ GB) of the address space. +.IP +Because +.B MAP_32BIT +reduces the address range available for address space layout +randomization (ASLR), +.B LD_PREFER_MAP_32BIT_EXEC +is always disabled in secure-execution mode. +.SH FILES +.TP +.I /lib/ld.so +a.out dynamic linker/loader +.TP +.IR /lib/ld\-linux.so. { 1 , 2 } +ELF dynamic linker/loader +.TP +.I /etc/ld.so.cache +File containing a compiled list of directories in which to search for +shared objects and an ordered list of candidate shared objects. +See +.BR ldconfig (8). +.TP +.I /etc/ld.so.preload +File containing a whitespace-separated list of ELF shared objects to +be loaded before the program. +See the discussion of +.B LD_PRELOAD +above. +If both +.B LD_PRELOAD +and +.I /etc/ld.so.preload +are employed, the libraries specified by +.B LD_PRELOAD +are preloaded first. +.I /etc/ld.so.preload +has a system-wide effect, +causing the specified libraries to be preloaded for +all programs that are executed on the system. +(This is usually undesirable, +and is typically employed only as an emergency remedy, for example, +as a temporary workaround to a library misconfiguration issue.) +.TP +.I lib*.so* +shared objects +.SH NOTES +.SS Legacy Hardware capabilities (from glibc 2.5 to glibc 2.37) +Some shared objects are compiled using hardware-specific instructions which do +not exist on every CPU. +Such objects should be installed in directories whose names define the +required hardware capabilities, such as +.IR /usr/lib/sse2/ . +The dynamic linker checks these directories against the hardware of the +machine and selects the most suitable version of a given shared object. +Hardware capability directories can be cascaded to combine CPU features. +The list of supported hardware capability names depends on the CPU. +The following names are currently recognized: +.\" Presumably, this info comes from sysdeps/i386/dl-procinfo.c and +.\" similar files +.TP +.B Alpha +ev4, ev5, ev56, ev6, ev67 +.TP +.B MIPS +loongson2e, loongson2f, octeon, octeon2 +.TP +.B PowerPC +4xxmac, altivec, arch_2_05, arch_2_06, booke, cellbe, dfp, efpdouble, efpsingle, +fpu, ic_snoop, mmu, notb, pa6t, power4, power5, power5+, power6x, ppc32, ppc601, +ppc64, smt, spe, ucache, vsx +.TP +.B SPARC +flush, muldiv, stbar, swap, ultra3, v9, v9v, v9v2 +.TP +.B s390 +dfp, eimm, esan3, etf3enh, g5, highgprs, hpage, ldisp, msa, stfle, +z900, z990, z9-109, z10, zarch +.TP +.B x86 (32-bit only) +acpi, apic, clflush, cmov, cx8, dts, fxsr, ht, i386, i486, i586, i686, mca, mmx, +mtrr, pat, pbe, pge, pn, pse36, sep, ss, sse, sse2, tm +.P +The legacy hardware capabilities support has the drawback that +each new feature added grows the search path exponentially, +because it has to be added to +every combination of the other existing features. +.P +For instance, on x86 32-bit, +if the hardware supports +.B i686 +and +.BR sse2 , +the resulting search path will be +.BR i686/sse2:i686:sse2:. . +A new capability +.B newcap +will set the search path to +.BR newcap/i686/sse2:newcap/i686:newcap/sse2:newcap:i686/sse2:i686:sse2: . +.\" +.SS glibc Hardware capabilities (from glibc 2.33) +.TP +.\" The initial discussion on various pitfalls of the old scheme is +.\" <https://sourceware.org/pipermail/libc-alpha/2020-May/113757.html> +.\" and the patchset that proposes the glibc-hwcap support is +.\" <https://sourceware.org/pipermail/libc-alpha/2020-June/115250.html> +glibc 2.33 added a new hardware capability scheme, +where under each CPU architecture, +certain levels can be defined, +grouping support for certain features or special instructions. +Each architecture level has +a fixed set of paths that it adds to the dynamic linker search list, +depending on the hardware of the machine. +Since each new architecture level is +not combined with previously existing ones, +the new scheme does not have the drawback of +growing the dynamic linker search list uncontrollably. +.P +For instance, on x86 64-bit, +if the hardware supports +.B x86_64-v3 +(for instance Intel Haswell or AMD Excavator), +the resulting search path will be +.B glibc-hwcaps/x86-64-v3:glibc-hwcaps/x86-64-v2:. +.\" The x86_64 architectures levels are defined the official ABI: +.\" <https://gitlab.com/x86-psABIs/x86-64-ABI/-/blob/master/x86-64-ABI/low-level-sys-info.tex> +.\" The PowerPC and s390x are glibc defined ones based on chip +.\" support (which maps to ISA levels). +The following paths are currently supported, in priority order. +.TP +.B PowerPC (64-bit little-endian only) +power10, power9 +.TP +.B s390 (64-bit only) +z16, z15, z14, z13 +.TP +.B x86 (64-bit only) +x86-64-v4, x86-64-v3, x86-64-v2 +.P +glibc 2.37 removed support for the legacy hardware capabilities. +.\" +.SH SEE ALSO +.BR ld (1), +.BR ldd (1), +.BR pldd (1), +.BR sprof (1), +.BR dlopen (3), +.BR getauxval (3), +.BR elf (5), +.BR capabilities (7), +.BR rtld\-audit (7), +.BR ldconfig (8), +.BR sln (8) +.\" .SH AUTHORS +.\" ld.so: David Engel, Eric Youngdale, Peter MacDonald, Hongjiu Lu, Linus +.\" Torvalds, Lars Wirzenius and Mitch D'Souza +.\" ld\-linux.so: Roland McGrath, Ulrich Drepper and others. +.\" +.\" In the above, (libc5) stands for David Engel's ld.so/ld\-linux.so. diff --git a/man/man8/ldconfig.8 b/man/man8/ldconfig.8 new file mode 100644 index 0000000..a614164 --- /dev/null +++ b/man/man8/ldconfig.8 @@ -0,0 +1,204 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk <kukuk@suse.de> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" Modified, 6 May 2002, Michael Kerrisk, <mtk.manpages@gmail.com> +.\" Change listed order of /usr/lib and /lib +.TH ldconfig 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +ldconfig \- configure dynamic linker run-time bindings +.SH SYNOPSIS +.SY /sbin/ldconfig +.\" TODO?: -c, --format, -i, --ignore-aux-cache, --print-cache, +.\" --verbose, -V, --version, -?, --help, --usage +.RB [ \-nNvVX ] +.RB [ \-C\~\c +.IR cache ] +.RB [ \-f\~\c +.IR conf ] +.RB [ \-r\~\c +.IR root ] +.IR directory \~.\|.\|. +.YS +.SY /sbin/ldconfig +.B \-l +.RB [ \-v ] +.IR library \~.\|.\|. +.YS +.SY /sbin/ldconfig +.B \-p +.YS +.SH DESCRIPTION +.B \%ldconfig +creates the necessary links and cache to the most recent shared +libraries found in the directories specified on the command line, +in the file +.IR /etc/ld.so.conf , +and in the trusted directories, +.I /lib +and +.IR /usr/lib . +On some 64-bit architectures such as x86-64, +.I /lib +and +.I /usr/lib +are the trusted directories for 32-bit libraries, +while +.I /lib64 +and +.I /usr/lib64 +are used for 64-bit libraries. +.P +The cache is used by the run-time linker, +.I ld.so +or +.IR ld\-linux.so . +.B \%ldconfig +checks the header and filenames of the libraries it encounters when +determining which versions should have their links updated. +.\" Support for libc4 and libc5 dropped in +.\" 8ee878592c4a642937152c8308b8faef86bcfc40 (2022-07-14) as "obsolete +.\" for over twenty years". +.B \%ldconfig +should normally be run by the superuser as it may require write +permission on some root owned directories and files. +.P +.B \%ldconfig +will look only at files that are named +.I lib*.so* +(for regular shared objects) or +.I ld\-*.so* +(for the dynamic loader itself). +Other files will be ignored. +Also, +.B \%ldconfig +expects a certain pattern to how the symbolic links are set up, +like this example, +where the middle file +.RB ( libfoo.so.1 +here) is the SONAME for the library: +.P +.in +4n +.EX +libfoo.so \-> libfoo.so.1 \-> libfoo.so.1.12 +.EE +.in +.P +Failure to follow this pattern may result in compatibility issues +after an upgrade. +.SH OPTIONS +.TP +.BI \-\-format= fmt +.TQ +.BI \-c\~ fmt +(Since glibc 2.2) +.\" commit 45eca4d141c047950db48c69c8941163d0a61fcd +Use cache format +.IR fmt , +which is one of +.BR old , +.BR new , +or +.BR \%compat . +Since glibc 2.32, +the default is +.BR new . +.\" commit cad64f778aced84efdaa04ae64f8737b86f063ab +Before that, +it was +.BR \%compat . +.TP +.BI \-C\~ cache +Use +.I cache +instead of +.IR /etc/ld.so.cache . +.TP +.BI \-f\~ conf +Use +.I conf +instead of +.IR /etc/ld.so.conf . +.TP +.B \-\-ignore\-aux\-cache +.TQ +.B \-i +(Since glibc 2.7) +.\" commit 27d9ffda17df4d2388687afd12897774fde39bcc +Ignore auxiliary cache file. +.TP +.B \-l +(Since glibc 2.2) +Interpret each operand as a library name and configure its links. +Intended for use only by experts. +.TP +.B \-n +Process only the directories specified on the command line; +don't process the trusted directories, +nor those specified in +.IR /etc/ld.so.conf . +Implies +.BR \-N . +.TP +.B \-N +Don't rebuild the cache. +Unless +.B \-X +is also specified, +links are still updated. +.TP +.B \-\-print\-cache +.TQ +.B \-p +Print the lists of directories and candidate libraries stored in +the current cache. +.TP +.BI \-r\~ root +Change to and use +.I root +as the root directory. +.TP +.B \-\-verbose +.TQ +.B \-v +Verbose mode. +Print current version number, +the name of each directory as it is scanned, +and any links that are created. +Overrides quiet mode. +.TP +.B \-\-version +.TQ +.B \-V +Print program version. +.TP +.B \-X +Don't update links. +Unless +.B \-N +is also specified, +the cache is still rebuilt. +.SH FILES +.\" FIXME Since glibc-2.3.4, "include" directives are supported in ld.so.conf +.\" +.\" FIXME Since glibc-2.4, "hwcap" directives are supported in ld.so.conf +.PD 0 +.TP +.I /lib/ld.so +is the run-time linker/loader. +.TP +.I /etc/ld.so.conf +contains a list of directories, +one per line, +in which to search for libraries. +.TP +.I /etc/ld.so.cache +contains an ordered list of libraries found in the directories +specified in +.IR /etc/ld.so.conf , +as well as those found in the trusted directories. +.PD +.SH SEE ALSO +.BR ldd (1), +.BR ld.so (8) diff --git a/man/man8/nscd.8 b/man/man8/nscd.8 new file mode 100644 index 0000000..07d365c --- /dev/null +++ b/man/man8/nscd.8 @@ -0,0 +1,84 @@ +.\" Copyright 1999 SuSE GmbH Nuernberg, Germany +.\" Author: Thorsten Kukuk <kukuk@suse.de> +.\" +.\" SPDX-License-Identifier: GPL-2.0-or-later +.\" +.\" 2008-12-05 Petr Baudis <pasky@suse.cz> +.\" Rewrite the NOTES section to reflect modern reality +.\" +.TH nscd 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +nscd \- name service cache daemon +.SH DESCRIPTION +.B nscd +is a daemon that provides a cache for the most common name service +requests. +The default configuration file, +.IR /etc/nscd.conf , +determines the behavior of the cache daemon. +See +.BR nscd.conf (5). +.P +.B nscd +provides caching for accesses of the +.BR passwd (5), +.BR group (5), +.BR hosts (5) +.BR services (5) +and +.I netgroup +databases through standard libc interfaces, such as +.BR getpwnam (3), +.BR getpwuid (3), +.BR getgrnam (3), +.BR getgrgid (3), +.BR gethostbyname (3), +and others. +.P +There are two caches for each database: +a positive one for items found, and a negative one +for items not found. +Each cache has a separate TTL (time-to-live) +period for its data. +Note that the shadow file is specifically not cached. +.BR getspnam (3) +calls remain uncached as a result. +.SH OPTIONS +.TP +.B "\-\-help" +will give you a list with all options and what they do. +.SH NOTES +The daemon will try to watch for changes in configuration files +appropriate for each database (e.g., +.I /etc/passwd +for the +.I passwd +database or +.I /etc/hosts +and +.I /etc/resolv.conf +for the +.I hosts +database), and flush the cache when these are changed. +However, this will happen only after a short delay (unless the +.BR inotify (7) +mechanism is available and glibc 2.9 or later is available), +and this auto-detection does not cover configuration files +required by nonstandard NSS modules, if any are specified in +.IR /etc/nsswitch.conf . +In that case, you need to run the following command +after changing the configuration file of the database so that +.B nscd +invalidates its cache: +.P +.in +4n +.EX +$ \fBnscd \-i\fP \fI<database>\fP +.EE +.in +.SH SEE ALSO +.BR nscd.conf (5), +.BR nsswitch.conf (5) +.\" .SH AUTHOR +.\" .B nscd +.\" was written by Thorsten Kukuk and Ulrich Drepper. diff --git a/man/man8/sln.8 b/man/man8/sln.8 new file mode 100644 index 0000000..0bb74c8 --- /dev/null +++ b/man/man8/sln.8 @@ -0,0 +1,44 @@ +.\" Copyright (c) 2013 by Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sln 8 2024-05-02 "Linux man-pages (unreleased)" +.SH NAME +sln \- create symbolic links +.SH SYNOPSIS +.nf +.BI sln " source dest" +.BI sln " filelist" +.fi +.SH DESCRIPTION +The +.B sln +program creates symbolic links. +Unlike the +.BR ln (1) +program, it is statically linked. +This means that if for some reason the dynamic linker is not working, +.B sln +can be used to make symbolic links to dynamic libraries. +.P +The command line has two forms. +In the first form, it creates +.I dest +as a new symbolic link to +.IR source . +.P +In the second form, +.I filelist +is a list of space-separated pathname pairs, +and the effect is as if +.B sln +was executed once for each line of the file, +with the two pathnames as the arguments. +.P +The +.B sln +program supports no command-line options. +.SH SEE ALSO +.BR ln (1), +.BR ld.so (8), +.BR ldconfig (8) diff --git a/man/man8/tzselect.8 b/man/man8/tzselect.8 new file mode 100644 index 0000000..ee03161 --- /dev/null +++ b/man/man8/tzselect.8 @@ -0,0 +1,125 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH tzselect 8 "" "Time Zone Database" +.SH NAME +tzselect \- select a timezone +.SH SYNOPSIS +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +.ds d " degrees +.ds m " minutes +.ds s " seconds +.ds _ " \& +.if t \{\ +. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\ +. ds d \(de +. ds m \(fm +. ds s \(sd +. ds _ \| +. \} +.\} +.B tzselect +[ +.B \*-c +.I coord +] [ +.B \*-n +.I limit +] [ +.B \*-\*-help +] [ +.B \*-\*-version +] +.SH DESCRIPTION +The +.B tzselect +program asks the user for information about the current location, +and outputs the resulting timezone to standard output. +The output is suitable as a value for the TZ environment variable. +.PP +All interaction with the user is done via standard input and standard error. +.SH OPTIONS +.TP +.BI "\*-c " coord +Instead of asking for continent and then country and then city, +ask for selection from time zones whose largest cities +are closest to the location with geographical coordinates +.I coord. +Use ISO 6709 notation for +.I coord, +that is, a latitude immediately followed by a longitude. The latitude +and longitude should be signed integers followed by an optional +decimal point and fraction: positive numbers represent north and east, +negative south and west. Latitudes with two and longitudes with three +integer digits are treated as degrees; latitudes with four or six and +longitudes with five or seven integer digits are treated as +.I "DDMM, DDDMM, DDMMSS," +or +.I DDDMMSS +representing +.I DD +or +.I DDD +degrees, +.I MM +minutes, +and zero or +.I SS +seconds, with any trailing fractions represent fractional minutes or +(if +.I SS +is present) seconds. The decimal point is that of the current locale. +For example, in the (default) C locale, +.B "\*-c\ +40.689\*-074.045" +specifies 40.689\*d\*_N, 74.045\*d\*_W, +.B "\*-c\ +4041.4\*-07402.7" +specifies 40\*d\*_41.4\*m\*_N, 74\*d\*_2.7\*m\*_W, and +.B "\*-c\ +404121\*-0740240" +specifies 40\*d\*_41\*m\*_21\*s\*_N, 74\*d\*_2\*m\*_40\*s\*_W. +If +.I coord +is not one of the documented forms, the resulting behavior is unspecified. +.TP +.BI "\*-n " limit +When +.B \*-c +is used, display the closest +.I limit +locations (default 10). +.TP +.B "\*-\*-help" +Output help information and exit. +.TP +.B "\*-\*-version" +Output version information and exit. +.SH "ENVIRONMENT VARIABLES" +.TP +\f3AWK\fP +Name of a POSIX-compliant +.B awk +program (default: +.BR awk ). +.TP +\f3TZDIR\fP +Name of the directory containing timezone data files (default: +.BR /usr/share/zoneinfo ). +.SH FILES +.TP +\f2TZDIR\fP\f3/iso3166.tab\fP +Table of ISO 3166 2-letter country codes and country names. +.TP +\f2TZDIR\fP\f3/zone1970.tab\fP +Table of country codes, latitude and longitude, timezones, and +descriptive comments. +.TP +\f2TZDIR\fP\f3/\fP\f2TZ\fP +Timezone data file for timezone \f2TZ\fP. +.SH "EXIT STATUS" +The exit status is zero if a timezone was successfully obtained from the user, +nonzero otherwise. +.SH "SEE ALSO" +newctime(3), tzfile(5), zdump(8), zic(8) +.SH NOTES +Applications should not assume that +.BR tzselect 's +output matches the user's political preferences. diff --git a/man/man8/zdump.8 b/man/man8/zdump.8 new file mode 100644 index 0000000..c3f0bba --- /dev/null +++ b/man/man8/zdump.8 @@ -0,0 +1,230 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH zdump 8 "" "Time Zone Database" +.SH NAME +zdump \- timezone dumper +.SH SYNOPSIS +.B zdump +[ +.I option +\&... ] [ +.I timezone +\&... ] +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie \n(.g .ds - \f(CR-\fP +.el .ds - \- +The +.B zdump +program prints the current time in each +.I timezone +named on the command line. +.SH OPTIONS +.TP +.B \*-\*-version +Output version information and exit. +.TP +.B \*-\*-help +Output short usage message and exit. +.TP +.B \*-i +Output a description of time intervals. For each +.I timezone +on the command line, output an interval-format description of the +timezone. See +.q "INTERVAL FORMAT" +below. +.TP +.B \*-v +Output a verbose description of time intervals. +For each +.I timezone +on the command line, +print the times at the two extreme time values, +the times (if present) at and just beyond the boundaries of years that +.BR localtime (3) +and +.BR gmtime (3) +can represent, and +the times both one second before and exactly at +each detected time discontinuity. +Each line is followed by +.BI isdst= D +where +.I D +is positive, zero, or negative depending on whether +the given time is daylight saving time, standard time, +or an unknown time type, respectively. +Each line is also followed by +.BI gmtoff= N +if the given local time is known to be +.I N +seconds east of Greenwich. +.TP +.B \*-V +Like +.BR \*-v , +except omit output concerning extreme time and year values. +This generates output that is easier to compare to that of +implementations with different time representations. +.TP +.BI "\*-c " \fR[\fIloyear , \fR]\fIhiyear +Cut off interval output at the given year(s). +Cutoff times are computed using the proleptic Gregorian calendar with year 0 +and with Universal Time (UT) ignoring leap seconds. +Cutoffs are at the start of each year, where the lower-bound +timestamp is inclusive and the upper is exclusive; for example, +.B "\*-c 1970,2070" +selects transitions on or after 1970-01-01 00:00:00 UTC +and before 2070-01-01 00:00:00 UTC. +The default cutoff is +.BR \*-500,2500 . +.TP +.BI "\*-t " \fR[\fIlotime , \fR]\fIhitime +Cut off interval output at the given time(s), +given in decimal seconds since 1970-01-01 00:00:00 +Coordinated Universal Time (UTC). +The +.I timezone +determines whether the count includes leap seconds. +As with +.BR \*-c , +the cutoff's lower bound is inclusive and its upper bound is exclusive. +.SH "INTERVAL FORMAT" +The interval format is a compact text representation that is intended +to be both human- and machine-readable. It consists of an empty line, +then a line +.q "TZ=\fIstring\fP" +where +.I string +is a double-quoted string giving the timezone, a second line +.q "\*- \*- \fIinterval\fP" +describing the time interval before the first transition if any, and +zero or more following lines +.q "\fIdate time interval\fP", +one line for each transition time and following interval. Fields are +separated by single tabs. +.PP +Dates are in +.IR yyyy - mm - dd +format and times are in 24-hour +.IR hh : mm : ss +format where +.IR hh <24. +Times are in local time immediately after the transition. A +time interval description consists of a UT offset in signed +.RI \(+- hhmmss +format, a time zone abbreviation, and an isdst flag. An abbreviation +that equals the UT offset is omitted; other abbreviations are +double-quoted strings unless they consist of one or more alphabetic +characters. An isdst flag is omitted for standard time, and otherwise +is a decimal integer that is unsigned and positive (typically 1) for +daylight saving time and negative for unknown. +.PP +In times and in UT offsets with absolute value less than 100 hours, +the seconds are omitted if they are zero, and +the minutes are also omitted if they are also zero. Positive UT +offsets are east of Greenwich. The UT offset \*-00 denotes a UT +placeholder in areas where the actual offset is unspecified; by +convention, this occurs when the UT offset is zero and the time zone +abbreviation begins with +.q "\*-" +or is +.q "zzz". +.PP +In double-quoted strings, escape sequences represent unusual +characters. The escape sequences are \es for space, and \e", \e\e, +\ef, \en, \er, \et, and \ev with their usual meaning in the C +programming language. E.g., the double-quoted string +\*(lq"CET\es\e"\e\e"\*(rq represents the character sequence \*(lqCET +"\e\*(rq.\"" +.PP +.ne 9 +Here is an example of the output, with the leading empty line omitted. +(This example is shown with tab stops set far enough apart so that the +tabbed columns line up.) +.nf +.sp +.if \n(.g .ft CR +.in +2 +.nr w \w'1896-01-13 'u+\n(.i +.ta \w'1896-01-13\0\0'u +\w'12:01:26\0\0'u +\w'-103126\0\0'u +\w'HWT\0\0'u +TZ="Pacific/Honolulu" +- - -103126 LMT +1896-01-13 12:01:26 -1030 HST +1933-04-30 03 -0930 HDT 1 +1933-05-21 11 -1030 HST +1942-02-09 03 -0930 HWT 1 +1945-08-14 13:30 -0930 HPT 1 +1945-09-30 01 -1030 HST +1947-06-08 02:30 -10 HST +.in +.if \n(.g .ft +.sp +.fi +Here, local time begins 10 hours, 31 minutes and 26 seconds west of +UT, and is a standard time abbreviated LMT. Immediately after the +first transition, the date is 1896-01-13 and the time is 12:01:26, and +the following time interval is 10.5 hours west of UT, a standard time +abbreviated HST. Immediately after the second transition, the date is +1933-04-30 and the time is 03:00:00 and the following time interval is +9.5 hours west of UT, is abbreviated HDT, and is daylight saving time. +Immediately after the last transition the date is 1947-06-08 and the +time is 02:30:00, and the following time interval is 10 hours west of +UT, a standard time abbreviated HST. +.PP +.ne 10 +Here are excerpts from another example: +.nf +.sp +.if \n(.g .ft CR +.if t .in +.5i +.if n .in +2 +TZ="Europe/Astrakhan" +- - +031212 LMT +1924-04-30 23:47:48 +03 +1930-06-21 01 +04 +1981-04-01 01 +05 1 +1981-09-30 23 +04 +\&... +2014-10-26 01 +03 +2016-03-27 03 +04 +.in +.if \n(.g .ft +.sp +.fi +This time zone is east of UT, so its UT offsets are positive. Also, +many of its time zone abbreviations are omitted since they duplicate +the text of the UT offset. +.SH LIMITATIONS +Time discontinuities are found by sampling the results returned by +.BR localtime (3) +at twelve-hour intervals. +This works in all real-world cases; +one can construct artificial time zones for which this fails. +.PP +In the +.B \*-v +and +.B \*-V +output, +.q "UT" +denotes the value returned by +.BR gmtime (3), +which uses UTC for modern timestamps and some other UT flavor for +timestamps that predate the introduction of UTC. +No attempt is currently made to have the output use +.q "UTC" +for newer and +.q "UT" +for older timestamps, partly because the exact date of the +introduction of UTC is problematic. +.SH SEE ALSO +.BR tzfile (5), +.BR zic (8) diff --git a/man/man8/zic.8 b/man/man8/zic.8 new file mode 100644 index 0000000..0ad373a --- /dev/null +++ b/man/man8/zic.8 @@ -0,0 +1,894 @@ +.\" This file is in the public domain, so clarified as of +.\" 2009-05-17 by Arthur David Olson. +.TH zic 8 "" "Time Zone Database" +.SH NAME +zic \- timezone compiler +.SH SYNOPSIS +.B zic +[ +.I option +\&... ] [ +.I filename +\&... ] +.SH DESCRIPTION +.ie '\(lq'' .ds lq \&"\" +.el .ds lq \(lq\" +.ie '\(rq'' .ds rq \&"\" +.el .ds rq \(rq\" +.de q +\\$3\*(lq\\$1\*(rq\\$2 +.. +.ie '\(la'' .ds < < +.el .ds < \(la +.ie '\(ra'' .ds > > +.el .ds > \(ra +.ie \n(.g \{\ +. ds : \: +. ds - \f(CR-\fP +.\} +.el \{\ +. ds : +. ds - \- +.\} +.ds d " degrees +.ds m " minutes +.ds s " seconds +.ds _ " \& +.if t \{\ +. if \n(.g .if c \(de .if c \(fm .if c \(sd \{\ +. ds d \(de +. ds m \(fm +. ds s \(sd +. ds _ \| +. \} +.\} +The +.B zic +program reads text from the file(s) named on the command line +and creates the timezone information format (TZif) files +specified in this input. +If a +.I filename +is +.q "\*-" , +standard input is read. +.SH OPTIONS +.TP +.B "\*-\*-version" +Output version information and exit. +.TP +.B \*-\*-help +Output short usage message and exit. +.TP +.BI "\*-b " bloat +Output backward-compatibility data as specified by +.IR bloat . +If +.I bloat +is +.BR fat , +generate additional data entries that work around potential bugs or +incompatibilities in older software, such as software that mishandles +the 64-bit generated data. +If +.I bloat +is +.BR slim , +keep the output files small; this can help check for the bugs +and incompatibilities. +The default is +.BR slim , +as software that mishandles 64-bit data typically +mishandles timestamps after the year 2038 anyway. +Also see the +.B \*-r +option for another way to alter output size. +.TP +.BI "\*-d " directory +Create time conversion information files in the named directory rather than +in the standard directory named below. +.TP +.BI "\*-l " timezone +Use +.I timezone +as local time. +.B zic +will act as if the input contained a link line of the form +.sp +.ti +2 +.ta \w'Link\0\0'u +\w'\fItimezone\fP\0\0'u +Link \fItimezone\fP localtime +.sp +If +.I timezone +is +.BR \*- , +any already-existing link is removed. +.TP +.BI "\*-L " leapsecondfilename +Read leap second information from the file with the given name. +If this option is not used, +no leap second information appears in output files. +.TP +.BI "\*-p " timezone +Use +.IR timezone 's +rules when handling nonstandard +TZ strings like "EET\*-2EEST" that lack transition rules. +.B zic +will act as if the input contained a link line of the form +.sp +.ti +2 +Link \fItimezone\fP posixrules +.sp +If +.I timezone +is +.q "\*-" +(the default), any already-existing link is removed. +.sp +Unless +.I timezone is +.q "\*-" , +this option is obsolete and poorly supported. +Among other things it should not be used for timestamps after the year 2037, +and it should not be combined with +.B "\*-b slim" +if +.IR timezone 's +transitions are at standard time or Universal Time (UT) instead of local time. +.TP +.BR "\*-r " "[\fB@\fP\fIlo\fP][\fB/@\fP\fIhi\fP]" +Limit the applicability of output files +to timestamps in the range from +.I lo +(inclusive) to +.I hi +(exclusive), where +.I lo +and +.I hi +are possibly signed decimal counts of seconds since the Epoch +(1970-01-01 00:00:00 UTC). +Omitted counts default to extreme values. +The output files use UT offset 0 and abbreviation +.q "\*-00" +in place of the omitted timestamp data. +For example, +.q "zic \*-r @0" +omits data intended for negative timestamps (i.e., before the Epoch), and +.q "zic \*-r @0/@2147483648" +outputs data intended only for nonnegative timestamps that fit into +31-bit signed integers. +On platforms with GNU +.BR date , +.q "zic \*-r @$(date +%s)" +omits data intended for past timestamps. +Although this option typically reduces the output file's size, +the size can increase due to the need to represent the timestamp range +boundaries, particularly if +.I hi +causes a TZif file to contain explicit entries for +.RI pre- hi +transitions rather than concisely representing them +with an extended POSIX.1-2017 TZ string. +Also see the +.B "\*-b slim" +option for another way to shrink output size. +.TP +.BI "\*-R @" hi +Generate redundant trailing explicit transitions for timestamps +that occur less than +.I hi +seconds since the Epoch, even though the transitions could be +more concisely represented via the extended POSIX.1-2017 TZ string. +This option does not affect the represented timestamps. +Although it accommodates nonstandard TZif readers +that ignore the extended POSIX.1-2017 TZ string, +it increases the size of the altered output files. +.TP +.BI "\*-t " file +When creating local time information, put the configuration link in +the named file rather than in the standard location. +.TP +.B \*-v +Be more verbose, and complain about the following situations: +.RS +.PP +The input specifies a link to a link, +something not supported by some older parsers, including +.B zic +itself through release 2022e. +.PP +A year that appears in a data file is outside the range +of representable years. +.PP +A time of 24:00 or more appears in the input. +Pre-1998 versions of +.B zic +prohibit 24:00, and pre-2007 versions prohibit times greater than 24:00. +.PP +A rule goes past the start or end of the month. +Pre-2004 versions of +.B zic +prohibit this. +.PP +A time zone abbreviation uses a +.B %z +format. +Pre-2015 versions of +.B zic +do not support this. +.PP +A timestamp contains fractional seconds. +Pre-2018 versions of +.B zic +do not support this. +.PP +The input contains abbreviations that are mishandled by pre-2018 versions of +.B zic +due to a longstanding coding bug. +These abbreviations include +.q L +for +.q Link , +.q mi +for +.q min , +.q Sa +for +.q Sat , +and +.q Su +for +.q Sun . +.PP +The output file does not contain all the information about the +long-term future of a timezone, because the future cannot be summarized as +an extended POSIX.1-2017 TZ string. For example, as of 2023 this problem +occurs for Morocco's daylight-saving rules, as these rules are based +on predictions for when Ramadan will be observed, something that +an extended POSIX.1-2017 TZ string cannot represent. +.PP +The output contains data that may not be handled properly by client +code designed for older +.B zic +output formats. These compatibility issues affect only timestamps +before 1970 or after the start of 2038. +.PP +The output contains a truncated leap second table, +which can cause some older TZif readers to misbehave. +This can occur if the +.B "\*-L" +option is used, and either an Expires line is present or +the +.B "\*-r" +option is also used. +.PP +The output file contains more than 1200 transitions, +which may be mishandled by some clients. +The current reference client supports at most 2000 transitions; +pre-2014 versions of the reference client support at most 1200 +transitions. +.PP +A time zone abbreviation has fewer than 3 or more than 6 characters. +POSIX requires at least 3, and requires implementations to support +at least 6. +.PP +An output file name contains a byte that is not an ASCII letter, +.q "\*-" , +.q "/" , +or +.q "_" ; +or it contains a file name component that contains more than 14 bytes +or that starts with +.q "\*-" . +.RE +.SH FILES +Input files use the format described in this section; output files use +.BR tzfile (5) +format. +.PP +Input files should be text files, that is, they should be a series of +zero or more lines, each ending in a newline byte and containing at +most 2048 bytes counting the newline, and without any NUL bytes. +The input text's encoding +is typically UTF-8 or ASCII; it should have a unibyte representation +for the POSIX Portable Character Set (PPCS) +\*<https://pubs\*:.opengroup\*:.org/\*:onlinepubs/\*:9699919799/\*:basedefs/\*:V1_chap06\*:.html\*> +and the encoding's non-unibyte characters should consist entirely of +non-PPCS bytes. Non-PPCS characters typically occur only in comments: +although output file names and time zone abbreviations can contain +nearly any character, other software will work better if these are +limited to the restricted syntax described under the +.B \*-v +option. +.PP +Input lines are made up of fields. +Fields are separated from one another by one or more white space characters. +The white space characters are space, form feed, carriage return, newline, +tab, and vertical tab. +Leading and trailing white space on input lines is ignored. +An unquoted sharp character (#) in the input introduces a comment which extends +to the end of the line the sharp character appears on. +White space characters and sharp characters may be enclosed in double quotes +(") if they're to be used as part of a field. +Any line that is blank (after comment stripping) is ignored. +Nonblank lines are expected to be of one of three types: +rule lines, zone lines, and link lines. +.PP +Names must be in English and are case insensitive. +They appear in several contexts, and include month and weekday names +and keywords such as +.BR "maximum" , +.BR "only" , +.BR "Rolling" , +and +.BR "Zone" . +A name can be abbreviated by omitting all but an initial prefix; any +abbreviation must be unambiguous in context. +.PP +A rule line has the form +.nf +.ti +2 +.ta \w'Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00w\0\0'u +\w'1:00d\0\0'u +.sp +Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +.sp +For example: +.ti +2 +.sp +Rule US 1967 1973 \*- Apr lastSun 2:00w 1:00d D +.sp +.fi +The fields that make up a rule line are: +.TP +.B NAME +Gives the name of the rule set that contains this line. +The name must start with a character that is neither +an ASCII digit nor +.q \*- +nor +.q + . +To allow for future extensions, +an unquoted name should not contain characters from the set +.ie \n(.g .q \f(CR!$%&\(aq()*,/:;<=>?@[\e]\(ha\(ga{|}\(ti\fP . +.el .ie t .q \f(CW!$%&'()*,/:;<=>?@[\e]^\(ga{|}~\fP . +.el .q !$%&'()*,/:;<=>?@[\e]^`{|}~ . +.TP +.B FROM +Gives the first year in which the rule applies. +Any signed integer year can be supplied; the proleptic Gregorian calendar +is assumed, with year 0 preceding year 1. +Rules can describe times that are not representable as time values, +with the unrepresentable times ignored; this allows rules to be portable +among hosts with differing time value types. +.TP +.B TO +Gives the final year in which the rule applies. +The word +.B maximum +(or an abbreviation) means the indefinite future, and the word +.B only +(or an abbreviation) +may be used to repeat the value of the +.B FROM +field. +.TP +.B \*- +Is a reserved field and should always contain +.q \*- +for compatibility with older versions of +.BR zic . +It was previously known as the +.B TYPE +field, which could contain values to allow a +separate script to further restrict in which +.q types +of years the rule would apply. +.TP +.B IN +Names the month in which the rule takes effect. +Month names may be abbreviated. +.TP +.B ON +Gives the day on which the rule takes effect. +Recognized forms include: +.nf +.in +2 +.sp +.ta \w'Sun<=25\0\0'u +5 the fifth of the month +lastSun the last Sunday in the month +lastMon the last Monday in the month +Sun>=8 first Sunday on or after the eighth +Sun<=25 last Sunday on or before the 25th +.fi +.in +.sp +A weekday name (e.g., +.BR "Sunday" ) +or a weekday name preceded by +.q "last" +(e.g., +.BR "lastSunday" ) +may be abbreviated or spelled out in full. +There must be no white space characters within the +.B ON +field. +The +.q <= +and +.q >= +constructs can result in a day in the neighboring month; +for example, the IN-ON combination +.q "Oct Sun>=31" +stands for the first Sunday on or after October 31, +even if that Sunday occurs in November. +.TP +.B AT +Gives the time of day at which the rule takes effect, +relative to 00:00, the start of a calendar day. +Recognized forms include: +.nf +.in +2 +.sp +.ta \w'00:19:32.13\0\0'u +2 time in hours +2:00 time in hours and minutes +01:28:14 time in hours, minutes, and seconds +00:19:32.13 time with fractional seconds +12:00 midday, 12 hours after 00:00 +15:00 3 PM, 15 hours after 00:00 +24:00 end of day, 24 hours after 00:00 +260:00 260 hours after 00:00 +\*-2:30 2.5 hours before 00:00 +\*- equivalent to 0 +.fi +.in +.sp +Although +.B zic +rounds times to the nearest integer second +(breaking ties to the even integer), the fractions may be useful +to other applications requiring greater precision. +The source format does not specify any maximum precision. +Any of these forms may be followed by the letter +.B w +if the given time is local or +.q "wall clock" +time, +.B s +if the given time is standard time without any adjustment for daylight saving, +or +.B u +(or +.B g +or +.BR z ) +if the given time is universal time; +in the absence of an indicator, +local (wall clock) time is assumed. +These forms ignore leap seconds; for example, +if a leap second occurs at 00:59:60 local time, +.q "1:00" +stands for 3601 seconds after local midnight instead of the usual 3600 seconds. +The intent is that a rule line describes the instants when a +clock/calendar set to the type of time specified in the +.B AT +field would show the specified date and time of day. +.TP +.B SAVE +Gives the amount of time to be added to local standard time when the rule is in +effect, and whether the resulting time is standard or daylight saving. +This field has the same format as the +.B AT +field +except with a different set of suffix letters: +.B s +for standard time and +.B d +for daylight saving time. +The suffix letter is typically omitted, and defaults to +.B s +if the offset is zero and to +.B d +otherwise. +Negative offsets are allowed; in Ireland, for example, daylight saving +time is observed in winter and has a negative offset relative to +Irish Standard Time. +The offset is merely added to standard time; for example, +.B zic +does not distinguish a 10:30 standard time plus an 0:30 +.B SAVE +from a 10:00 standard time plus a 1:00 +.BR SAVE . +.TP +.B LETTER/S +Gives the +.q "variable part" +(for example, the +.q "S" +or +.q "D" +in +.q "EST" +or +.q "EDT" ) +of time zone abbreviations to be used when this rule is in effect. +If this field is +.q \*- , +the variable part is null. +.PP +A zone line has the form +.sp +.nf +.ti +2 +.ta \w'Zone\0\0'u +\w'Asia/Amman\0\0'u +\w'STDOFF\0\0'u +\w'Jordan\0\0'u +\w'FORMAT\0\0'u +Zone NAME STDOFF RULES FORMAT [UNTIL] +.sp +For example: +.sp +.ti +2 +Zone Asia/Amman 2:00 Jordan EE%sT 2017 Oct 27 01:00 +.sp +.fi +The fields that make up a zone line are: +.TP +.B NAME +The name of the timezone. +This is the name used in creating the time conversion information file for the +timezone. +It should not contain a file name component +.q ".\&" +or +.q ".." ; +a file name component is a maximal substring that does not contain +.q "/" . +.TP +.B STDOFF +The amount of time to add to UT to get standard time, +without any adjustment for daylight saving. +This field has the same format as the +.B AT +and +.B SAVE +fields of rule lines, except without suffix letters; +begin the field with a minus sign if time must be subtracted from UT. +.TP +.B RULES +The name of the rules that apply in the timezone or, +alternatively, a field in the same format as a rule-line SAVE column, +giving the amount of time to be added to local standard time +and whether the resulting time is standard or daylight saving. +If this field is +.B \*- +then standard time always applies. +When an amount of time is given, only the sum of standard time and +this amount matters. +.TP +.B FORMAT +The format for time zone abbreviations. +The pair of characters +.B %s +is used to show where the +.q "variable part" +of the time zone abbreviation goes. +Alternatively, a format can use the pair of characters +.B %z +to stand for the UT offset in the form +.RI \(+- hh , +.RI \(+- hhmm , +or +.RI \(+- hhmmss , +using the shortest form that does not lose information, where +.IR hh , +.IR mm , +and +.I ss +are the hours, minutes, and seconds east (+) or west (\-) of UT. +Alternatively, +a slash (/) +separates standard and daylight abbreviations. +To conform to POSIX, a time zone abbreviation should contain only +alphanumeric ASCII characters, +.q "+" +and +.q "\*-". +By convention, the time zone abbreviation +.q "\*-00" +is a placeholder that means local time is unspecified. +.TP +.B UNTIL +The time at which the UT offset or the rule(s) change for a location. +It takes the form of one to four fields YEAR [MONTH [DAY [TIME]]]. +If this is specified, +the time zone information is generated from the given UT offset +and rule change until the time specified, which is interpreted using +the rules in effect just before the transition. +The month, day, and time of day have the same format as the IN, ON, and AT +fields of a rule; trailing fields can be omitted, and default to the +earliest possible value for the missing fields. +.IP +The next line must be a +.q "continuation" +line; this has the same form as a zone line except that the +string +.q "Zone" +and the name are omitted, as the continuation line will +place information starting at the time specified as the +.q "until" +information in the previous line in the file used by the previous line. +Continuation lines may contain +.q "until" +information, just as zone lines do, indicating that the next line is a further +continuation. +.PP +If a zone changes at the same instant that a rule would otherwise take +effect in the earlier zone or continuation line, the rule is ignored. +A zone or continuation line +.I L +with a named rule set starts with standard time by default: +that is, any of +.IR L 's +timestamps preceding +.IR L 's +earliest rule use the rule in effect after +.IR L 's +first transition into standard time. +In a single zone it is an error if two rules take effect at the same +instant, or if two zone changes take effect at the same instant. +.PP +If a continuation line subtracts +.I N +seconds from the UT offset after a transition that would be +interpreted to be later if using the continuation line's UT offset and +rules, the +.q "until" +time of the previous zone or continuation line is interpreted +according to the continuation line's UT offset and rules, and any rule +that would otherwise take effect in the next +.I N +seconds is instead assumed to take effect simultaneously. +For example: +.br +.ne 7 +.nf +.in +2 +.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'2006\0\0'u +\w'\*-\0\0'u +\w'Oct\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +# Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +Rule US 1967 2006 - Oct lastSun 2:00 0 S +Rule US 1967 1973 - Apr lastSun 2:00 1:00 D +.ta \w'# Zone\0\0'u +\w'America/Menominee\0\0'u +\w'STDOFF\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u +# Zone NAME STDOFF RULES FORMAT [UNTIL] +Zone America/Menominee \*-5:00 \*- EST 1973 Apr 29 2:00 + \*-6:00 US C%sT +.sp +.in +.fi +Here, an incorrect reading would be there were two clock changes on 1973-04-29, +the first from 02:00 EST (\*-05) to 01:00 CST (\*-06), +and the second an hour later from 02:00 CST (\*-06) to 03:00 CDT (\*-05). +However, +.B zic +interprets this more sensibly as a single transition from 02:00 CST (\*-05) to +02:00 CDT (\*-05). +.PP +A link line has the form +.sp +.nf +.ti +2 +.ta \w'Link\0\0'u +\w'Europe/Istanbul\0\0'u +Link TARGET LINK-NAME +.sp +For example: +.sp +.ti +2 +Link Europe/Istanbul Asia/Istanbul +.sp +.fi +The +.B TARGET +field should appear as the +.B NAME +field in some zone line or as the +.B LINK-NAME +field in some link line. +The +.B LINK-NAME +field is used as an alternative name for that zone; +it has the same syntax as a zone line's +.B NAME +field. +Links can chain together, although the behavior is unspecified if a +chain of one or more links does not terminate in a Zone name. +A link line can appear before the line that defines the link target. +For example: +.sp +.ne 3 +.nf +.in +2 +.ta \w'Zone\0\0'u +\w'Greenwich\0\0'u +Link Greenwich G_M_T +Link Etc/GMT Greenwich +Zone Etc/GMT\0\00\0\0\*-\0\0GMT +.sp +.in +.fi +The two links are chained together, and G_M_T, Greenwich, and Etc/GMT +all name the same zone. +.PP +Except for continuation lines, +lines may appear in any order in the input. +However, the behavior is unspecified if multiple zone or link lines +define the same name. +.PP +The file that describes leap seconds can have leap lines and an +expiration line. +Leap lines have the following form: +.nf +.ti +2 +.ta \w'Leap\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +\w'HH:MM:SS\0\0'u +\w'CORR\0\0'u +.sp +Leap YEAR MONTH DAY HH:MM:SS CORR R/S +.sp +For example: +.ti +2 +.sp +Leap 2016 Dec 31 23:59:60 + S +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields tell when the leap second happened. +The +.B CORR +field +should be +.q "+" +if a second was added +or +.q "\*-" +if a second was skipped. +The +.B R/S +field +should be (an abbreviation of) +.q "Stationary" +if the leap second time given by the other fields should be interpreted as UTC +or +(an abbreviation of) +.q "Rolling" +if the leap second time given by the other fields should be interpreted as +local (wall clock) time. +.PP +Rolling leap seconds were implemented back when it was not +clear whether common practice was rolling or stationary, +with concerns that one would see +Times Square ball drops where there'd be a +.q "3... 2... 1... leap... Happy New Year" +countdown, placing the leap second at +midnight New York time rather than midnight UTC. +However, this countdown style does not seem to have caught on, +which means rolling leap seconds are not used in practice; +also, they are not supported if the +.B \*-r +option is used. +.PP +The expiration line, if present, has the form: +.nf +.ti +2 +.ta \w'Expires\0\0'u +\w'YEAR\0\0'u +\w'MONTH\0\0'u +\w'DAY\0\0'u +.sp +Expires YEAR MONTH DAY HH:MM:SS +.sp +For example: +.ti +2 +.sp +Expires 2020 Dec 28 00:00:00 +.sp +.fi +The +.BR YEAR , +.BR MONTH , +.BR DAY , +and +.B HH:MM:SS +fields give the expiration timestamp in UTC for the leap second table. +.br +.ne 22 +.SH "EXTENDED EXAMPLE" +Here is an extended example of +.B zic +input, intended to illustrate many of its features. +.nf +.in +2 +.ta \w'# Rule\0\0'u +\w'NAME\0\0'u +\w'FROM\0\0'u +\w'1973\0\0'u +\w'\*-\0\0'u +\w'Apr\0\0'u +\w'lastSun\0\0'u +\w'2:00\0\0'u +\w'SAVE\0\0'u +.sp +# Rule NAME FROM TO \*- IN ON AT SAVE LETTER/S +Rule Swiss 1941 1942 \*- May Mon>=1 1:00 1:00 S +Rule Swiss 1941 1942 \*- Oct Mon>=1 2:00 0 \*- +.sp .5 +Rule EU 1977 1980 \*- Apr Sun>=1 1:00u 1:00 S +Rule EU 1977 only \*- Sep lastSun 1:00u 0 \*- +Rule EU 1978 only \*- Oct 1 1:00u 0 \*- +Rule EU 1979 1995 \*- Sep lastSun 1:00u 0 \*- +Rule EU 1981 max \*- Mar lastSun 1:00u 1:00 S +Rule EU 1996 max \*- Oct lastSun 1:00u 0 \*- +.sp +.ta \w'# Zone\0\0'u +\w'Europe/Zurich\0\0'u +\w'0:29:45.50\0\0'u +\w'RULES\0\0'u +\w'FORMAT\0\0'u +# Zone NAME STDOFF RULES FORMAT [UNTIL] +Zone Europe/Zurich 0:34:08 \*- LMT 1853 Jul 16 + 0:29:45.50 \*- BMT 1894 Jun + 1:00 Swiss CE%sT 1981 + 1:00 EU CE%sT +.sp +Link Europe/Zurich Europe/Vaduz +.sp +.in +.fi +In this example, the EU rules are for the European Union +and for its predecessor organization, the European Communities. +The timezone is named Europe/Zurich and it has the alias Europe/Vaduz. +This example says that Zurich was 34 minutes and 8 +seconds east of UT until 1853-07-16 at 00:00, when the legal offset +was changed to +7\*d\*_26\*m\*_22.50\*s, +which works out to 0:29:45.50; +.B zic +treats this by rounding it to 0:29:46. +After 1894-06-01 at 00:00 the UT offset became one hour +and Swiss daylight saving rules (defined with lines beginning with +.q "Rule Swiss") +apply. From 1981 to the present, EU daylight saving rules have +applied, and the UTC offset has remained at one hour. +.PP +In 1941 and 1942, daylight saving time applied from the first Monday +in May at 01:00 to the first Monday in October at 02:00. +The pre-1981 EU daylight-saving rules have no effect +here, but are included for completeness. Since 1981, daylight +saving has begun on the last Sunday in March at 01:00 UTC. +Until 1995 it ended the last Sunday in September at 01:00 UTC, +but this changed to the last Sunday in October starting in 1996. +.PP +For purposes of display, +.q "LMT" +and +.q "BMT" +were initially used, respectively. Since +Swiss rules and later EU rules were applied, the time zone abbreviation +has been CET for standard time and CEST for daylight saving +time. +.SH FILES +.TP +.I /etc/localtime +Default local timezone file. +.TP +.I /usr/share/zoneinfo +Default timezone information directory. +.SH NOTES +For areas with more than two types of local time, +you may need to use local standard time in the +.B AT +field of the earliest transition time's rule to ensure that +the earliest transition time recorded in the compiled file is correct. +.PP +If, +for a particular timezone, +a clock advance caused by the start of daylight saving +coincides with and is equal to +a clock retreat caused by a change in UT offset, +.B zic +produces a single transition to daylight saving at the new UT offset +without any change in local (wall clock) time. +To get separate transitions +use multiple zone continuation lines +specifying transition instants using universal time. +.SH SEE ALSO +.BR tzfile (5), +.BR zdump (8) |