{
	"problemMatcher": [
		{
			"owner": "tcltest",
			"pattern": [
				{
					"regexp": "^==== ([-\\w]+) (.+) (FAILED)$",
					"severity": 3,
					"message": 2,
					"code": 1
				}
			]
		}
	]
}

# This workflow is meant for development use and run only on demand.
# It is customizable to select
#   - Platforms
#   - Toolchains
#   - Branches (no need for core-* prefixes)
#   - Tests
# To run the workflow, select "Custom" on the left side in the GH Actions
# page. Then click the Run workflow button on the right. This will display
# a dropdown that allows customization as above.
#
# To run the workflow, you need to have permissions to the repository.
# The simplest way is to clone the Tcl mirror on Github. However, that means
# if you work in fossil, you have a potential 24-hour wait before the mirror
# updates, which apart from nostalgia about the punched card batch processing
# era, is not so convenient. My preference instead is to mirror the fossil
# repository to Github via a local checkout on my system, do the work there
# pushing to github and running this workflow to verify across platforms
# and then committing back to the master fossil repository.
#
# Improvements to the workflow welcome.

name: Custom

on:
  workflow_dispatch:
    inputs:
      platform:
        description: 'Target platform(s)")'
        required: true
        default: 'all'
        type: choice
        options:
          - all
          - windows
          - linux
          - macos

      windows_toolchains:
        description: 'Windows toolchain'
        required: true
        type: choice
        options:
          - '["nmake", "msys"]'
          - '["nmake"]'
          - '["msys"]'
        default: '["nmake"]'

      windows_architectures:
        description: 'Architecture (Windows Nmake only)'
        required: true
        type: choice
        options:
          - '["x64"]'
          - '["x86"]'
          - '["x64", "x86"]'
        default: '["x64"]'

      linux_compiler:
        description: 'Linux compiler'
        required: true
        default: 'gcc'
        type: choice
        options:
          - gcc
          - clang
      run_tests:
        description: 'Run tests'
        required: false
        default: true
        type: boolean
      test_flags:
        description: 'TESTFLAGS'
        required: false
        default: ''

jobs:
  windows:
    if: ${{ github.event.inputs.platform == 'windows' || github.event.inputs.platform == 'all' }}
    runs-on: windows-latest
    strategy:
      matrix:
        arch: ${{ fromJSON(github.event.inputs.windows_architectures) }}
        toolchain: ${{ fromJSON(github.event.inputs.windows_toolchains) }}
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ github.ref }}

      # Nmake builds
      - name: Setup MSVC (for nmake)
        if: ${{ matrix.toolchain == 'nmake' }}
        uses: ilammy/msvc-dev-cmd@v1
        with:
          arch: ${{ matrix.arch }}

      - name: Build with nmake (Visual C++)
        if: ${{ matrix.toolchain == 'nmake' }}
        shell: cmd
        env:
          ERROR_ON_FAILURES: 1
        working-directory: win
        run: |
          nmake /s /f makefile.vc

      - name: Tests with nmake (Visual C++)
        if: ${{ matrix.toolchain == 'nmake' && inputs.run_tests != 'false' }}
        shell: cmd
        env:
          ERROR_ON_FAILURES: 1
          TESTFLAGS: ${{ github.event.inputs.test_flags }}
        working-directory: win
        run: |
          echo TESTFLAGS=%TESTFLAGS%
          nmake /s /f makefile.vc test

      # Msys builds

      - name: Set up msys2 (x64)
        if: ${{ matrix.toolchain == 'msys' && matrix.arch == 'x64'}}
        uses: msys2/setup-msys2@v2
        with:
          msystem: UCRT64
          pacboy: "git: make: gcc:p"
          path-type: minimal
          release: true
          update: false
          cache: true

      - name: Set up msys2 (x86)
        if: ${{ matrix.toolchain == 'msys' && matrix.arch == 'x86'}}
        uses: msys2/setup-msys2@v2
        with:
          msystem: MINGW32
          pacboy: "git: make: gcc:p"
          path-type: minimal
          release: true
          update: false
          cache: true

      - name: Verify toolchain
        if: ${{ matrix.toolchain == 'msys' }}
        shell: bash -l {0}
        run: |
          gcc -v
          make -v

      - name: Configure with MSYS
        if: ${{ matrix.toolchain == 'msys' }}
        env:
          ERROR_ON_FAILURES: 1
        working-directory: win
        shell: msys2 {0}
        run: |
          mkdir build
          cd build
          ../configure

      - name: Compile with MSYS
        if: ${{ matrix.toolchain == 'msys' }}
        env:
          ERROR_ON_FAILURES: 1
        shell: msys2 {0}
        working-directory: win\build
        run: |
          file ../../libtommath/win32/tommath.lib
          make -s

      - name: Tests with MSYS
        if: ${{ matrix.toolchain == 'msys' && inputs.run_tests != 'false' }}
        env:
          ERROR_ON_FAILURES: 1
          TESTFLAGS: ${{ github.event.inputs.test_flags }}
        working-directory: win\build
        shell: msys2 {0}
        run: |
          echo TESTFLAGS=$TESTFLAGS
          make -s test

  linux:
    if: ${{ github.event.inputs.platform == 'linux' || github.event.inputs.platform == 'all' }}
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ github.ref }}

      - name: Configure with ${{ github.event.inputs.linux_compiler }}
        env:
          ERROR_ON_FAILURES: 1
          CC: ${{ github.event.inputs.linux_compiler }}
        working-directory: unix
        run: |
          mkdir build
          cd build
          echo CC=$CC
          ../configure || (cat config.log && exit 1)

      - name: Compile
        working-directory: unix/build
        run: |
          make -s

      - name: Run tests
        if: ${{ inputs.run_tests != 'false' }}
        env:
          ERROR_ON_FAILURES: 1
          TESTFLAGS: ${{ github.event.inputs.test_flags }}
        working-directory: unix/build
        run: |
          echo TESTFLAGS=$TESTFLAGS
          make -s test

  macos:
    if: ${{ github.event.inputs.platform == 'macos' || github.event.inputs.platform == 'all' }}
    runs-on: macos-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          ref: ${{ github.ref }}

      - name: Configure
        env:
          ERROR_ON_FAILURES: 1
        working-directory: unix
        run: |
          mkdir build
          cd build
          ../configure --enable-framework || (cat config.log && exit 1)
          make -s

      - name: Compile
        working-directory: unix/build
        run: |
          make -s

      - name: Run tests
        if: ${{ inputs.run_tests != 'false' }}
        env:
          ERROR_ON_FAILURES: 1
          TESTFLAGS: ${{ github.event.inputs.test_flags }}
        working-directory: unix/build
        run: |
          echo TESTFLAGS=$TESTFLAGS
          make -s test

name: Linux
on:
  push:
    branches:
    - "main"
    - "core-9-1-branch"
    tags:
    - "core-*"

permissions:
  contents: read
jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      gcc: ${{ steps.matrix.outputs.gcc }}
    steps:
      - name: Select build matrix based on branch name
        id: matrix
        run: |
          (
            echo gcc=$(jq -nc '{config: (if env.IsMatched == "true" then env.FULL else env.PARTIAL end) | fromjson }' )
          ) | tee -a $GITHUB_OUTPUT
        env:
          IsMatched: ${{ github.ref_name == 'main' || github.ref_name == 'core-9-1-branch' }}
          # DO NOT CHANGE THESE MATRIX SPECS; IT AFFECTS OUR COST CONTROLS
          FULL: >
            [
              "",
              "CFLAGS=-DTCL_NO_DEPRECATED=1",
              "--disable-shared",
              "--disable-zipfs",

            [
              "",
              "--enable-symbols=all",
              "CFLAGS=-m32 CPPFLAGS=-m32 LDFLAGS=-m32 --disable-64bit"
            ]
  gcc:
    needs: plan
    runs-on: ubuntu-24.04
    strategy:
      matrix: ${{ fromJson(needs.plan.outputs.gcc) }}
    defaults:
      run:
        shell: bash
        working-directory: unix
    steps:

        timeout-minutes: 5
      - name: Info
        run: |
          ulimit -a || echo 'get limit failed'
          make runtest SCRIPT=../.github/workflows/info.tcl || echo 'get info failed'
      - name: Run Tests
        run: |
          echo "::add-matcher::.github/tcltest.json"
          make test
          echo "::remove-matcher::.github/tcltest.json"
        env:
          ERROR_ON_FAILURES: 1

        timeout-minutes: 30
      - name: Test-Drive Installation
        run: |
          make install
        timeout-minutes: 5
      - name: Create Distribution Package
        if: ${{ matrix.config == '' }}

name: macOS
on:
  push:
    branches:
    - "main"
    - "core-9-1-branch"
    tags:
    - "core-*"

permissions:
  contents: read
jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      clang: ${{ steps.matrix.outputs.clang }}
    steps:
      - name: Select build matrix based on branch name
        id: matrix
        run: |
          (
            echo clang=$(jq -nc '{config: (if env.IsMatched == "true" then env.FULL else env.PARTIAL end) | fromjson }' )
          ) | tee -a $GITHUB_OUTPUT
        env:
          IsMatched: ${{ github.ref_name == 'main' || github.ref_name == 'core-9-1-branch' }}
          # DO NOT CHANGE THIS MATRIX SPEC; IT AFFECTS OUR COST CONTROLS
          FULL: >
            [
              "",
              "--disable-shared",
              "--disable-zipfs",
              "--enable-symbols",
              "--enable-symbols=mem",
              "--enable-symbols=all"
            ]
          PARTIAL: >
            [
              "",
              "--enable-symbols=all"
            ]
  xcode:
    runs-on: macos-26
    defaults:
      run:
        shell: bash
        working-directory: macosx
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        timeout-minutes: 5
      - name: Prepare
        run: |
          touch tclStubInit.c tclOOStubInit.c tclOOScript.h
        working-directory: generic
      - name: Build
        run: make -j4 all
        env:
          CFLAGS: -arch x86_64 -arch arm64
        timeout-minutes: 15
      - name: Run Tests
        run: |
          echo "::add-matcher::.github/tcltest.json"
          make -j4 test styles=develop
        env:
          ERROR_ON_FAILURES: 1
          MAC_CI: 1
        timeout-minutes: 15
  clang:
    runs-on: macos-26
    needs: plan
    strategy:
      matrix: ${{ fromJson(needs.plan.outputs.clang) }}
    defaults:
      run:
        shell: bash
        working-directory: unix

        timeout-minutes: 15
      - name: Info
        run: |
          ulimit -a || echo 'get limit failed'
          make runtest SCRIPT=../.github/workflows/info.tcl || echo 'get info failed'
      - name: Run Tests
        run: |
          echo "::add-matcher::.github/tcltest.json"
          make test
        env:
          ERROR_ON_FAILURES: 1
          MAC_CI: 1
        timeout-minutes: 20

name: Build Binaries
on:
  push:
    branches:
    - "main"
    - "core-9-1-branch"
    tags:
    - "core-*"

permissions:
  contents: read
jobs:
  linux:
    name: Linux
    runs-on: ubuntu-24.04
    defaults:

          name: Tclsh ${{ env.TCL_PATCHLEVEL }} macOS single-file build (snapshot)
          path: 1dist/*.dmg
        id: upload
    outputs:
      url: ${{ steps.upload.outputs.artifact-url }}
  win:
    name: Windows
    runs-on: windows-2025-vs2026
    defaults:
      run:
        shell: msys2 {0}
    timeout-minutes: 10
    env:
      CC: gcc
      CFGOPT: --disable-symbols --disable-shared

      url: ${{ steps.upload.outputs.artifact-url }}
  combine:
    needs:
      - linux
      - macos
      - win
    name: Combine Artifacts (prototype)
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    timeout-minutes: 10
    env:
      # See also
      # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/store-information-in-variables

          merge-multiple: true
      - name: Check data downloaded
        run: |
          ls -AlR
        working-directory: data
      - name: Transfer built files
        # https://github.com/marketplace/actions/rsync-deployments-action
        uses: burnett01/rsync-deployments@9.0.0
        id: rsync
        if: false  # Disabled... for now
        with:
          # I don't know what the right switches are here, BTW
          switches: -avzr
          path: data/
          remote_path: ${{ env.REMOTE_PATH }}

name: Windows
on:
  push:
    branches:
    - "main"
    - "core-9-1-branch"
    tags:
    - "core-*"

permissions:
  contents: read
jobs:
  plan:
    runs-on: ubuntu-latest
    outputs:
      msvc: ${{ steps.matrix.outputs.msvc }}
      gcc: ${{ steps.matrix.outputs.gcc }}
    steps:
      - name: Select build matrix based on branch name
        id: matrix
        run: |
          (
            echo msvc=$(jq -nc '{config: (if env.IsMatched == "true" then env.MSVC_FULL else env.MSVC_PARTIAL end) | fromjson }' )
            echo gcc=$(jq -nc '{config: (if env.IsMatched == "true" then env.GCC_FULL else env.GCC_PARTIAL end) | fromjson }' )
          ) | tee -a $GITHUB_OUTPUT
        env:
          IsMatched: ${{ github.ref_name == 'main' || github.ref_name == 'core-9-1-branch' }}
          # DO NOT CHANGE THESE MATRIX SPECS; IT AFFECTS OUR COST CONTROLS
          MSVC_FULL: >
            [
              "",
              "CHECKS=nodep",
              "OPTS=static",
              "OPTS=noembed",

          GCC_PARTIAL: >
            [
              "",
              "--disable-shared",
              "--enable-symbols=all"
            ]
  msvc:
    runs-on: windows-2025-vs2026
    needs: plan
    defaults:
      run:
        shell: powershell
        working-directory: win
    strategy:
      matrix: ${{ fromJson(needs.plan.outputs.msvc) }}
    # Using powershell means we need to explicitly stop on failure
    steps:
      - name: Checkout
        uses: actions/checkout@v7
        timeout-minutes: 5
      - name: Init MSVC
        uses: ilammy/msvc-dev-cmd@v1
        timeout-minutes: 5



      - name: Build ${{ matrix.config }}
        run: |
          &nmake -f makefile.vc ${{ matrix.config }} all
          if ($lastexitcode -ne 0) {
             throw "nmake exit code: $lastexitcode"
          }
        timeout-minutes: 5
      - name: Build Test Harness ${{ matrix.config }}
        run: |
          &nmake -f makefile.vc ${{ matrix.config }} tcltest
          if ($lastexitcode -ne 0) {
             throw "nmake exit code: $lastexitcode"
          }
        timeout-minutes: 5
      - name: Run Tests ${{ matrix.config }}
        run: |
          Write-Output "::add-matcher::.github/tcltest.json"
          &nmake -f makefile.vc ${{ matrix.config }} test
          if ($lastexitcode -ne 0) {
             throw "nmake exit code: $lastexitcode"
          }
        timeout-minutes: 30
        env:
          ERROR_ON_FAILURES: 1
  gcc:
    runs-on: windows-2025-vs2026
    needs: plan
    defaults:
      run:
        shell: msys2 {0}
        working-directory: win
    strategy:
      matrix: ${{ fromJson(needs.plan.outputs.gcc) }}

        run: make -j4 tcltest
        timeout-minutes: 5
      - name: Info
        run: |
          ulimit -a || echo 'get limit failed'
          make runtest SCRIPT=../.github/workflows/info.tcl || echo 'get info failed'
      - name: Run Tests
        run: |
          echo "::add-matcher::.github/tcltest.json"
          make test
        timeout-minutes: 30
        env:
          ERROR_ON_FAILURES: 1
      - name: Install
        run: make install
        timeout-minutes: 5

# If you add builds with Wine, be sure to define the environment variable
# CI_USING_WINE when running them so that broken tests know not to run.

<?xml version="1.0" encoding="UTF-8"?>
<projectDescription>
	<name>tcl9.1</name>
	<comment></comment>
	<projects>
	</projects>
	<buildSpec>
	</buildSpec>
	<natures>
	</natures>

# README:  Tcl

This is the **Tcl 9.1b1** source distribution.

You can get any source release of Tcl from [our distribution
site](https://sourceforge.net/projects/tcl/files/Tcl/).

9.1 (in development, daily build)
[![Build Status](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions/workflows/linux-build.yml?query=branch%3Amain)
[![Build Status](https://github.com/tcltk/tcl/actions/workflows/win-build.yml/badge.svg?branch=main)](https://github.com/tcltk/tcl/actions/workflows/win-build.yml?query=branch%3Amain)

anything you like with it, such as modifying it, redistributing it,
and selling it either in whole or in part.  See the file
`license.terms` for complete information.

## <a id="doc">2.</a> Documentation
Extensive documentation is available on our website.
The home page for this release, including new features, is
[here](https://www.tcl-lang.org/software/tcltk/9.1.html).
Detailed release notes can be found at the
[file distributions page](https://sourceforge.net/projects/tcl/files/Tcl/)
by clicking on the relevant version.

Information about Tcl itself can be found at the [Developer
Xchange](https://www.tcl-lang.org/about/).
There have been many Tcl books on the market.  Many are mentioned in
[the Wiki](https://wiki.tcl-lang.org/_/ref?N=25206).

The complete set of reference manual entries for Tcl 9.1 is [online,
here](https://www.tcl-lang.org/man/tcl9.1/).

### <a id="doc.unix"></a> Unix man pages
The `doc` subdirectory in this release contains a complete set of
reference manual entries for Tcl.  Files with extension "`.1`" are for
programs (for example, `tclsh.1`); files with extension "`.3`" are for C
library procedures; and files with extension "`.n`" describe Tcl
commands.  The file "`doc/Tcl.n`" gives a quick summary of the Tcl
language syntax.  To print any of the man pages on Unix, cd to the
"doc" directory and invoke your favorite variant of troff using the
normal -man macros, for example

		groff -man -Tpdf Tcl.n >output.pdf

to print Tcl.n to PDF.  If Tcl has been installed correctly and your "man" program
supports it, you should be able to access the Tcl manual entries using the
normal "man" mechanisms, such as

		man Tcl








## <a id="build">3.</a> Compiling and installing Tcl
There are brief notes in the `unix/README`, `win/README`, and `macosx/README`
about compiling on these different platforms.  There is additional information
about building Tcl from sources
[online](https://www.tcl-lang.org/doc/howto/compile.html).

## <a id="news">4.</a> News feeds






You can keep up with the latest happenings in the Tcl world via
[fosstodon](https://fosstodon.org/@tcl_tk) or
[X](https://twitter.com/TclLang) feeds.

## <a id="complangtcl">5.</a> Tcl newsgroup
There is a USENET newsgroup, "`comp.lang.tcl`", intended for the exchange of
information about Tcl, Tk, and related applications.  The newsgroup is a
great place to ask general information questions.  For bug reports, please
see the "Support and bug fixes" section below.

The source code for Tcl is managed by fossil.  Tcl developers coordinate all
changes to the Tcl source code at

> [Tcl Source Code](https://core.tcl-lang.org/tcl/timeline)






































































































































Release Tcl 9.1b1 arises from the check-in with tag `core-9-1-b1`.





































Highlighted differences between Tcl 9.1 and Tcl 9.0 are summarized below,
with focus on changes important to programmers using the Tcl library and
writing Tcl scripts.

# New commands and options

- [New options `-backslashes`, `-commands` and `-variables` for `subst` command](https://core.tcl-lang.org/tips/doc/trunk/tip/712.md)
- [New command `unicode` for Unicode normalization](https://core.tcl-lang.org/tips/doc/trunk/tip/726.md)
- [New `timer` command, switch to monotonic clock and microsecond resolution](https://core.tcl-lang.org/tips/doc/trunk/tip/723.md)
- [Remove `expr` behavior from `lseq`](https://core.tcl-lang.org/tips/doc/trunk/tip/746.md) *Incompatibility*
- [File paths are now treated as case-insensitive on MacOS](https://core.tcl-lang.org/tcl/tktview/e6ca0b1b) *Incompatibility*





- New command `tcl::registry` as a synonym for the `registry` command without needing

the registry package to be loaded. The registry module is now part of the core


Tcl DLL in all build configurations.
- [New `lfilter` command for selecting items from a list](https://core.tcl-lang.org/tips/doc/trunk/tip/735.md)


- [Many new functions from C99](https://core.tcl-lang.org/tips/doc/trunk/tip/745.md), specifically: `acosh()`, `asinh()`, `atanh()`, `cbrt()`, `copysign()`, `dim()`,  `erf()`, `erfc()`, `exp2()`, `expm1()`, `fma()`, `gamma()`, `ldexp()`, `lgamma()`, `log1p()`, `log2()`, `logb()`, `nextafter()`, `remainder()`, `signbit()`, and `trunc()`, and (for functions that return multiple values in their C99 API) the commands: `divmod`, `frexp`, `modf`, and `remquo`. (See [this page](https://en.cppreference.com/w/c/numeric/math.html) for more information about these functions; the Tcl functions are _intentionally_ only thin wrappers around the functions in the C99 standard.)

- [New `switch` option `-integer` to compare values as integers](https://core.tcl-lang.org/tips/doc/trunk/tip/730.md)






- [Reading and writing of child interpreter variables](https://core.tcl-lang.org/tips/doc/trunk/tip/728.md)
- [Updated Tcl Bytecode opcodes](https://core.tcl-lang.org/tips/doc/trunk/tip/720.md)

- New `tcltest::configure` option `-iterations` to control number of iterations of each test.
















# New public C API

- [`Tcl_IsEmpty()` — checks if the string representation of a value would be the empty string](https://core.tcl-lang.org/tips/doc/trunk/tip/711.md)
- [`Tcl_GetEncodingNameForUser()` — returns name of encoding from user settings](https://core.tcl-lang.org/tips/doc/trunk/tip/716.md)
- [`Tcl_AttemptCreateHashEntry()` — version of `Tcl_CreateHashEntry()` that returns NULL instead of panic'ing on memory allocation errors](https://core.tcl-lang.org/tips/doc/trunk/tip/717.md)
- [`Tcl_ListObjRange()`, `Tcl_ListObjRepeat()`, `Tcl_ListObjReverse()` — C API for new list operations](https://core.tcl-lang.org/tips/doc/trunk/tip/649.md)
- [`Tcl_UtfToNormalized()`, `Tcl_UtfToNormalizedDString()` — C API for Unicode normalization](https://core.tcl-lang.org/tips/doc/trunk/tip/726.md)
- [`Tcl_UtfToExternalEx()` and `Tcl_ExternalToUtfEx()` — C encoding API supporting output buffers larger than INT_MAX](https://core.tcl-lang.org/tips/doc/trunk/tip/737.md)
- [New API for monotonic clock and microseconds resolution](https://core.tcl-lang.org/tips/doc/trunk/tip/723.md)
- [Windows `auto_execok` enhancements and `exec` search reform](https://core.tcl-lang.org/tips/doc/trunk/tip/753.md)
- [New timer API using long long in stead of Tcl_Time](https://core.tcl-lang.org/tips/doc/trunk/tip/752.md)













# Changes in interpreter initialization

- [Custom applications must call Tcl\_FindExecutable or TclZipfs_AppHook to initialize Tcl](https://core.tcl-lang.org/tips/doc/trunk/tip/732.md) *Potential incompatibility*
- [Search path for locating Tcl core script and encodings is changed](https://core.tcl-lang.org/tips/doc/trunk/tip/732.md) *Potential incompatibility*
- [`Tcl_RegisterPostInitProc` callback for post-initialization of interpreters](https://core.tcl-lang.org/tips/doc/trunk/tip/755.md)







# Performance

- [Memory efficient internal representations](https://core.tcl-lang.org/tcl/wiki?name=New+abstract+list+representations)















for list operations on large lists.
- [Continued 64-bit capacity: Command line arguments larger than 2Gb](https://core.tcl-lang.org/tips/doc/trunk/tip/626.md)
- [Support for long paths on Windows](https://core.tcl-lang.org/tips/doc/trunk/tip/744.md)
- [Faster UTF-8 encoding and I/O](https://core.tcl-lang.org/tcl/wiki?name=Faster+UTF+encoding)
- Faster interpreter creation











# Bug fixes
- [Inconsistent `glob` matching on MacOS](https://core.tcl-lang.org/tcl/tktview/e6ca0b1b)
- [`file normalize` does not uniquely identify a file on MacOS](https://core.tcl-lang.org/tcl/tktview/10890417)
- [Inconsistencies between `cd` and `file normalize` for volume-relative paths on Windows](https://core.tcl-lang.org/tcl/tktview/bca391ab)
- [Tcl cannot run from an arbitrary build directory with --disable-zipfs](https://core.tcl-lang.org/tcl/tktview/006bef5d)
- [Crash on finalization with an active thread running.](https://core.tcl-lang.org/tcl/tktview/e55a589d)


- [Crash on use-after-free in Windows socket thread.](https://core.tcl-lang.org/tcl/tktview/06f19cc4)











# Updated bundled packages, libraries, standards, data
 - Unicode 18.0.0 (draft)

 - platorm 1.2b1

/*
 * gettod.c --
 *
 *	This file provides the gettimeofday function on systems
 *	that only have the System V ftime function.
 *
 * Copyright © 1995 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution
 * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#include "tclPort.h"
#include <sys/timeb.h>

/*
 * mkstemp.c --
 *
 *	Source code for the "mkstemp" library routine.
 *
 * Copyright © 2009 Donal K. Fellows
 *
 * See the file "license.terms" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#include <errno.h>
#include <fcntl.h>

/*
 * strncasecmp.c --
 *
 *	Source code for the "strncasecmp" library routine.
 *
 * Copyright © 1988-1993 The Regents of the University of California.
 * Copyright © 1995-1996 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#include "tclPort.h"

/*
 * waitpid.c --
 *
 *	This procedure emulates the POSIX waitpid kernel call on BSD systems
 *	that don't have waitpid but do have wait3. This code is based on a
 *	prototype version written by Mark Diekhans and Karl Lehenbauer.
 *
 * Copyright © 1993 The Regents of the University of California.
 * Copyright © 1994 Sun Microsystems, Inc.
 *
 * See the file "license.terms" for information on usage and redistribution of
 * this file, and for a DISCLAIMER OF ALL WARRANTIES.
 */

#include "tclPort.h"

.nf
\fB#include <tcl.h>\fR
.sp
const char *
\fBTcl_Concat\fR(\fIargc, argv\fR)
.fi
.SH ARGUMENTS
.AS "const char *const" *argv
.AP Tcl_Size argc in
Number of strings.
.AP "const char *const" *argv in
Array of strings to concatenate.  Must have \fIargc\fR entries.
.BE

.SH DESCRIPTION
.PP
\fBTcl_Concat\fR is a utility procedure used by several of the
Tcl commands.  Given a collection of strings, it concatenates

'\"
'\" Copyright (c) 1990 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_CreateTimerHandler, TclCreateTimerHandlerMicroSeconds, Tcl_DeleteTimerHandler \- call a procedure at a given time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_TimerToken
\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
.sp
Tcl_TimerToken
\fBTcl_CreateTimerHandlerMicroSeconds\fR(\fImicroseconds, proc, clientData\fR)
.sp
\fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
.fi
.SH ARGUMENTS
.AS Tcl_TimerToken milliseconds
.AP long_long microseconds  in
How many microseconds to wait before invoking \fIproc\fR.
.AP int milliseconds  in
How many milliseconds to wait before invoking \fIproc\fR.
.AP Tcl_TimerProc *proc in
Procedure to invoke after \fImilliseconds\fR have elapsed.
.AP void *clientData in
Arbitrary one-word value to pass to \fIproc\fR.
.AP Tcl_TimerToken token in
Token for previously created timer handler (the return value
from some previous call to \fBTcl_CreateTimerHandler\fR).
.BE
.SH DESCRIPTION
.PP
\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be
invoked at a time \fImilliseconds\fR milliseconds in the
future.
\fBTcl_CreateTimerHandlerMicroseconds\fR arranges for \fIproc\fR to be
invoked at a time \fImicroseconds\fR microseconds in the
future.
The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR,
so \fBTcl_CreateTimerHandler\fR is only useful in programs that
dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
such as \fBvwait\fR.
The call to \fIproc\fR may not be made at the exact time given by
the parameter:  it will be made at the next opportunity
after that time.  For example, if \fBTcl_DoOneEvent\fR is not
called until long after the time has elapsed, or if there
are other pending events to process before the call to
\fIproc\fR, then the call to \fIproc\fR will be delayed.
.PP
\fIProc\fR should have arguments and return value that match
the type \fBTcl_TimerProc\fR:
.PP
.CS
typedef void \fBTcl_TimerProc\fR(
        void *\fIclientData\fR);
.CE
.PP
The \fIclientData\fR parameter to \fIproc\fR is a
copy of the \fIclientData\fR argument given to
\fBTcl_CreateTimerHandler\fR when the callback
was created.  Typically, \fIclientData\fR points to a data
structure containing application-specific information about
what to do in \fIproc\fR.
.PP
Both functions return a \fBtolken\fR.
In case of \fBTcl_CreateTimerHandlerMicroSeconds\fR, the return value is \fBNULL\fR,
if the given time interval is to much in the future and may not be
represented. This is a theoretical case, as it is in around 26 thousand years.
\fBTcl_CreateTimerHandler\fR does not check for overflow and never returns \fBNULL\fR.
.PP
\fBTcl_DeleteTimerHandler\fR may be called to delete a
previously created timer handler.  It deletes the handler
indicated by \fItoken\fR so that no call to \fIproc\fR
will be made;  if that handler no longer exists
(e.g. because the time period has already elapsed and \fIproc\fR
has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
The tokens returned by \fBTcl_CreateTimerHandler\fR never have
a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
then the procedure does nothing.
.SH "SEE ALSO"
after(n), Tcl_CreateFileHandler(3), Tcl_DoWhenIdle(3)
.SH KEYWORDS
callback, clock, handler, timer

.AP int options in
The options controlling the wait. WNOHANG specifies not to wait when
checking the process.
.BE
.SH DESCRIPTION
.PP
\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
mechanism for managing subprocesses that are running in background.
These procedures are needed because the parent of a process must
eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
similar kernel calls) to wait for the child to exit.  Until the
parent waits for the child, the child's state cannot be completely
reclaimed by the system.  If a parent continually creates children
and doesn't wait on them, the system's process table will eventually
overflow, even if all the children have exited.
.PP
\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
for one or more processes whose process ids are contained in the
\fIpidPtr\fR array passed as argument.  The caller presumably
has started these processes running in background and does not
want to have to deal with them again.
.PP
\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
on each of the background processes so that its state can be cleaned
up if it has exited.  If the process has not exited yet,
\fBTcl_ReapDetachedProcs\fR does not wait for it to exit;  it will check again
the next time it is invoked.

'\"
'\" Copyright (c) 1997-1998 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_GetEncoding, Tcl_FreeEncoding, Tcl_GetEncodingFromObj, Tcl_ExternalToUtfDString, Tcl_ExternalToUtfDStringEx, Tcl_ExternalToUtf,Tcl_ExternalToUtfEx, Tcl_UtfToExternalDString, Tcl_UtfToExternalDStringEx, Tcl_UtfToExternal, Tcl_UtfToExternalEx, Tcl_GetEncodingName, Tcl_SetSystemEncoding, Tcl_GetEncodingNameFromEnvironment, Tcl_GetEncodingNameForUser, Tcl_GetEncodingNames, Tcl_CreateEncoding, Tcl_GetEncodingSearchPath, Tcl_SetEncodingSearchPath \- procedures for creating and using encodings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Encoding
\fBTcl_GetEncoding\fR(\fIinterp, name\fR)
.sp

char *
\fBTcl_UtfToExternalDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
.sp
int
\fBTcl_UtfToExternalDStringEx\fR(\fIinterp, encoding, src, srcLen, flags, dstPtr, errorIdxPtr\fR)
.sp
int
\fBTcl_ExternalToUtfEx\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
.sp
int
\fBTcl_ExternalToUtf\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadIntPtr, dstWroteIntPtr, dstCharsIntPtr\fR)
.sp
int
\fBTcl_UtfToExternalEx\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadPtr, dstWrotePtr, dstCharsPtr\fR)
.sp
int
\fBTcl_UtfToExternal\fR(\fIinterp, encoding, src, srcLen, flags, statePtr, dst, dstLen, srcReadIntPtr, dstWroteIntPtr, dstCharsIntPtr\fR)
.sp
const char *
\fBTcl_GetEncodingName\fR(\fIencoding\fR)
.sp
Tcl_Size
\fBTcl_GetEncodingNulLength\fR(\fIencoding\fR)
.sp
int
\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
.sp
const char *
\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)
.sp
const char *
\fBTcl_GetEncodingNameForUser\fR(\fIbufPtr\fR)
.sp
\fBTcl_GetEncodingNames\fR(\fIinterp\fR)
.sp
Tcl_Encoding
\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
.sp
Tcl_Obj *
\fBTcl_GetEncodingSearchPath\fR()
.sp
int
\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
.fi
.SH ARGUMENTS
.AS "const Tcl_EncodingType" *dstWroteIntPtr in/out
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL if no error reporting is
desired.
.AP "const char" *name in
Name of encoding to load.
.AP Tcl_Encoding encoding in
The encoding to query, free, or use for converting text.  If \fIencoding\fR is

Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
encoding-specific length of the string is used.
.AP Tcl_DString *dstPtr out
Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
result will be stored.
.AP int flags in
This is a bit mask passed in to control the operation of the encoding functions.














Any bits not defined in the function descriptions below should be set to 0 as they
are used internally by Tcl.
.AP Tcl_EncodingState *statePtr in/out
Used when converting a (generally long or indefinite length) byte stream
in a piece-by-piece fashion.







.AP char *dst out
Buffer in which the converted result will be stored.  No more than
\fIdstLen\fR bytes will be stored in \fIdst\fR.
.AP Tcl_Size dstLen in
The maximum length of the output buffer \fIdst\fR in bytes.
.AP Tcl_Size *srcReadPtr out
Filled with the number of bytes from \fIsrc\fR that were converted. May be NULL.
.AP int *srcReadIntPtr out
Filled with the number of bytes from \fIsrc\fR that were converted. May be NULL.
.AP Tcl_Size *dstWrotePtr out
Filled with the number of bytes that were stored in the output

buffer as a result of the conversion. May be NULL.
.AP int *dstWroteIntPtr out
Filled with the number of bytes that were stored in the output
buffer as a result of the conversion.  May be NULL.
.AP Tcl_Size *dstCharsPtr out
Filled with the number of characters that correspond to the number of bytes
stored in the output buffer. May be NULL.
.AP int *dstCharsIntPtr out
Filled with the number of characters that correspond to the number of bytes
stored in the output buffer. May be NULL.
.AP Tcl_Size *errorIdxPtr out
Filled with the index of the byte or character that caused the encoding transform
to fail. May be NULL.
.AP Tcl_DString *bufPtr out
Storage for the prescribed system encoding name.
.AP "const Tcl_EncodingType" *typePtr in
Structure that defines a new type of encoding.

staging ground for all the various encodings. In the example above, text would
be translated into TUTF-8 from whatever file encoding the operating system is
using. Then it would be translated from TUTF-8 into whatever font encoding the
display routines require.
.PP
Some basic encodings are compiled into Tcl. Others can be defined by the user or
dynamically loaded from encoding files in a platform-independent manner.
.SH "MANAGING ENCODINGS"
.PP
\fBTcl_GetEncoding\fR finds an encoding given its \fIname\fR. The name may refer
to a built-in Tcl encoding, a user-defined encoding registered by calling
\fBTcl_CreateEncoding\fR, or a dynamically-loadable encoding file. The return
value is a token that represents the encoding and can be used in subsequent

calls to functions that expect an argument of type \fBTcl_Encoding\fR. If the
name did not refer to any known or loadable encoding, NULL is returned and an
error message is stored in \fIinterp\fR.
.PP
The encoding package maintains a database of all encodings currently in use.
The first time \fIname\fR is seen, \fBTcl_GetEncoding\fR returns an
encoding with a reference count of 1.  If the same \fIname\fR is requested
further times, then the reference count for that encoding is incremented
without the overhead of allocating a new encoding and all its associated
data structures.

\fBTcl_Encoding\fR token is written to the storage pointed to by
\fIencodingPtr\fR, and the value \fBTCL_OK\fR is returned. If no such
encoding is found, the value \fBTCL_ERROR\fR is returned, and no
writing to \fB*\fR\fIencodingPtr\fR takes place. Just as with
\fBTcl_GetEncoding\fR, the caller should call \fBTcl_FreeEncoding\fR
on the resulting encoding token when that token will no longer be
used.






















































































.PP
\fBTcl_GetEncodingName\fR is roughly the inverse of \fBTcl_GetEncoding\fR.
Given an \fIencoding\fR, the return value is the \fIname\fR argument that
was used to create the encoding.  The string returned by
\fBTcl_GetEncodingName\fR is only guaranteed to persist until the
\fIencoding\fR is deleted.  The caller must not modify this string.
.PP
\fBTcl_GetEncodingNulLength\fR returns the length of the terminating
nul byte sequence for strings in the specified encoding.
.PP
\fBTcl_SetSystemEncoding\fR sets the default encoding that should be used
whenever the user passes a NULL value for the \fIencoding\fR argument to
any of the other encoding functions.  If \fIname\fR is NULL, the system
encoding is reset to the default system encoding, \fBbinary\fR.  If the
name did not refer to any known or loadable encoding, \fBTCL_ERROR\fR is
returned and an error message is left in \fIinterp\fR.  Otherwise, this
procedure increments the reference count of the new system encoding,
decrements the reference count of the old system encoding, and returns
\fBTCL_OK\fR.
.PP
\fBTcl_GetEncodingNameFromEnvironment\fR retrieves the encoding name to

use as the system encoding. On non-Windows platforms, this is derived
from the \fBnl_langinfo\fR system call if available, and environment
variables \fBLC_ALL\fR, \fBLC_CTYPE\fR or \fBLANG\fR otherwise. On
Windows versions Windows 10 Build 18362 and later the returned value is
always \fButf-8\fR. On earlier Windows versions, it is derived from the
user settings in the Windows registry. \fBTcl_GetEncodingNameForUser\fR
retrieves the encoding name based on the user settings for the current
user and is derived in the same manner as
\fBTcl_GetEncodingNameFromEnvironment\fR on non-Windows platforms. On
Windows, unlike \fBTcl_GetEncodingNameFromEnvironment\fR, it returns the
encoding name as per the Windows registry settings irrespective of the
Windows version. Both functions accept \fIbufPtr\fR, a pointer to an
uninitialized or freed \fBTcl_DString\fR and write the encoding name to
it. They return \fBTcl_DStringValue(bufPtr)\fR which points to the stored
name.
.PP
\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
consisting of the names of all the encodings that are currently defined
or can be dynamically loaded, searching the encoding path specified by
\fBTcl_SetEncodingSearchPath\fR.  This procedure does not ensure that the
dynamically-loadable encoding files contain valid data, but merely that they
exist.
.SH "CONVERTING BETWEEN TUTF-8 AND OTHER ENCODINGS"
.PP
There are two sets of functions to convert data between TUTF-8 and any external
encoding known to Tcl. They differ primarily in the form in which converted data
is returned to the caller. The \fBTcl_ExternalToUtfEx\fR and
\fBTcl_UtfToExternalEx\fR functions return the data in buffers supplied by the
caller. The \fBTcl_ExternalToUtfDStringEx\fR and
\fBTcl_UtfToExternalDStringEx\fR return the data in a \fBTcl_DString\fR
structure. For backwards compatibility, Tcl also provides "non-Ex" variants
of these such as \fBTcl_ExternalToUtf\fR.
.SS "CONVERSION USING OUTPUT BUFFERS"
.PP
The \fBTcl_ExternalToUtfEx\fR function converts bytes in the encoding
\fIencoding\fR at address \fIsrc\fR into TUTF-8 encoding, storing them in the
buffer at address \fIdst\fR. Conversely, \fBTcl_UtfToExternalEx\fR converts
bytes encoded in TUTF-8 at address \fIsrc\fR into the encoding given by
\fIencoding\fR, storing them in the output buffer at address \fIdst\fR. In both
cases, \fIsrcLen\fR specifies the number of bytes to be converted and
\fIdstLen\fR specifies the size of the output buffer.
.PP
The \fIflags\fR parameter is a bitmask that controls operation of the conversion
and should be a bitwise OR of zero or more of the following values:
.RS
.IP \fBTCL_ENCODING_PROFILE_xxx\fR 29
At most one of the profile selection flags listed in the \fBPROFILES\fR section of
this manpage.
.IP \fBTCL_ENCODING_NO_TERMINATE\fR 29
Disables null termination of the output. By default, the output buffer \fIdst\fR
is terminated with an encoding-appropriate null.
.IP \fBTCL_ENCODING_START\fR and \fBTCL_ENCODING_END\fR 29
Indicate whether the source bytes correspond to the first or last blocks,
respectively, in a source stream. \fBTCL_ENCODING_START\fR will cause the
conversion routine to reset to an initial state ready to process the first byte
of an encoded stream. \fBTCL_ENCODING_END\fR indicates the source buffer is the
last block in an input stream allowing any required finalization to be
performed. Any incomplete trailing characters will then be treated as per the
encoding profile in effect. Both flags may be specified in the same call when
all data to be converted is passed in a single block. Both flags are also
presumed to be implicitly set if the \fIstatePtr\fR parameter is passed as NULL.
.IP \fBTCL_ENCODING_CHAR_LIMIT\fR 29
Specifies that the functions should not convert more characters than the number
passed through the \fIdstCharsPtr\fR argument, if not NULL. This flag is only
supported by the \fBTcl_ExternalToUtfEx\fR function and should not be passed to
other functions.
.RE
.LP
The \fIstatePtr\fR parameter is an opaque pointer to a location used by the
encoding functions to store intermediate state when the data to be converted is
passed in multiple chunks. The same location should be passed in \fIstatePtr\fR
for all related calls with the first chunk passed with the
\fBTCL_ENCODING_START\fR flag set and the last with \fBTCL_ENCODING_END\fR set.
If \fIstatePtr\fR is passed as NULL, all data is presumed to all be contained in
that single call and the functions behave as if \fBTCL_ENCODING_START\fR and
\fBTCL_ENCODING_END\fR were both set in the \fIflags\fR parameter.
.PP
The \fIsrcReadPtr\fR, \fIdstWrotePtr\fR and \fIdstCharsPtr\fR point to locations
to hold the number of bytes in the source that were processed successfully, the
number of bytes written to the output buffer (excluding terminating nulls), and
the number of characters written to the output buffer (again excluding
terminating nulls) respectively. All three are optional and may be passed as
NULL. Further, in the case of the \fBTcl_ExternalToUtfEx\fR function, the
\fIdstCharsPtr\fR may be used with the \fBTCL_ENCODING_CHAR_LIMIT\fR flags to
limit the number of characters processed as described earlier.
.PP
With the exceptions noted below, the counts returned in \fIsrcReadPtr\fR,
\fIdstWrotePtr\fR and \fIdstCharsPtr\fR are valid for all return codes listed
below other than \fBTCL_ERROR\fR.
.RS
.IP \fBTCL_OK\fR 29
The function completed without any exceptional conditions. Note this does not
mean all passed input in \fIsrc\fR was processed or verified. In particular, in
the case of the caller passing \fBTCL_ENCODING_CHAR_LIMIT\fR to limit the number
of characters converted, only the corresponding number of bytes in the source
input would have been processed as indicated by the value in \fIsrcReadPtr\fR.
.IP \fBTCL_CONVERT_NOSPACE\fR 29
The output buffer had insufficient space. The output buffer will contain as much
converted data as it could fit and will be null terminated as appropriate unless
the buffer was too small to even contain a null terminator by itself.
\fIsrcReadPtr\fR will hold number of processed source bytes and caller should
call again to process the remaining bytes. *Note: As a quirk of implementation,
in some cases the destination buffer needs to be \fBTCL_UTF_MAX\fR bytes greater
than the actual size needed. This is an existing quirk present in both 8.6 and
9.0 that is not addressed in this TIP.*
.IP \fBTCL_CONVERT_MULTIBYTE\fR 29
The trailing bytes in the source input formed an incomplete encoding sequence.
Caller should call the function again with additional source bytes appended to
the tail at offset \fI*srcReadPtr\fR of the original source bytes and with the
same \fIstatePtr\fR. Note that if \fIflags\fR had the \fBTCL_ENCODING_END\fR
flag set, indicating no more data is forthcoming, the functions will return
\fBTCL_CONVERT_SYNTAX\fR instead of \fBTCL_CONVERT_MULTIBYTE\fR.
.IP \fBTCL_CONVERT_SYNTAX\fR 29
An invalid byte sequence was detected in the source input. What constitutes an
"invalid" sequence is subject to the encoding profile as specified by the
\fIflags\fR parameter. The \fI*srcReadPtr\fR count will contain the number of
bytes successfully processed and is therefore also the offset of the start of
the invalid sequence. The output buffer will contain the converted data up to
that point.
.IP \fBTCL_CONVERT_UNKNOWN\fR 29
The input byte sequence represented a character that cannot be encoded in the
output encoding for the encoding profile in effect. Treatment is similar to that
of \fBTCL_CONVERT_SYNTAX\fR.
.IP \fBTCL_ERROR\fR 29
An error message is stored in \fIinterp\fR if it is not NULL. The output
locations at \fIsrcReadPtr\fR, \fIdstWrotePtr\fR and \fIdstCharsPtr\fR may have
been modified but should not be considered valid.
.RE
.LP
The functions \fBTcl_ExternalToUtf\fR and \fBTcl_UtfToExternal\fR are variants
of \fBTcl_ExternalToUtfEx\fR and \fBTcl_UtfToExternalEx\fR. They differ in that
their output counts have a limit of INT_MAX and therefore cannot handle the full
string lengths supported by Tcl on 64-bit platforms. They will return
\fBTCL_ERROR\fR in such cases.
.SS "CONVERSION USING TCL_DSTRING"
.PP
\fBTcl_ExternalToUtfDStringEx\fR and \fBTcl_UtfToExternalDStringEx\fR convert
\fIsrcLen\fR bytes at address \fIsrc\fR from the specified \fIencoding\fR into
TUTF-8 and the reverse respectively. The converted bytes are stored in
\fIdstPtr\fR, which is then null-terminated. The caller should eventually call
\fBTcl_DStringFree\fR to free any information stored in \fIdstPtr\fR irrespective
of the return value from the function.
.PP
The \fIflags\fR argument to the functions should be 0 or one of the profile
selection flags described above to select the profile to use for conversion.
The other flags should be cleared. The functions assume the entire source
string to be converted is passed into the function.
.PP
On success, the function returns \fBTCL_OK\fR with the
converted string stored in \fB*dstPtr\fR. For errors \fIother than conversion
errors\fR, such as invalid flags, the function returns \fBTCL_ERROR\fR with an
error message in \fBinterp\fR if it is not NULL.
For conversion errors, \fBTcl_ExternalToUtfDStringEx\fR returns one
of the \fBTCL_CONVERT_*\fR errors listed above.
When one of these conversion errors is returned, an error message is stored
in \fBinterp\fR only if \fBerrorIdxPtr\fR is NULL. Otherwise, no error message
is stored as the function expects the caller is only interested the decoded data
up to that point and not treating this as an immediate error condition.
The index of the error location is stored in \fB*errorIdxPtr\fR.
.PP
\fBTcl_ExternalToUtfDString\fR and \fBTcl_UtfToExternalDString\fR are older,
less flexible variants of the above functions that do not support profiles. The
return value from the functions is a pointer to the value stored in the
\fBTcl_DString\fR. When converting, if any of the characters in the source
buffer cannot be represented in the target encoding, a default fallback
character will be used. The return value is a pointer to the value stored in the
DString. \fBTcl_UtfToExternalDString\fR converts a source buffer \fIsrc\fR from
TUTF-8 into the specified \fIencoding\fR. The converted bytes are stored in
\fIdstPtr\fR, which is then terminated with the appropriate encoding-specific
null. The caller should eventually call \fBTcl_DStringFree\fR to free any
information stored in \fIdstPtr\fR. When converting, if any of the characters in
the source buffer cannot be represented in the target encoding, an
encoding-specific default fallback character will be used.
.SH CREATING NEW ENCODINGS
.PP
\fBTcl_CreateEncoding\fR defines a new encoding and registers the C
procedures that are called back to convert between the encoding and
TUTF-8.  Encodings created by \fBTcl_CreateEncoding\fR are thereafter
visible in the database used by \fBTcl_GetEncoding\fR.  Just as with the
\fBTcl_GetEncoding\fR procedure, the return value is a token that
represents the encoding and can be used in subsequent calls to other

        void *\fIclientData\fR,
        const char *\fIsrc\fR,
        int \fIsrcLen\fR,
        int \fIflags\fR,
        Tcl_EncodingState *\fIstatePtr\fR,
        char *\fIdst\fR,
        int \fIdstLen\fR,
        int *\fIsrcReadIntPtr\fR,
        int *\fIdstWroteIntPtr\fR,
        int *\fIdstCharsIntPtr\fR);
.CE
.PP
The \fItoUtfProc\fR and \fIfromUtfProc\fR procedures are called by the
\fBTcl_ExternalToUtf\fR or \fBTcl_UtfToExternal\fR family of functions to
perform the actual conversion.  The \fIclientData\fR parameter to these
procedures is the same as the \fIclientData\fR field specified to
\fBTcl_CreateEncoding\fR when the encoding was created.  The remaining
arguments to the callback procedures are the same as the arguments,
documented at the top, to \fBTcl_ExternalToUtf\fR or
\fBTcl_UtfToExternal\fR, with the following exceptions.  If the
\fIsrcLen\fR argument to one of those high-level functions is negative,
the value passed to the callback procedure will be the appropriate
encoding-specific string length of \fIsrc\fR.  The \fIsrcReadIntPtr\fR,
\fIdstWroteIntPtr\fR, and \fIdstCharsIntPtr\fR arguments will always be non-NULL,
even if the corresponding argument to one of the high-level
functions is NULL.

.PP
The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
\fBTcl_EncodingFreeProc\fR:
.PP
.CS
typedef void \fBTcl_EncodingFreeProc\fR(
        void *\fIclientData\fR);

If your extensions is compiled with \fB-DTCL_8_API\fR, this function will return
NULL for paths having more than INT_MAX elements (which should
trigger proper error-handling), otherwise expect it to crash.
.AP Tcl_Obj *basePtr in
The base path on to which to join the given elements. May be NULL.
.AP Tcl_Size objc in
The number of elements in \fIobjv\fR.
.AP "Tcl_Obj *const" *objv in
The elements to join to the given base path.
.AP Tcl_Obj *linkNamePtr in
The name of the link to be created or read.
.AP Tcl_Obj *toPtr in
What the link called \fIlinkNamePtr\fR should be linked to, or NULL if
the symbolic link specified by \fIlinkNamePtr\fR is to be read.
.AP int linkAction in

.PP
The resulting value is a pure
.QW path
value, which will only receive
a UTF-8 string representation if that is required by some Tcl code.
.PP
\fBTcl_FSGetNativePath\fR is for use by the Win/Unix native
filesystems, so that they can easily retrieve the native (char * or
TCHAR *) representation of a path. This function is a convenience
wrapper around \fBTcl_FSGetInternalRep\fR. It may be desirable in the
future to have non-string-based native representations (for example,
on macOS, a representation using a fileSpec of FSRef structure would
probably be more efficient). On Windows a full Unicode representation
would allow for paths of unlimited length. Currently the representation
is simply a character string which may contain either the relative path
or a complete, absolute normalized path in the native encoding (complex

'\"
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_FindExecutable 3 9.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_FindExecutable, Tcl_GetNameOfExecutable \- identify or return the name of the binary file containing the application
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
const char *
\fBTcl_FindExecutable\fR(\fIargv0\fR)
.sp
const char *
\fBTcl_GetNameOfExecutable\fR()
.fi
.SH ARGUMENTS
.AS char *argv0
.AP char *argv0 in
The first command-line argument to the program, which gives the
application's name.
.BE

.SH DESCRIPTION
.PP
\fBTcl_FindExecutable\fR is one of two functions, \fBTclZipfs_AppHook\fR
being the other, that must be called by an application to initialize
Tcl prior to any other calls into Tcl. Applications that wish to use
ZipFS-based builds should call \fBTclZipfs_AppHook\fR in preference


to this function.

.PP





On UNIX platforms, the function should be passed \fIargv[0]\fR as its
argument. It is important not to change the working directory before
this invocation. \fBTcl_FindExecutable\fR uses \fIargv0\fR together
with the \fBPATH\fR environment variable to locate the application's
executable, if possible. If it fails to find the binary, subsequent

calls to \fBinfo nameofexecutable\fR will return an empty string.
.PP
On Windows platforms, the \fIargv[0]\fR argument is used only to

indicate whether the executable has a standard error channel (any
non-null value) or not (the value null). If \fBTcl_SetPanicProc\fR is
never called and no debugger is running, this setting determines
whether a panic message is sent to standard error or displayed in a
system dialog.
.PP
As part of its initialization sequence,
\fBTcl_FindExecutable\fR computes the full path name of the executable
file from which the application was invoked. This result is saved for
Tcl's internal use and is returned by the
\fBinfo nameofexecutable\fR command.
.PP
The result of \fBTcl_FindExecutable\fR is the full Tcl version string,
including build information (for example,
\fB9.0.0+abcdef...abcdef.gcc-1002\fR).
.PP
\fBTcl_GetNameOfExecutable\fR simply returns a pointer to the
internal full path name of the executable file as computed by
\fBTcl_FindExecutable\fR.  This procedure call is the C API
equivalent to the \fBinfo nameofexecutable\fR command.  NULL
is returned if the internal full path name has not been
computed or unknown.
.PP
\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions.
.SH KEYWORDS
binary, executable file

.QW \fB0o\fR
then \fIsrc\fR is expected to be in octal form;  otherwise,
if the first such characters are
.QW \fB0b\fR
then \fIsrc\fR
is expected to be in binary form;  otherwise, \fIsrc\fR is
expected to be in decimal form.
.VS "TIP 551"
One or more underscore characters,
.QW _ ,
may be inserted between digits, acting as numeric whitespace, but not
before the first digit or after the last digit, or between the prefix
(as described above, if present) and the first digit.
Which is to say,
.QW "1_000_000"
is a \fIvalid\fR way of writing one million, but
.QW "0d_1000_000"
is \fInot valid\fR, and will be reported as an error.
.VE "TIP 551"
.PP
\fBTcl_GetDouble\fR expects \fIsrc\fR to consist of a floating-point
number, which is:  white space;  a sign; a sequence of digits;  a
decimal point
.QW \fB.\fR ;
a sequence of digits;  the letter
.QW \fBe\fR ;

'\"
'\" Copyright (c) 2001 Kevin B. Kenny <kennykb@acm.org>.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_GetTime 3 8.4 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_GetMonotonicTime, Tcl_GetTime, Tcl_SetTimeProc, Tcl_QueryTimeProc \- get date and time
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
long long
\fBTcl_GetMonotonicTime\fR()
.sp
\fBTcl_GetTime\fR(\fItimePtr\fR)
.sp
\fBTcl_SetTimeProc\fR(\fIgetProc, scaleProc, clientData\fR)
.sp
\fBTcl_QueryTimeProc\fR(\fIgetProcPtr, scaleProcPtr, clientDataPtr\fR)
.fi
.SH ARGUMENTS

.AP Tcl_ScaleTimeProc *scaleProcPtr out
Pointer to place the currently registered scale handler function into.
.AP void **clientDataPtr out
Pointer to place the currently registered pass-through value into.
.BE
.SH DESCRIPTION
.PP
The \fBTcl_GetMonotonicTime\fR function returns the current monotonic time.
The unit is micro-seconds.
Only time differences are defined.
The timer value 0 may be the epoc but may also be the start-up of the system.
.PP
The value is contiguous but may jump due to timer virtualization or sleep mode.
.PP
The precision is system dependent and not guaranteed to be micro-second precise.
.PP
The \fBTcl_GetTime\fR function retrieves the current time as a
\fITcl_Time\fR structure in memory the caller provides.  This
structure has the following definition:
.PP
.CS
typedef struct {
    long long \fIsec\fR;
    long \fIusec\fR;
} \fBTcl_Time\fR;
.CE
.PP
On return, the \fIsec\fR member of the structure is filled in with the
number of seconds that have elapsed since the \fIepoch:\fR the epoch
is the point in time of 00:00 UTC, 1 January 1970.  This number does
\fInot\fR count leap seconds; an interval of one day advances it by
86400 seconds regardless of whether a leap second has been inserted.
.PP
The \fIusec\fR member of the structure is filled in with the number of
microseconds that have elapsed since the start of the second
designated by \fIsec\fR.
.PP

This command uses the system wall clock and is not contiguous by definition.
It may have large jumps in short time, specially if the system is awaked from
sleep mode.

.SS "VIRTUALIZED TIME"
.PP
The \fBTcl_SetTimeProc\fR and \fBTcl_QueryTimeProc\fR are not supported since TCL 9.1.















They call a \fBTcl_Panic\fR.





















.SH "SEE ALSO"
clock(n), timer(n)
.SH KEYWORDS
date, time

'\"
'\" Copyright (c) 1989-1993 The Regents of the University of California.
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_InitHashTable, Tcl_InitCustomHashTable, Tcl_InitObjHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_AttemptCreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_InitHashTable\fR(\fItablePtr, keyType\fR)
.sp
\fBTcl_InitCustomHashTable\fR(\fItablePtr, keyType, typePtr\fR)
.sp
\fBTcl_InitObjHashTable\fR(\fItablePtr\fR)
.sp
\fBTcl_DeleteHashTable\fR(\fItablePtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_AttemptCreateHashEntry\fR(\fItablePtr, key, newPtr\fR)
.sp
\fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR)
.sp
Tcl_HashEntry *
\fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
.sp
void *
\fBTcl_GetHashValue\fR(\fIentryPtr\fR)

\fBTcl_CreateHashEntry\fR locates the entry corresponding to a
particular key, creating a new entry in the table if there
was not already one with the given key.
If an entry already existed with the given key then \fI*newPtr\fR
is set to zero.
If a new entry was created, then \fI*newPtr\fR is set to a non-zero
value and the value of the new entry will be set to zero.
\fI*newPtr\fR is allowed to be NULL.
The return value from \fBTcl_CreateHashEntry\fR is a pointer to
the entry, which may be used to retrieve and modify the entry's
value or to delete the entry from the table.
.PP
\fBTcl_AttemptCreateHashEntry\fR does the same as
\fBTcl_CreateHashEntry\fR, except in case of a memory
overflow. \fBTcl_AttemptCreateHashEntry\fR returns NULL
in that case while \fBTcl_CreateHashEntry\fR panics.
.PP
\fBTcl_DeleteHashEntry\fR will remove an existing entry from a
table.
The memory associated with the entry itself will be freed, but
the client is responsible for any cleanup associated with the
entry's value, such as freeing a structure that it points to.
.PP
\fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR

custom set of allocation routines might depend on, in order to avoid any
circular dependency.
.PP
The \fIhashKeyProc\fR member contains the address of a function called to
calculate a hash value for the key.
.PP
.CS
typedef size_t \fBTcl_HashKeyProc\fR(
        Tcl_HashTable *\fItablePtr\fR,
        void *\fIkeyPtr\fR);
.CE
.PP
If this is NULL then \fIkeyPtr\fR is used and
\fBTCL_HASH_KEY_RANDOMIZE_HASH\fR is assumed.
.PP

.CE
.PP
If this is NULL then \fBTcl_Alloc\fR is used to allocate enough space for a
Tcl_HashEntry, the key pointer is assigned to key.oneWordValue and the
clientData is set to NULL. String keys and array keys use this function to
allocate enough space for the entry and the key in one block, rather than
doing it in two blocks. This saves space for a pointer to the key from the
entry and another memory allocation. Tcl_Obj * keys use this function to
allocate enough space for an entry and increment the reference count on the
value.
.PP
The \fIfreeEntryProc\fR member contains the address of a function called to
free space for an entry.
.PP
.CS
typedef void \fBTcl_FreeHashEntryProc\fR(
        Tcl_HashEntry *\fIhPtr\fR);
.CE
.PP
If this is NULL then \fBTcl_Free\fR is used to free the space for the entry.
Tcl_Obj * keys use this function to decrement the reference count on the
value.
.SH "REFERENCE COUNT MANAGEMENT"
.PP
When a hash table is created with \fBTcl_InitCustomHashTable\fR, the
\fBTcl_CreateHashEntry\fR function will increment the reference count of its
\fIkey\fR argument when it creates a key (but not if there is an existing
matching key). The reference count of the key will be decremented when the
corresponding hash entry is deleted, whether with \fBTcl_DeleteHashEntry\fR or
with \fBTcl_DeleteHashTable\fR. The \fBTcl_GetHashKey\fR function will return
the key without further modifying its reference count.
.PP
Custom hash tables that use a Tcl_Obj * as key will generally need to do
something similar in their \fIallocEntryProc\fR.
.SH "SEE ALSO"
Dict(3)
.SH KEYWORDS
hash table, key, lookup, search, value

\fB#include <tcl.h>\fR
.sp
int
\fBTcl_Init\fR(\fIinterp\fR)
.sp
const char *
\fBTcl_SetPreInitScript\fR(\fIscriptPtr\fR)
.sp
.VS TIP755
typedef int \fBTcl_PostInitProc\fR(\fBTcl_Interp *\fIinterp\fR, \fBvoid *\fIclientData\fR)
.sp
int
\fBTcl_RegisterPostInitProc\fR(\fIpostInitProc\fR, \fIclientData\fR)
.sp
int
\fBTcl_UnregisterPostInitProc\fR(\fIpostInitProc\fR, \fIclientData\fR)
.sp
int
\fBTcl_ClearPostInitProcs\fR(void)
.VE TIP755
.fi
.SH ARGUMENTS
.AS Tcl_Interp *interp
.AP Tcl_Interp *interp in
Interpreter to initialize.
.AP "const char" *scriptPtr in
Address of the initialization script.
.AP Tcl_PostInitProc *postInitProc in
Function to call post initialization of interpreter.
.AP "void" *clientData in
Arbitrary one-word value to pass to \fBpostInitProc\fR.
.BE

.SH DESCRIPTION
.PP
\fBTcl_Init\fR is a helper procedure that finds and \fBsource\fRs the
\fBinit.tcl\fR script, which should exist somewhere on the Tcl library
path.
.PP
\fBTcl_Init\fR is typically called from \fBTcl_AppInit\fR procedures.
.PP
\fBTcl_SetPreInitScript\fR registers the pre-initialization script and
returns the former (now replaced) script pointer.
A value of \fINULL\fR may be passed to not register any script.
The pre-initialization script is executed by \fBTcl_Init\fR before accessing
the file system. The purpose is to typically prepare a custom file system
(like an embedded zip-file) to be activated before the search.
.VS TIP755
.PP
\fBTcl_RegisterPostInitProc\fR registers a callback that should be invoked by
\fBTcl_Init\fR at the end of initialization of subsequently created
interpreters except safe interpreters. The function returns a Tcl return code.
.PP
This callback function is passed the interpreter being initialized and the
opaque \fIclientData\fR value that was passed at the time of registration. It
should return a Tcl return code. Multiple callbacks are supported and will be
invoked in the order of their registration except that an error return from a
callback will skip the remaining registrations. The Tcl return code from the
last callback invoked is returned as the return value from \fBTcl_Init\fR.
.PP
\fBTcl_UnregisterPostInitProc\fR unregisters a previously registered callback.
Both \fIpostInitProc\fR and \fIclientData\fR must match the the corresponding
values that were passed to \fBTcl_RegisterPostInitProc\fR. The function returns
a standard Tcl return code. It is not an error if there is no matching prior
registration.
.PP
The \fBTcl_ClearPostInitProcs\fR function unregisters all currently registered
callbacks.
.PP
Callback functions registered through \fBTcl_RegisterPostInitProc\fR may load
static packages, add commands, or set up other facilities so they are available
in all interpreters. They cannot however execute any code that may result in new
interpreters and should not delete the passed interpreter.
.PP
The `Tcl_RegisterPostInitProc` and `Tcl_UnregisterPostInitProc` functions may be
invoked from within a registered callback. However, the change in registration
will not have effect for the interpreter that is being initialized.
.VE TIP755
.PP
When used in stub-enabled embedders, the stubs table must be first initialized
using one of \fBTcl_InitSubsystems\fR, \fBTcl_SetPanicProc\fR,
\fBTcl_FindExecutable\fR
or \fBTclZipfs_AppHook\fR before \fBTcl_SetPreInitScript\fR may be called.
.SH "SEE ALSO"
Tcl_AppInit, Tcl_Main
.SH KEYWORDS
application, initialization, interpreter

.nf
\fB#include <tcl.h>\fR
.sp
const char *
\fBTcl_InitSubsystems\fR()
.fi
.BE

.SH DESCRIPTION
.PP
The \fBTcl_InitSubsystems\fR procedure initializes various Tcl subsystems. It
should be called by any additional Tcl threads created after the main thread in

a Tcl application that wish to use Tcl facilities without creating an
interpreter. Threads that create interpreters using \fBTcl_CreateInterp\fR do
not need to call this function, provided that \fBTcl_CreateInterp\fR is the
first call into Tcl from that thread.
.PP
Note that the main thread must have first called either \fBTclZipfs_AppHook\fR
or \fBTcl_FindExecutable\fR to perform application-wide Tcl initialization
before additional threads using Tcl are created. \fBTcl_InitSubsystems\fR does
not suffice for this purpose and should only be used to initialize Tcl in
secondary threads. It need not be called in the main thread invoking one of the
two aforementioned functions.

.PP
The result of \fBTcl_InitSubsystems\fR is the full Tcl version string,
including build information (for example,
\fB9.0.0+abcdef...abcdef.gcc-1002\fR).





.SH KEYWORDS
binary, executable file

'\"
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_ListObj 3 9.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_ListObjRange, Tcl_ListObjRepeat, Tcl_ListObjReverse \- manipulate Tcl values as lists
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR)
.sp

\fBTcl_ListObjLength\fR(\fIinterp, listPtr, lengthPtr\fR)
.sp
int
\fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR)
.sp
int
\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
.sp
int
\fBTcl_ListObjRange\fR(\fIinterp, listPtr, first, last, objPtrPtr\fR)
.sp
int
\fBTcl_ListObjRepeat\fR(\fIinterp, count, objc, objv, objPtrPtr\fR)
.sp
int
\fBTcl_ListObjReverse\fR(\fIinterp, listPtr, objPtrPtr\fR)
.fi
.SH ARGUMENTS
.AS "Tcl_Obj *const" *elemListPtr in/out
.AP Tcl_Interp *interp in
If an error occurs while converting a value to be a list value,
an error message is left in the interpreter's result value
unless \fIinterp\fR is NULL.
.AP Tcl_Obj *listPtr in/out
Points to the input list value.
If \fIlistPtr\fR does not already point to a list value,
an attempt will be made to convert it to one.
Some functions may store a reference to it internally so
care must be taken when managing its reference count.
See the \fBREFERENCE COUNT MANAGEMENT\fR section below.
.AP Tcl_Obj *elemListPtr in/out
For \fBTcl_ListObjAppendList\fR, this points to a list value
containing elements to be appended onto \fIlistPtr\fR.
Each element of *\fIelemListPtr\fR will
become a new element of \fIlistPtr\fR.
If *\fIelemListPtr\fR is not NULL and
does not already point to a list value,

If your extensions is compiled with \fB\-DTCL_8_API\fR, this function will return
NULL for lists with more than INT_MAX elements (which should
trigger proper error-handling), otherwise expect it to crash.
.AP Tcl_Obj ***objvPtr out
A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
of pointers to the element values of \fIlistPtr\fR.
.AP Tcl_Size objc in
The number of Tcl values in the \fIobjv\fR array.




.AP "Tcl_Obj *const" *objv in
An array of pointers to Tcl values.



.AP "Tcl_Size \&| int" *lengthPtr out
Points to location where \fBTcl_ListObjLength\fR
stores the length of the list.
May be (Tcl_Size *)NULL when not used. If it points to a variable which
type is not \fBTcl_Size\fR, a compiler warning will be generated.
If your extensions is compiled with \fB-DTCL_8_API\fR, this function will return
TCL_ERROR for lists with more than INT_MAX elements (which should
trigger proper error-handling), otherwise expect it to crash.
.AP Tcl_Size index in
Index of the list element that \fBTcl_ListObjIndex\fR
is to return.
The first element has index 0.
.AP Tcl_Obj **objPtrPtr out
Points to location to store an output list or element value. No assumptions
should be made about the reference count of the returned value.
See the \fBREFERENCE COUNT MANAGEMENT\fR section below.
.AP Tcl_Size first in
Index of the first element in a range of elements in a list.
.AP Tcl_Size last in
Index of the last element in a range of elements in a list.
.AP Tcl_Size count in
The number of elements to be operated on or a repetition count.

.BE

.SH DESCRIPTION
.PP
Tcl list values have an internal representation that supports
the efficient indexing and appending.
The procedures described in this man page are used to
create, modify, access, and transform Tcl list values from C code.
.PP
\fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
both add one or more values
to the end of the list value referenced by \fIlistPtr\fR.
\fBTcl_ListObjAppendList\fR appends each element of the list value
referenced by \fIelemListPtr\fR while
\fBTcl_ListObjAppendElement\fR appends the single value

of 0. Abstract Lists create a new element Obj on demand, and do not
retain any element Obj values. Therefore, the caller is responsible for
freeing the element when it is no longer needed. Note that this is a
change from Tcl 8 where all list elements always have a reference
count of at least 1. (See \fBABSTRACT LIST TYPES\fR, \fBSTORAGE
MANAGEMENT OF VALUES\fR, Tcl_BounceRefCount(3), and lseq(n) for more
information.)

.PP
\fBTcl_ListObjReplace\fR replaces zero or more elements
of the list referenced by \fIlistPtr\fR
with the \fIobjc\fR values in the array referenced by \fIobjv\fR.
If \fIlistPtr\fR does not point to a list value,
\fBTcl_ListObjReplace\fR will attempt to convert it to one;
if the conversion fails, it returns \fBTCL_ERROR\fR

by simply calling \fBTcl_ListObjReplace\fR
with a NULL \fIobjvPtr\fR:
.PP
.CS
result = \fBTcl_ListObjReplace\fR(interp, listPtr, first, count,
        0, NULL);
.CE
.PP
\fBTcl_ListObjRange\fR stores in \fIobjPtrPtr\fR a pointer to a list value
containing all elements in the passed input list \fIlistPtr\fR at indices
between \fIfirst\fR and \fIlast\fR, both inclusive. An empty
list is returned in the case of \fIfirst\fR being greater than \fIlast\fR.
.PP
\fBTcl_ListObjRepeat\fR stores in \fIobjPtrPtr\fR a pointer to a list value
whose elements are the \fIobjc\fR elements passed in \fIobjv\fR, repeated
\fIcount\fR number of times. An error is raised if \fIcount\fR is negative.
.PP
\fBTcl_ListObjReverse\fR stores in \fIobjPtrPtr\fR a pointer to a list value
containing all elements of the input list \fIlistPtr\fR in reverse order.
.PP
For all three functions, \fBTcl_ListObjRange\fR, \fBTcl_ListObjRepeat\fR and
\fBTcl_ListObjReverse\fR, the value passed in \fIlistPtr\fR need not be unshared.
The pointer stored at \fIobjPtrPtr\fR is guaranteed to be different from
\fIlistPtr\fR but no assumptions should be made about its reference count.
In case of errors, the location addressed by \fIobjPtrPtr\fR may have been
modified and should be treated by the caller as undefined.
.SH "REFERENCE COUNT MANAGEMENT"
.PP
Care must be taken by callers when managing the reference count
of values passed in as well as values returned from the above functions.
.PP
Unless specified otherwise below, the above functions may internally
keep a reference to the value passed in \fIlistPtr\fR and increment its
reference count. Therefore, if \fIlistPtr\fR is newly allocated and has
a zero reference count, it should not be freed after the call with
\fBTcl_DecrRefCount\fR. Rather, use \fBTcl_BounceRefCount\fR instead.
Furthermore, if \fIlistPtr\fR was retrieved from the interpreter result
(e.g. via \fBTcl_GetObjResult\fR) and that is the only reference to the
value, it may be deleted if a function sets the interpreter result on
error. The more general and safe method for passing values is to
increment their reference counts with \fBTcl_IncrRefCount\fR prior to
the call and release them with \fBTcl_DecrRefCount\fR when the call
returns. However, this may preclude certain optimizations based on
modifying unshared values in-place.
.PP
\fBTcl_NewListObj\fR always returns a zero-reference object, much like
\fBTcl_NewObj\fR. If a non-NULL \fIobjv\fR argument is given, the reference
counts of the first \fIobjc\fR values in that array are incremented.
.PP
\fBTcl_SetListObj\fR does not modify the reference count of its \fIobjPtr\fR
argument, but does require that the object be unshared. The reference counts
of the first \fIobjc\fR values in the \fIobjv\fR array are incremented.
.PP
\fBTcl_ListObjGetElements\fR, \fBTcl_ListObjIndex\fR, and
\fBTcl_ListObjLength\fR do not modify the reference count of the
\fIlistPtr\fR argument except on error when the interpreter

result holds a reference to it as described earlier.
.PP
\fBTcl_ListObjAppendList\fR, \fBTcl_ListObjAppendElement\fR, and
\fBTcl_ListObjReplace\fR require an unshared \fIlistPtr\fR argument.
\fBTcl_ListObjAppendList\fR only reads its \fIelemListPtr\fR argument.
\fBTcl_ListObjAppendElement\fR increments the reference count of its
\fIobjPtr\fR on success. \fBTcl_ListObjReplace\fR increments the
reference count of the first \fIobjc\fR values in the \fIobjv\fR array
on success. Note that the same caveat stated earlier applies if the
interpreter result holds a reference to \fIlistPtr\fR.
.PP
The pointer to a result value returned in \fIobjPtrPtr\fR by the
functions \fBTcl_ListObjRange\fR,
\fBTcl_ListObjRepeat\fR and \fBTcl_ListObjReverse\fR is guaranteed
to be different from the \fBlistPtr\fR passed in. It is therefore
safe to manage its reference count independently from that of
\fBlistPtr\fR. No assumptions should be made about its reference
count and the standard reference counting idiom should be followed.
The caller can pass it to a function such as \fBTcl_SetObjResult\fR,
\fBTcl_ListObjAppendElement\fR etc. which take ownership of
its reference count management or dispose of the value itself
with either a \fBTcl_IncrRefCount\fR/\fBTcl_DecrRefCount\fR pair or
\fBTcl_BounceRefCount\fR.
.SH "SEE ALSO"
Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3), Tcl_GetObjResult(3)
.SH KEYWORDS
append, index, insert, internal representation, length, list, list value,
list type, value, value type, replace, string representation

stack, to evaluate a script:
.PP
.CS
int
\fITheCmdOldObjProc\fR(
    void *clientData,
    Tcl_Interp *interp,
    Tcl_Size objc,
    Tcl_Obj *const *objv)
{
    int result;
    Tcl_Obj *objPtr;

    \fI... preparation ...\fR

    result = \fBTcl_EvalObjEx\fR(interp, objPtr, 0);

    \fI... postprocessing ...\fR

    return result;
}
\fBTcl_CreateObjCommand2\fR(interp, "theCommand",
        \fITheCmdOldObjProc\fR, clientData, TheCmdDeleteProc);
.CE
.PP
To avoid consuming space on the C stack, \fITheCmdOldObjProc\fR is renamed to
\fITheCmdNRObjProc\fR and the postprocessing step is split into a separate
function, \fITheCmdPostProc\fR, which is pushed onto the function stack.
\fITcl_EvalObjEx\fR is replaced with \fITcl_NREvalObj\fR, which uses a
trampoline instead of consuming space on the C stack.  A new version of
\fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to
call \fITheCmdNRObjProc\fR:
.PP
.CS
int
\fITheCmdOldObjProc\fR(
    void *clientData,
    Tcl_Interp *interp,
    Tcl_Size objc,
    Tcl_Obj *const *objv)
{
    return \fBTcl_NRCallObjProc2\fR(interp, \fITheCmdNRObjProc\fR,
            clientData, objc, objv);
}
.CE
.PP
.CS
int
\fITheCmdNRObjProc\fR
    void *clientData,
    Tcl_Interp *interp,
    Tcl_Size objc,
    Tcl_Obj *const *objv)
{
    Tcl_Obj *objPtr;

    \fI... preparation ...\fR

    \fBTcl_NRAddCallback\fR(interp, \fITheCmdPostProc\fR,
            data0, data1, data2, data3);

in any of the numeric formats recognized by Tcl.
.AP "const char" *bytes in
Points to first byte of the string value to be examined.
.AP Tcl_Size numBytes in
The number of bytes, starting at \fIbytes\fR, that should be examined.
If \fBnumBytes\fR is negative, then all bytes should
be examined until the first \fBNUL\fR byte terminates examination.
.AP void **clientDataPtr out
Points to space where a pointer value may be written through which a numeric
value is available to read.
.AP int *typePtr out
Points to space where a value may be written reporting what type of
numeric storage is available to read.
.AP Tcl_Obj *objPtr in
A Tcl value to be examined.

.AP Tcl_Interp *interp in
Interpreter to use for error reporting.
.AP Tcl_Obj *objPtr in
For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which
it appends the name of each value type as a list element.
For \fBTcl_ConvertToType\fR, this points to a value that
must have been the result of a previous call to \fBTcl_NewObj\fR.
.AP "const char" *bytes in
String representation.
.AP "size_t" numBytes in
Length of the string representation in bytes.
.AP "const Tcl_ObjInternalRep" *irPtr in
Internal object representation.
.AP "const Tcl_ObjType" *typePtr in
Requested internal representation type.
.BE

.SH DESCRIPTION
.PP
The procedures in this man page manage Tcl value types (sometimes
referred to as object types or \fBTcl_ObjType\fRs for historical reasons).

.PP
Additional fields in the Tcl_ObjType descriptor allow for control over
how custom data values can be manipulated using Tcl's List commands
without converting the value to a List type. This requires the custom
type to provide functions that will perform the given operation on the
custom data representation.  Not all functions are required. In the
absence of a particular function (set to NULL), the fallback is to
allow the internal List operation to perform the operation, which
may possibly cause the value type to be converted to a traditional
list.
.SS "SCALAR VALUE TYPES"
.PP
For a custom value type that is scalar or atomic in nature, i.e., not
a divisible collection, version \fBTCL_OBJTYPE_V1\fR is
recommended. In this case, List commands will treat the scalar value
as if it where a list of length 1, and not convert the value to a List
type.
.SS "VERSION 2: ABSTRACT LISTS"
.PP
Version 2, \fBTCL_OBJTYPE_V2\fR, allows full List support when the
functions described below are provided.  This allows for script level
use of the List commands without causing the type of the Tcl_Obj value
to be converted to a list.

Unless specified otherwise, all functions specific to Version 2 should return
\fBTCL_OK\fR on success and \fBTCL_ERROR\fR on failure.

In the case that a \fBTcl_Obj *\fR is also returned, the reference count of the
returned \fBTcl_Obj\fR should not be incremented so, for example, if a new
\fBTcl_Obj\fR value is returned it should have a reference count of zero.

The functions should not assume that any \fBTcl_Obj\fR passed in
is unshared.

.SS "THE LENGTHPROC FIELD"
.PP
The \fBLengthProc\fR function correlates with the \fBTcl_ListObjLength\fR
C API. The function returns the number of elements in the list. It
is used in every List operation and is required for all Abstract List
implementations.
.CS
typedef Tcl_Size
(Tcl_ObjTypeLengthProc) (Tcl_Obj *listPtr);
.CE
.PP
.SS "THE INDEXPROC FIELD"
.PP
The \fBIndexProc\fR function correlates with with the
\fBTcl_ListObjIndex\fR C API. The function should store a pointer to
the element at the specified \fBindex\fR in \fB*elemObj\fR.
Indices that are out of bounds should not be treated as errors;
rather, the function should store a null pointer and
return TCL_OK.
.CS
typedef int (\fBTcl_ObjTypeIndexProc\fR) (
    Tcl_Interp *interp,
    Tcl_Obj *listPtr,
    Tcl_Size index,
    Tcl_Obj **elemObj);
.CE
.SS "THE SLICEPROC FIELD"
.PP
The \fBSliceProc\fR correlates with the \fBlrange\fR command,
returning a new List or Abstract List for the portion of the original
list specified.
.CS
typedef int (\fBTcl_ObjTypeSliceProc\fR) (
    Tcl_Interp *interp,
    Tcl_Obj *listPtr,
    Tcl_Size fromIdx,
    Tcl_Size toIdx,
    Tcl_Obj **newObjPtr);
.CE
.SS "THE REVERSEPROC FIELD"
.PP
The \fBReverseProc\fR correlates with the \fBlreverse\fR command,
returning a List or Abstract List that has the same elements as the
input Abstract List, but in reverse order.
.CS
typedef int (\fBTcl_ObjTypeReverseProc\fR) (
    Tcl_Interp *interp,
    Tcl_Obj *listPtr,
    Tcl_Obj **newObjPtr);
.CE
.SS "THE GETELEMENTS FIELD"

const char *
\fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
.sp
\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
.fi
.SH ARGUMENTS
.AS Tcl_PanicProc *panicProc
.AP "const char" *format in
A printf-style format string.
.AP "" arg in
Arguments matching the format string.
.AP Tcl_PanicProc *panicProc in
Procedure to report fatal error message and abort.
.BE
.SH DESCRIPTION

.AP void *clientDataPtr out
Pointer to place to store the value associated with the matching
package. It is only changed if the pointer is not NULL and the
function completed successfully. The storage can be any pointer
type with the same size as a void pointer.
.AP Tcl_Size objc in
Number of requirements.
.AP Tcl_Obj **objv in
Array of requirements.
.BE
.SH DESCRIPTION
.PP
These procedures provide C-level interfaces to Tcl's package and
version management facilities.
.PP

.sp
\fBTcl_GetChannelErrorInterp\fR(\fIinterp, msgPtr\fR)
.fi
.SH ARGUMENTS
.AS Tcl_Channel chan
.AP Tcl_Channel chan in
Refers to the Tcl channel whose bypass area is accessed.
.AP Tcl_Interp *interp in
Refers to the Tcl interpreter whose bypass area is accessed.
.AP Tcl_Obj *msg in
Error message put into a bypass area. A list of return options and values,
followed by a string message. Both message and the option/value information
are optional. This \fImust\fR be a well-formed list.
.AP Tcl_Obj **msgPtr out
Reference to a place where the message stored in the accessed bypass area can
be stored in.
.BE
.SH DESCRIPTION
.PP
The standard definition of a Tcl channel driver does not permit the direct
return of arbitrary error messages, except for the setting and retrieval of

Tcl_Sleep \- delay execution for a given number of milliseconds
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
\fBTcl_Sleep\fR(\fIms\fR)
.fi
\fBTcl_SleepMicroSeconds\fR(\fIus\fR)
.fi
.SH ARGUMENTS
.AS int ms
.AP int ms in
Number of milliseconds to sleep.
.AS long long us
.AP long long us in
Number of micro-seconds to sleep.
.BE
.SH DESCRIPTION
.PP
Those procedures delays the calling process by the given time
and return after the time has elapsed.
The two variants of the command only differ in thue time unit.
\fBTcl_Sleep\fR uses milli-seconds, while, \fBTcl_SleepMicroSeconds\fR
uses micro-seconds.
They are typically used for things like flashing a button,
where the delay is short and the
application need not do anything while it waits.  For longer
delays where the application needs to respond to other events
during the delay, the procedure \fBTcl_CreateTimerHandler\fR
should be used instead of those commands.
.SH KEYWORDS
sleep, time, wait

'\"
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_StringObj 3 8.1 Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_NewStringObj, Tcl_NewUnicodeObj, Tcl_SetStringObj, Tcl_SetUnicodeObj, Tcl_GetStringFromObj, Tcl_GetString, Tcl_GetUnicodeFromObj, Tcl_GetUnicode, Tcl_GetUniChar, Tcl_GetCharLength, Tcl_GetRange, Tcl_AppendToObj, Tcl_AppendUnicodeToObj, Tcl_AppendObjToObj, Tcl_AppendStringsToObj, Tcl_AppendLimitedToObj, Tcl_Format, Tcl_AppendFormatToObj, Tcl_ObjPrintf, Tcl_AppendPrintfToObj, Tcl_SetObjLength, Tcl_AttemptSetObjLength, Tcl_ConcatObj, Tcl_IsEmpty \- manipulate Tcl values as strings
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
Tcl_Obj *
\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
.sp

\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
.sp
int
\fBTcl_AttemptSetObjLength\fR(\fIobjPtr, newLength\fR)
.sp
Tcl_Obj *
\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
.sp
int
\fBTcl_IsEmpty\fR(\fIfIobjPtr\fR)
.fi
.SH ARGUMENTS
.AS "const Tcl_UniChar" *appendObjPtr in/out
.AP "const char" *bytes in
Points to a TUTF-8 (Tcl's internal modified UTF-8 encoding)
byte sequence bytes used to set or append to a string value.
This byte array may contain embedded null characters

If NULL is passed then the suffix
.QW "..."
is used.
.AP "const char" *format in
Format control string including % conversion specifiers.
.AP Tcl_Size objc in
The number of elements to format or concatenate.
.AP Tcl_Obj **objv in
The array of values to format or concatenate.
.AP Tcl_Size newLength in
New length for the string value of \fIobjPtr\fR, not including the
final null character.
.BE
.SH DESCRIPTION
.PP

array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
as it copies the string representations of the \fIobjv\fR array to the
result. If an element of the \fIobjv\fR array consists of nothing but
white space, then that value is ignored entirely. This white-space
removal was added to make the output of the \fBconcat\fR command
cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
newly-created value whose ref count is zero.
.PP
The \fBTcl_IsEmpty\fR function returns 1 if \fIobjPtr\fR is the empty
string, 0 otherwise.
It doesn't generate the string representation (unless there
is no other way to do it), so it can safely be called on lists with
billions of elements, or any other data structure for which
it is impossible or expensive to construct the string representation.
.SH "REFERENCE COUNT MANAGEMENT"
.PP
\fBTcl_NewStringObj\fR, \fBTcl_NewUnicodeObj\fR, \fBTcl_Format\fR,
\fBTcl_ObjPrintf\fR, and \fBTcl_ConcatObj\fR always return a zero-reference
object, much like \fBTcl_NewObj\fR.
.PP
\fBTcl_GetStringFromObj\fR, \fBTcl_GetString\fR, \fBTcl_GetUnicodeFromObj\fR,

.sp
\fBTcl_SetMainLoop\fR(\fImainLoopProc\fR)
.fi
.SH ARGUMENTS
.AS Tcl_MainLoopProc *mainLoopProc
.AP Tcl_Size argc in
Number of elements in \fIargv\fR.
.AP char **argv in
Array of strings containing command-line arguments. On Windows, when
using \fB\-DUNICODE\fR, the parameter type changes to wchar_t **.
.AP char **charargv in
As argv, but does not change type to wchar_t **.
.AP char **wideargv in
As argv, but type is always wchar_t **.
.AP Tcl_AppInitProc *appInitProc in
Address of an application-specific initialization procedure.
The value for this argument is usually \fBTcl_AppInit\fR.
.AP Tcl_Obj *path in
Name of file to use as startup script, or NULL.
.AP "const char" *encoding in
Encoding of file to use as startup script, or NULL.

The result of invoking the \fIproc\fR is a dynamically allocated
string that will be released by the Tcl library via a call to
\fBTcl_Free\fR.  Must not be specified at the same time as
\fBTCL_TRACE_RESULT_OBJECT\fR.
.TP
\fBTCL_TRACE_RESULT_OBJECT\fR
.
The result of invoking the \fIproc\fR is a Tcl_Obj * (cast to a char *)
with a reference count of at least one.  The ownership of that
reference will be transferred to the Tcl core for release (when the
core has finished with it) via a call to \fBTcl_DecrRefCount\fR.  Must
not be specified at the same time as \fBTCL_TRACE_RESULT_DYNAMIC\fR.
.PP
Whenever one of the specified operations occurs on the variable,
\fIproc\fR will be invoked.

If \fIproc\fR returns a non-NULL value it signifies that an
error occurred.
The return value must be a pointer to a static character string
containing an error message,
unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
\fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
either a dynamic string (to be released with \fBTcl_Free\fR) or a
Tcl_Obj * (cast to char * and to be released with
\fBTcl_DecrRefCount\fR) containing the error message.
If a trace procedure returns an error, no further traces are
invoked for the access and the traced access aborts with the
given message.
Trace procedures can use this facility to make variables
read-only, for example (but note that the value of the variable
will already have been modified before the trace procedure is

'\"
'\" Copyright (c) 2025 Ashok P. Nadkarni
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH Tcl_UtfToNormalized 3 "9.1" Tcl "Tcl Library Procedures"
.so man.macros
.BS
.SH NAME
Tcl_UtfToNormalized, Tcl_UtfToNormalizedDString \- procedures for Unicode normalization
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
.sp
int
\fBTcl_UtfToNormalized\fR(\fIinterp, src, numBytes, normForm, profile, dst, dstLen, dstWrotePtr\fR)
.sp
int
\fBTcl_UtfToNormalizedDString\fR(\fIinterp, src, numBytes, normForm, profile, dstPtr\fR)
.fi
.SH ARGUMENTS
.AP Tcl_Interp *interp in
Interpreter to use for error reporting, or NULL if no error reporting is
desired.
.AP "const char" *src in
An array of bytes in Tcl's internal UTF-8 based encoding.
.AP Tcl_Size numBytes in
Length of \fIsrc\fR in bytes.  If the length is negative,
the length includes all bytes until the first nul byte.
.AP char *dst out
Buffer in which the converted result will be stored.  No more than
\fIdstLen\fR bytes will be stored in \fIdst\fR.
.AP Tcl_Size dstLen in
The size of the output buffer \fIdst\fR in bytes.
.AP Tcl_Size *dstWrotePtr out
Filled with the number of bytes in the normalized string. This number
does not include the terminating nul character.
May be NULL.
.AP Tcl_UnicodeNormalizationForm normForm in
Must be one of the \fBTcl_UnicodeNormalizationForm\fR members
\fBTCL_NFC\fR, \fBTCL_NFD\fR, \fBTCL_NFKC\fR or \fBTCL_NFKD\fR specifying
the Unicode normalization type.
.AP int profile in/out
The encoding profile as described in the \fBTcl_GetEncoding\fR documentation.
Must be either \fBTCL_ENCODING_PROFILE_STRICT\fR
or \fBTCL_ENCODING_PROFILE_REPLACE\fR.
.AP Tcl_DString *dstPtr out
Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
result, which is also encoded in Tcl's internal UTF-8 encoding, will be stored.
The function initializes the storage and caller must call
\fBTcl_DStringFree\fR on success.
.BE
.SH DESCRIPTION
.PP
The \fBTcl_UtfToNormalized\fR and \fBTcl_UtfToNormalizedDString\fR functions
transform the passed string into one of the standard normalization forms defined
in the Unicode standard. The normalization form is specified via the
\fInormForm\fR argument which must have one of the values \fBTCL_NFC\fR,
\fBTCL_NFD\fR, \fBTCL_NFKC\fR or \fBTCL_NFKD\fR corresponding to the Unicode
normalization forms \fBNormalization Form C\fR (NFC), \fBNormalization Form D\fR
(NFD), \fBNormalization Form KC\fR (NFKC) and \fBNormalization Form KD\fR (NFKD)
respectively. For details on the above normalization forms, refer to Section
3.11 of the Unicode standard
(https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/).
.PP
The \fBTcl_UtfToNormalized\fR function stores the normalized result
in the buffer provided by the caller through the \fIdst\fR argument. The
result is nul terminated but the nul is not included in the count of
stored bytes returned in \fIdstWrotePtr\fR. The function returns TCL_OK
on success, TCL_CONVERT_NOSPACE if there is insufficient room in the output
buffer and TCL_ERROR in case of other failures. In the latter two cases,
an error message is stored in \fIinterp\fR if it is not NULL.
.PP
The \fBTcl_UtfToNormalizedDString\fR function stores the normalized result
in \fIdstPtr\fR which must eventually be freed by caller through
\fBTcl_DStringFree\fR. The function returns TCL_OK on success and
TCL_ERROR on failure with an error message in \fIinterp\fR if it is not NULL.
.SH "SEE ALSO"
unicode(n)
.SH KEYWORDS
utf, Unicode, normalize

.AS "Tcl_Obj *const" *message
.AP Tcl_Interp interp in
Interpreter in which error will be reported: error message gets stored
in its result value.
.AP Tcl_Size objc in
Number of leading arguments from \fIobjv\fR to include in error
message.
.AP "Tcl_Obj *const" *objv in
Arguments to command that had the wrong number of arguments.
.AP "const char" *message in
Additional error information to print after leading arguments
from \fIobjv\fR.  This typically gives the acceptable syntax
of the command.  This argument may be NULL.
.BE
.SH DESCRIPTION

\fBafter idle \fR?\fIscript script script ...\fR?
\fBafter info \fR?\fIid\fR?
.fi
.BE
.SH DESCRIPTION
.PP
This command is used to delay execution of the program or to execute
a command in background sometime in the future.
This command uses a monotonic clock if available.
It has several forms, depending on the first argument to the command:
.\" METHOD: <none>
.TP
\fBafter \fIms\fR
.
\fIMs\fR must be an integer giving a time in milliseconds.
A negative number is treated as 0.
The command sleeps for \fIms\fR milliseconds and then returns.

.\" METHOD: cancel
.TP
\fBafter cancel \fIid\fR
.
Cancels the execution of a delayed command that
was previously scheduled.
\fIId\fR indicates which command should be canceled;  it must have
been the return value from a previous \fBafter\fR or \fBtimer\fR command.
If the command given by \fIid\fR has already been executed then
the \fBafter cancel\fR command has no effect.
.TP
\fBafter cancel \fIscript script ...\fR
.
This command also cancels the execution of a delayed command.
The \fIscript\fR arguments are concatenated together with space

\fIid\fR must have been the return value from some previous call
to \fBafter\fR and it must not have triggered yet or been canceled.
In this case the command returns a list with two elements.
The first element of the list is the script associated
with \fIid\fR, and the second element is either
\fBidle\fR or \fBtimer\fR to indicate what kind of event
handler it is.
Monotonic and wall clock events have the kind \fBtimer\fR.
Use \fBtimer info\fR to differntiate between the two clocks and to
retrieve the scheduled event time.
.LP
The \fBafter \fIms\fR and \fBafter idle\fR forms of the command
assume that the application is event driven:  the delayed commands
will not be executed unless the application enters the event loop.
In applications that are not normally event-driven, such as
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
and \fBupdate\fR commands.
.SH "TIME MAXIMUM VALUE"
The argument \fIdelay\fR is bound to a resulting 63 bit monotonic clock value
(in unit microseconds).
Any higher value (which is after year 294441) will result in a \fBtime to far\fR error.
.SH "EXAMPLES"
This defines a command to make Tcl do nothing at all for \fIN\fR
seconds:
.PP
.CS
proc sleep {N} {
    \fBafter\fR [expr {int($N * 1000)}]

proc doOneStep {} {
    if {[::my_calc::one_step]} {
        \fBafter idle\fR [list \fBafter\fR 0 doOneStep]
    }
}
doOneStep
.CE
.SH "MAXIMUM TIME"
The maximum supported time point is bound to a 63 bit microseconds value.
This is minimum around year 294441.
Specifying time delays resulting in larger monotonic time values will raise an error.
.SH "COMPATIBILITY"
This command uses a monotonic clock if available.
All versions prior to 9.1 used a wall clock for this command.
The new \fBtimer\fR command features options using the wall clock.
.SH "SEE ALSO"
concat(n), interp(n), timer(n), update(n), vwait(n)
.SH KEYWORDS
cancel, delay, idle callback, sleep, time
'\" Local Variables:
'\" mode: nroff
'\" End:

'\"
'\" Generated from file './doc/clock.dt' by tcllib/doctools with format 'nroff'
'\" Copyright (c) 2004 Kevin B. Kenny <kennykb@acm.org>. All rights reserved.
'\"
.TH "clock" n 8.5 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
.SH NAME
clock \- Obtain and manipulate dates and times
.SH "SYNOPSIS"
.nf
\fBpackage require Tcl 9.1-\fR

\fBclock add\fI timeVal\fR ?\fIcount unit ...\fR? ?\fI\-option value\fR?
\fBclock clicks\fR ?\fI\-option\fR?
\fBclock format\fI timeVal\fR ?\fI\-option value ...\fR?
\fBclock microseconds\fR
\fBclock milliseconds\fR
\fBclock monotonic\fR
\fBclock scan\fI inputString\fR ?\fI\-option value ...\fR?
\fBclock seconds\fR
.fi
.BE
.SH "DESCRIPTION"
.PP
The \fBclock\fR command performs several operations that obtain and

Formats a time that is expressed as an integer number of seconds into a format
intended for consumption by users or external programs.
See \fBFORMATTING TIMES\fR for a full description.
.\" METHOD: microseconds
.TP
\fBclock microseconds\fR
.
Returns the current wall clock time as an integer number of microseconds.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.\" METHOD: milliseconds
.TP
\fBclock milliseconds\fR
.
Returns the current wall clock time as an integer number of milliseconds.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.TP
\fBclock monotonic\fR
.
Returns the current monontonic clock value in microseconds.
See \fBHIGH RESOLUTION TIMERS\fR for a full description.
.\" METHOD: scan
.TP
\fBclock scan\fI inputString\fR ?\fI\-option value ...\fR?
.
Scans a time that is expressed as a character string and produces an
integer number of seconds.
See \fBSCANNING TIMES\fR for a full description.
.\" METHOD: seconds
.TP
\fBclock seconds\fR
.
Returns the current wall clock time as an integer number of seconds.
.SS "PARAMETERS"
.TP
\fIcount\fR
.
An integer representing a count of some unit of time.  See
\fBCLOCK ARITHMETIC\fR for the details.
.TP

.PP
If multiple \fIcount unit\fR pairs are present on the command, they
are evaluated consecutively, from left to right.
.SH "HIGH RESOLUTION TIMERS"
.PP
Most of the subcommands supported by the \fBclock\fR command deal with
times represented as a count of seconds from the epoch time, and this is the
representation that \fBclock seconds\fR returns.  There are four exceptions,
which are all intended for use where higher-resolution times are required.
\fBclock milliseconds\fR returns the count of milliseconds from the
epoch time, and \fBclock microseconds\fR returns the count of microseconds
from the epoch time. In addition, there is a \fBclock clicks\fR command
that returns a platform-dependent high-resolution timer.  Unlike
\fBclock seconds\fR and \fBclock milliseconds\fR, the value
of \fBclock clicks\fR is not guaranteed to be tied to any fixed
epoch; it is simply intended to be the most precise interval timer
available, and is intended only for relative timing studies such as
benchmarks.
\fBclock monotonic\fR is a system monotonic clock and has no fixed start value.
As a difference to the others, it is guranteed to be contiguous.
.SH "FORMATTING TIMES"
.PP
The \fBclock format\fR command produces times for display to a user
or writing to an external medium.  The command accepts times that are
expressed in seconds from the epoch time of 1 January 1970, 00:00 UTC,
as returned by \fBclock seconds\fR, \fBclock scan\fR, \fBclock add\fR,
\fBfile atime\fR or \fBfile mtime\fR.

.IP [1]
If the string contains a \fB%s\fR format group, representing
seconds from the epoch, that group is used to determine the date.
.IP [2]
If the string contains a \fB%J\fR, \fB%EJ\fR or \fB%Ej\fR format groups,
representing the Calendar or Astronomical Julian Day Number, that groups
are used to determine the date.
Note, that in case of \fB%EJ\fR or \fB%Ej\fR format groups, representing
the Julian Date with time fraction, this groups may be used to determine
the date and time.
.IP [3]
If the string contains a complete set of format groups specifying
century, year, month, and day of month; century, year, and day of year;
or ISO8601 fiscal year, week of year, and day of week; those groups are
combined and used to determine the date.  If more than one complete

determined in the namespace that the \fBcoroutine\fR command was called from.
.PP
.VS TIP383
A suspended coroutine (i.e., one that has \fByield\fRed or \fByieldto\fR-d)
may have its state inspected (or modified) at that point by using
\fBcoroprobe\fR to run a command at the point where the coroutine is at. The
command takes the name of the coroutine to run the command in, \fIcoroName\fR,
and the name of a command (and any arguments it requires) to immediately run
at that point. The result of that command is the result of the \fBcoroprobe\fR
command, and the gross state of the coroutine remains the same afterwards
(i.e., the coroutine is still expecting the results of a \fByield\fR or
\fByieldto\fR as before) though variables may have been changed.
.PP
Similarly, the \fBcoroinject\fR command may be used to place a command to be
run inside a suspended coroutine (when it is resumed) to process arguments,

'\"
'\" Copyright (c) 2025 Donal Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH divmod n 9.1 Tcl "Tcl Integer Division"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
divmod \- Divide an integer by another and report quotient and remainder
.SH SYNOPSIS
\fBpackage require tcl 9.1\fR
.sp
\fBdivmod \fIx y\fR
.BE
.SH DESCRIPTION
The \fBdivmod\fR command takes two integer numbers, \fIx\fR and \fIy\fR, and
returns a list of two values. The first element of the result is the
whole quotient of \fIx\fR/\fIy\fR, and the second is the remainder such that
the sum of the remainder and the product of the quotient and \fIy\fR is equal
to \fIx\fR.
.PP
The quotient and remainder are calculated using the same rules as for Tcl's
\fB/\fR and \fB%\fR operators.
.SH EXAMPLE
.PP
.CS
lassign [\fBdivmod\fR 123 50] q r
puts "quotient=$q remainder=$r"
#       quotient=2 remainder=23
.CE
.SH "SEE ALSO"
expr(n), mathfunc(n), mathop(n)
.SH KEYWORDS
division, integer value
'\" Local Variables:
'\" mode: nroff
'\" End:

.PP
This command treats its arguments as the specification
of one or more subprocesses to execute.
The arguments take the form of a standard shell pipeline
where each \fIarg\fR becomes one word of a command, and
each distinct command becomes a subprocess.
The result of the command is the standard output of the final subprocess in
the pipeline, interpreted using the system \fBencoding\fR; to use any other
encoding (especially including binary data), the pipeline must be
\fBopen\fRed, configured and read explicitly.
.PP
If the initial arguments to \fBexec\fR start with \fB\-\fR then
they are treated as command-line switches and are not part
of the pipeline specification.  The following switches are
currently supported:
.\" OPTION: -encoding
.TP 13
\fB\-encoding \fIencodingName\fR
.
Specifies the name of the encoding to use to decode the output of the first

subprocess. Defaults to that returned by the \fBencoding system\fR command.
.\" OPTION: -ignorestderr
.TP 13
\fB\-ignorestderr\fR
.
Stops the \fBexec\fR command from treating the output of messages to the
pipeline's standard error channel as an error case.
.\" OPTION: -keepnewline

or
.QW <@
then the standard input for the first command in the
pipeline is taken from the application's current standard input.
.PP
If the last \fIarg\fR is
.QW &
then the pipeline will be executed in background.
In this case the \fBexec\fR command will return a list whose
elements are the process identifiers for all of the subprocesses
in the pipeline.
The standard output from the last command in the pipeline will
go to the application's standard output if it has not been
redirected, and error output from all of
the commands in the pipeline will go to the application's

.PP
\fBexec\fR will not work well with TUI applications when a console is not
present, as is done when launching applications under wish.  It is desirable
to have console applications hidden and detached.  This is a designed-in
limitation as \fBexec\fR wants to communicate over pipes.  The Expect
extension addresses this issue when communicating with a TUI application.
.PP
When attempting to execute an application, \fBexec\fR searches directories
in the same manner as described for the \fBauto_execok\fR command. However,
with respect to file extensions, unlike \fBauto_execok\fR, \fBexec\fR only
searches for
the name as it was specified and then in order,
\fB.com\fR, \fB.exe\fR, \fB.bat\fR and \fB.cmd\fR. The \fBPATHEXT\fR


environment variable is disregarded as are any file associations.












In order to execute shell built-in commands like \fBdir\fR and \fBcopy\fR,
other extensions in \fBPATHEXT\fR, or registered application paths,
make use of \fBauto_execok\fR to retrieve the command to be passed to
\fBexec\fR.

.RE
.TP
\fBUnix\fR (including macOS)
.
The \fBexec\fR command is fully functional and works as described.
.SH "UNIX EXAMPLES"
.PP

.
Logical OR.  If both operands are false, the result is 0, or 1 otherwise.
This operator evaluates lazily; it only evaluates its second operand if it
must in order to determine its result.
.TP 20
\fIx \fB?\fI y \fB:\fI z\fR
.
If-then-else, as in C.  If \fIx\fR is false , the result is the value of
\fIy\fR.  Otherwise the result is the value of \fIz\fR.
This operator evaluates lazily; it evaluates only one of \fIy\fR or \fIz\fR.
.PP
The exponentiation operator promotes types in the same way that the multiply
and divide operators do, and the result is is the same as the result of
\fBpow\fR.
Exponentiation groups right-to-left within a precedence level. Other binary

\fItarget\fR is an existing directory, then the second form is used.
The second form moves each \fIsource\fR file or directory into the
directory \fItargetDir\fR. Existing files will not be overwritten
unless the \fB\-force\fR option is specified.  When operating inside a
single filesystem, Tcl will rename symbolic links rather than the
things that they point to.  Trying to overwrite a non-empty directory,
overwrite a directory with a file, or a file with a directory will all
result in errors. There is no guarantee that metadata such as attributes
or access control lists are preserved by the command.
Arguments are processed in the order specified,
halting at the first error, if any.  A \fB\-\|\-\fR marks the end of
switches; the argument following the \fB\-\|\-\fR will be treated as a
\fIsource\fR even if it starts with a \fB\-\fR.
.\" METHOD: rootname
.TP
\fBfile rootname \fIname\fR
.

# Make sure that where we're going to move to exists...
if {![\fBfile isdirectory\fR [\fBfile dirname\fR $newName]]} {
    \fBfile mkdir\fR [\fBfile dirname\fR $newName]
}
\fBfile rename\fR $oldName $newName
\fBfile link\fR -symbolic $oldName $newName
.CE










.SH "SEE ALSO"
filename(n), open(n), close(n), eof(n), gets(n), tell(n), seek(n),
fblocked(n), flush(n)
.SH KEYWORDS
attributes, copy files, delete files, directory, file, move files, name,
rename files, stat, user
'\" Local Variables:
'\" mode: nroff
'\" fill-column: 78
'\" End:

'\"
'\" Copyright (c) 2025 Donal Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH frexp n 9.1 Tcl "Tcl Float Decomposition"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
frexp \- Split a floating-point number into fraction and exponent parts
.SH SYNOPSIS
\fBpackage require tcl 9.1\fR
.sp
\fBfrexp \fIvalue\fR
.BE
.SH DESCRIPTION
The \fBfrexp\fR command takes a floating-point number, \fIvalue\fR, and
returns a list of two values. The first element of the result is the
fractional part of \fIvalue\fR (signed, of magnitude between 0.5 and 1.0),
and the second element of the result is the integer exponent from \fIvalue\fR.
When \fIvalue\fR is infinite, the fraction is also infinite (of the same sign).
.SH EXAMPLE
.PP
The \fBfrexp\fR command is paired with the \fBldexp\fR function, like this:
.PP
.CS
set value 123.456
lassign [\fBfrexp\fR $value] frac exp
set recovered [expr { ldexp($frac, $exp) }]
puts "$value -> $frac*2**$exp -> $recovered"
#       123.456 -> 0.9645*2**7 -> 123.456
.CE
.SH "SEE ALSO"
expr(n), mathfunc(n), modf(n)
.SH KEYWORDS
floating point
'\" Local Variables:
'\" mode: nroff
'\" End:

The command sets the maximum size of the Tcl call stack only. It cannot
by itself prevent stack overflows on the C stack being used by the
application. If your machine has a limit on the size of the C stack, you
may get stack overflows before reaching the limit set by the command. If
this happens, see if there is a mechanism in your system for increasing
the maximum size of the C stack.
.RE
.\" METHOD: set
.TP
\fBinterp set\fI path varName\fR ?\fIvalue\fR?
.VS 9.1
Writes to, or reads from, the variable \fIvarName\fR in the interpreter
specifed by \fIpath\fR. If \fIvalue\fR is given, writes to the variable and
returns its new value; if \fIvalue\fR is omitted, reads from the variable.
As with the \fBset\fR command, traces may affect what the value of the
variable is.
.VE 9.1
.\" METHOD: share
.TP
\fBinterp share\fI srcPath channel destPath\fR
.
Causes the IO channel identified by \fIchannel\fR to become shared
between the interpreter identified by \fIsrcPath\fR and the interpreter
identified by \fIdestPath\fR. Both interpreters have the same permissions

The command sets the maximum size of the Tcl call stack only. It cannot
by itself prevent stack overflows on the C stack being used by the
application. If your machine has a limit on the size of the C stack, you
may get stack overflows before reaching the limit set by the command. If
this happens, see if there is a mechanism in your system for increasing
the maximum size of the C stack.
.RE
.\" METHOD: set
.TP
\fIchild \fBset\fR \fIvarName\fR ?\fIvalue\fR?
.VS 9.1
Writes to, or reads from, the variable \fIvarName\fR in the \fIchild\fR
interpreter. If \fIvalue\fR is given, writes to the variable and
returns its new value; if \fIvalue\fR is omitted, reads from the variable.
As with the \fBset\fR command, traces may affect what the value of the
variable is.
.VE 9.1
.SH "SAFE INTERPRETERS"
.PP
A safe interpreter is one with restricted functionality, so that
is safe to execute an arbitrary script from your worst enemy without
fear of that script damaging the enclosing application or the rest
of your computing environment.  In order to make an interpreter
safe, certain commands and variables are removed from the interpreter.

'\"
'\" Copyright (c) 2025 Donal K. Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH lfilter n "" Tcl "Tcl Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
lfilter \- Select elements from a list based on an expression
.SH SYNOPSIS
\fBlfilter \fIvarname list expression\fR
.br
\fBlfilter \fIvarlist1 list1\fR ?\fIvarlist2 list2 ...\fR? \fIbody\fR
.BE
.SH DESCRIPTION
.PP
The \fBlfilter\fR command implements a loop where the loop variable(s) take on
values from one or more lists, and the loop returns a list of values from the
(first) list where the \fIbody\fR script evaluates to a true value.
.PP
In the simplest case there is one loop variable, \fIvarname\fR, and one list,
\fIlist\fR, that is a list of values to assign to \fIvarname\fR. The
\fIbody\fR argument is a Tcl script. For each element of \fIlist\fR
(in order from first to last), \fBlfilter\fR assigns the contents of the
element to \fIvarname\fR as if the \fBlindex\fR command had been used to
extract the element, then calls the Tcl interpreter to execute \fIbody\fR.
If execution of the script completes normally and produces a true value,
that element of \fIlist\fR is appended to an accumulator list. \fBlmap\fR
returns the accumulator list.
.PP
In the general case there can be more than one value list (e.g., \fIlist1\fR
and \fIlist2\fR), and each value list can be associated with a list of loop
variables (e.g., \fIvarlist1\fR and \fIvarlist2\fR). During each iteration of
the loop the variables of each \fIvarlist\fR are assigned consecutive values
from the corresponding \fIlist\fR. Values in each \fIlist\fR are used in order
from first to last, and each value is used exactly once. The total number of
loop iterations is large enough to use up all the values from all the value
lists. If a value list does not contain enough elements for each of its loop
variables in each iteration, empty values are used for the missing elements.
For each iteration, the value that is appended when \fIbody\fR yields
a true value (i.e., anything accepted by \fBTcl_GetBooleanFromObj\fR as a
boolean) is the value that was assigned to the first variable of the first
list of variables; all other values are not collected.
.PP
The \fBbreak\fR and \fBcontinue\fR statements may be invoked inside
\fIbody\fR, with the same effect as in the \fBfor\fR and \fBforeach\fR
commands. In these cases the body does not complete normally and the lead value
is not appended to the accumulator list.
.SH EXAMPLES
.PP
Select the elements of the list that are odd:
.PP
.CS
\fBlfilter\fR x {0 2 4 1 3 5 10 8 6 11 9 7} {
    expr {($x % 2) == 1}
}
# The result is "1 3 5 11 9 7"
.CE
.PP
Select elements of a list according to a condition in another list:
.PP
.CS
\fBlfilter\fR x [lseq 10] y [lseq 0 .. 1 by 0.1] {
    expr {$y > 0.3 && $y < 0.7}
}
# The result is "4 5 6"
.CE
.PP
Select the elements containing at least five characters:
.PP
.CS
set sentence "The quick brown fox jumps over the lazy dog."
\fBlfilter\fR word [split $sentence] {
    expr {[string length $word] >= 5}
}
# The result is "quick brown jumps"
.CE
.PP
Select the elements that are true palindromes:
.PP
.CS
set usernames {tom bob steve dood}
\fBlfilter\fR word $usernames {
    string equal $word [string reverse $word]
}
# The result is "bob dood"
.CE
.SH "SEE ALSO"
dict(n), foreach(n), lmap(n), lsearch(n)
.SH KEYWORDS
foreach, iteration, list, loop, filter
'\" Local Variables:
'\" mode: nroff
'\" End:

.SH "COMMAND PROCEDURES"
.PP
The following procedures are provided in the Tcl library:
.\" COMMAND: auto_execok
.TP
\fBauto_execok \fIcmd\fR
.

The command returns a list of arguments to be passed to \fBexec\fR to

execute the external program named by \fIcmd\fR. If no such program is






found, the command returns an empty list. Callers must not make any
assumptions about any returned paths being in any particular form such
as normalized, absolute, native or canonical.

.RS
.PP
On platforms other than Windows, if \fIcmd\fR contains any path
separators, \fBauto_execok\fR checks for the existence of an executable
file with that path. If present, it is returned as the first element of
the returned list. Note that this may be a relative path. If \fIcmd\fR
does not contain any path separators, all directories in the \fBPATH\fR
environment variable are searched for an executable file of that name.
If found, a list containing a single element holding the full path to
the file is returned.
.PP
The rest of this description applies to Windows platforms.
.PP
If \fIcmd\fR contains path separators, the command checks for the
existence of a file of that name. If found, the file associations in the
Windows registry is looked up to retrieve the template for the file's
extension. On success, the template is processed to replace environment
variables, placeholders for the file path, converted to list form and
returned. Otherwise, an empty list is returned.
.PP
If \fIcmd\fR does not contain path separators, it is first matched
against the built-in commands in the \fBcmd.exe\fR command shell.
Built-ins that are intended only for batch file use are excluded. On a
match, the returned list is the list of arguments to be passed to
\fBexec\fR to run the built-in using \fBcmd.exe\fR.
.PP
Next, \fBauto_execok\fR searches directories in the following order:
the directory of the process executable, the current working directory
(subject to conditions described below), the Windows \fBsystem32\fR
directory, the Windows directory and the directories in the \fBPATH\fR
environment variable. Within each directory, the command will look for
a file matching the passed name, and if not found, for a file matching
the passed name appended with extensions listed in the \fBPATHEXT\fR
environment variable. The extension of the matched file is looked up in
the file associations in the registry and the corresponding template is
returned after processing as described earlier.
.PP
Inclusion of the current working directory in the list of examined
directories depends on Windows system settings retrieved with the
\fBNeedCurrentDirectoryForExePathW\fR Win32 API. Refer to its
documentation for details. Note that if the current directory, \fB.\fR,
is explicitly included in \fBPATH\fR, it is not affected by this
setting.
.PP
Finally, if all above fails, \fIcmd\fR is looked up in the \fBApp
Paths\fR key in the Windows registry after appending \fB.exe\fR if not
already present. If listed there as a registered application, its path
is returned as the first (and only) list element.
.PP
To run the \fIDIR\fR shell builtin on Windows, you would do:
.PP
.CS
exec {*}[\fBauto_execok\fR dir]
.CE
.PP
To open a \fB.txt\fR file on Windows with the associated program,
you would do:
.PP
.CS
exec {*}[\fBauto_execok\fR path/to/foo.txt]
.CE
.PP
Note in the above that since \fB.txt\fR is not generally included in
\fBPATHEXT\fR, the passed name is not searched for even if it does not
include any path separators.
.PP
To discover if there is a \fIfrobnicate\fR that can be run by \fBexec\fR,
you would do:
.PP
.CS
set mayFrob [expr {[llength [\fBauto_execok\fR frobnicate]] > 0}]
.CE
.RE
.\" COMMAND: auto_import

.\" COMMAND: auto_load
.TP
\fBauto_load \fIcmd\fR
.
This command attempts to load the definition for a Tcl command named
\fIcmd\fR.  To do this, it searches an \fIauto-load path\fR, which is
a list of one or more directories.  The auto-load path is given by the
global variable \fBauto_path\fR if it exists (see the tclvars manual page).
If there is no
\fBauto_path\fR variable, then the \fBTCLLIBPATH\fR environment variable is
used, if it exists.  Otherwise the auto-load path consists of just the
Tcl library directory.  Within each directory in the auto-load path
there must be a file \fBtclIndex\fR that describes one or more
commands defined in that directory and a script to evaluate to load
each of the commands.  The \fBtclIndex\fR file should be generated
with the \fBauto_mkindex\fR command.  If \fIcmd\fR is found in an

any commands.
.\" VARIABLE: auto_noload
.TP
\fBauto_noload\fR
.
If set to any value, then \fBunknown\fR will not attempt to auto-load
any commands.


























.\" VARIABLE: env(TCL_LIBRARY)
.TP
\fBenv(TCL_LIBRARY)\fR
.
If set, then it specifies the location of the directory containing
library scripts (the value of this variable will be
assigned to the \fBtcl_library\fR variable and therefore returned by

\fBenv(TCLLIBPATH)\fR
.
If set, then it must contain a valid Tcl list giving directories to
search during auto-load operations.  Directories must be specified in
Tcl format, using
.QW /
as the path separator, regardless of platform.
This variable is only used when initializing the \fBauto_path\fR variable
(see the \fBauto_load\fR command).
.RS
.PP
A key consequence of this variable is that it gives a way to let the user
of a script specify the list of places where that script may use
\fBpackage require\fR to read packages from. It is not normally usefully
settable within a Tcl script itself \fIexcept\fR to influence where other
interpreters load from (whether made with \fBinterp create\fR or launched

.PP
The following is a minimal extension:
.PP
.CS
#include <tcl.h>
#include <stdio.h>
static int fooCmd(void *clientData,
        Tcl_Interp *interp, Tcl_Size objc, Tcl_Obj *const *objv) {
    printf("called with %d arguments\en", objc);
    return TCL_OK;
}
int Foo_Init(Tcl_Interp *interp) {
    if (Tcl_InitStubs(interp, "8.1", 0) == NULL) {
	return TCL_ERROR;
    }
    printf("creating foo command");
    Tcl_CreateObjCommand2(interp, "foo", fooCmd, NULL, NULL);
    return TCL_OK;
}
.CE
.PP
When built into a shared/dynamic library with a suitable name
(e.g. \fBfoo.dll\fR on Windows, \fBlibfoo.so\fR on Solaris and Linux)
it can then be loaded into Tcl with the following:

mathfunc \- Mathematical functions for Tcl expressions
.SH SYNOPSIS
.nf
\fBpackage require Tcl 8.5-\fR

\fB::tcl::mathfunc::abs\fI arg\fR
\fB::tcl::mathfunc::acos\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::acosh\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::asin\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::asin\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::atan\fI arg\fR
\fB::tcl::mathfunc::atan2\fI y x\fR
.VS TIP745
\fB::tcl::mathfunc::atan\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::bool\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::cbrt\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::ceil\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::copysign\fI x y\fR
.VE TIP745
\fB::tcl::mathfunc::cos\fI arg\fR
\fB::tcl::mathfunc::cosh\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::dim\fI x y\fR
.VE TIP745
\fB::tcl::mathfunc::double\fI arg\fR
\fB::tcl::mathfunc::entier\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::erf\fI arg\fR
\fB::tcl::mathfunc::erfc\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::exp\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::exp2\fI arg\fR
\fB::tcl::mathfunc::expm1\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::floor\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::fma\fI x y z\fR
.VE TIP745
\fB::tcl::mathfunc::fmod\fI x y\fR
\fB::tcl::mathfunc::hypot\fI x y\fR
\fB::tcl::mathfunc::int\fI arg\fR
.VS TIP521
\fB::tcl::mathfunc::isfinite\fI arg\fR
\fB::tcl::mathfunc::isinf\fI arg\fR
\fB::tcl::mathfunc::isnan\fI arg\fR
\fB::tcl::mathfunc::isnormal\fI arg\fR
.VE TIP521
\fB::tcl::mathfunc::isqrt\fI arg\fR
.VS TIP521
\fB::tcl::mathfunc::issubnormal\fI arg\fR
\fB::tcl::mathfunc::isunordered\fI x y\fR
.VE TIP521
.VS TIP745
\fB::tcl::mathfunc::lgamma\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::log\fI arg\fR
\fB::tcl::mathfunc::log10\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::log1p\fI arg\fR
\fB::tcl::mathfunc::log2\fI arg\fR
\fB::tcl::mathfunc::logb\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::max\fI arg\fR ?\fIarg ...\fR?
\fB::tcl::mathfunc::min\fI arg\fR ?\fIarg ...\fR?
.VS TIP745
\fB::tcl::mathfunc::nextafter\fI x y\fR
.VE TIP745
\fB::tcl::mathfunc::pow\fI x y\fR
\fB::tcl::mathfunc::rand\fR
.VS TIP745
\fB::tcl::mathfunc::remainder\fI x y\fR
.VE TIP745
\fB::tcl::mathfunc::round\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::signbit\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::sin\fI arg\fR
\fB::tcl::mathfunc::sinh\fI arg\fR
\fB::tcl::mathfunc::sqrt\fI arg\fR
\fB::tcl::mathfunc::srand\fI arg\fR
\fB::tcl::mathfunc::tan\fI arg\fR
\fB::tcl::mathfunc::tanh\fI arg\fR
.VS TIP745
\fB::tcl::mathfunc::gamma\fI arg\fR
\fB::tcl::mathfunc::trunc\fI arg\fR
.VE TIP745
\fB::tcl::mathfunc::wide\fI arg\fR
.fi
.BE
.SH "DESCRIPTION"
.PP
The \fBexpr\fR command handles mathematical functions of the form
\fBsin($x)\fR or \fBatan2($y,$x)\fR by converting them to calls of the
form \fB[tcl::mathfunc::sin [expr {$x}]]\fR or
\fB[tcl::mathfunc::atan2 [expr {$y}] [expr {$x}]]\fR.
A number of math functions are available by default within the
namespace \fB::tcl::mathfunc\fR; these functions are also available
for code apart from \fBexpr\fR, by invoking the given commands
directly.
.PP
Tcl supports the following mathematical functions in expressions, all
of which work solely with floating-point numbers unless otherwise noted:
.DS
.ta 3.2c 6.4c 9.6c
\fBabs\fR	\fBacos\fR	\fBacosh\fR	\fBasin\fR
\fBasinh\fR	\fBatan\fR	\fBatan2\fR	\fBatanh\fR
\fBbool\fR	\fBcbrt\fR	\fBcopysign\fR	\fBceil\fR
\fBcos\fR	\fBcosh\fR	\fBdim\fR	\fBdouble\fR
\fBentier\fR	\fBerf\fR	\fBerfc\fR	\fBexp\fR
\fBexp2\fR	\fBexpm1\fR	\fBfloor\fR	\fBfma\fR
\fBfmod\fR	\fBgamma\fR	\fBhypot\fR	\fBint\fR
\fBisfinite\fR	\fBisinf\fR	\fBisnan\fR	\fBisnormal\fR
\fBisqrt\fR	\fBissubnormal\fR	\fBisunordered\fR	\fBldexp\fR
\fBlgamma\fR	\fBlog\fR	\fBlog10\fR	\fBlog1p\fR
\fBlog2\fR	\fBlogb\fR	\fBmax\fR	\fBmin\fR
\fBnextafter\fR	\fBpow\fR	\fBrand\fR	\fBremainder\fR
\fBround\fR	\fBsin\fR	\fBsinh\fR	\fBsqrt\fR
\fBsrand\fR	\fBtan\fR	\fBtanh\fR	\fBtrunc\fR
\fBwide\fR
.DE
.PP
In addition to these predefined functions, applications may
define additional functions by using \fBproc\fR (or any other method,
such as \fBinterp alias\fR or \fBTcl_CreateObjCommand\fR) to define
new commands in the \fBtcl::mathfunc\fR namespace.
.SS "DETAILED DEFINITIONS"
.\" COMMAND: abs
.TP
\fBabs \fIarg\fR
.
Returns the absolute value of \fIarg\fR.  \fIArg\fR may be either
integer or floating-point, and the result is returned in the same form.
.\" COMMAND: acos
.TP
\fBacos \fIarg\fR
.
Returns the arc cosine of \fIarg\fR, in the range [\fI0\fR,\fIpi\fR]
radians. \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR].
.\" COMMAND: acosh
.TP
\fBacosh \fIarg\fR
.VS TIP745
Returns the arc hyperbolic cosine of \fIarg\fR, in the range [\fI0\fR,\fIinf\fR]
radians. \fIArg\fR should be in the range [\fI1\fR,\fIinf\fR].
.VE TIP745
.\" COMMAND: asin
.TP
\fBasin \fIarg\fR
.
Returns the arc sine of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR]
radians.  \fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR].
.\" COMMAND: asinh
.TP
\fBasinh \fIarg\fR
.VS TIP745
Returns the arc hyperbolic sine of \fIarg\fR, in the range [\fI\-inf\fR,\fIinf\fR].
.VE TIP745
.\" COMMAND: atan
.TP
\fBatan \fIarg\fR
.
Returns the arc tangent of \fIarg\fR, in the range [\fI\-pi/2\fR,\fIpi/2\fR]
radians.
.\" COMMAND: atan2
.TP
\fBatan2 \fIy x\fR
.
Returns the arc tangent of \fIy\fR/\fIx\fR, in the range [\fI\-pi\fR,\fIpi\fR]
radians.  \fIx\fR and \fIy\fR cannot both be 0.  If \fIx\fR is greater
than \fI0\fR, this is equivalent to
.QW "\fBatan \fR[\fBexpr\fR {\fIy\fB/\fIx\fR}]" .
.\" COMMAND: atanh
.TP
\fBatanh \fIarg\fR
.VS TIP745
Returns the arc hyperbolic tangent of \fIarg\fR, in the range [\fI\-inf\fR,\fIinf\fR].
\fIArg\fR should be in the range [\fI\-1\fR,\fI1\fR].
.VE TIP745
.\" COMMAND: bool
.TP
\fBbool \fIarg\fR
.
Accepts any numeric value, or any string acceptable to
\fBstring is boolean\fR, and returns the corresponding
boolean value \fB0\fR or \fB1\fR.  Non-zero numbers are true.
Other numbers are false.  Non-numeric strings produce boolean value in
agreement with \fBstring is true\fR and \fBstring is false\fR.
.\" COMMAND: cbrt
.TP
\fBcbrt \fIarg\fR
.VS TIP745
The argument may be any numeric value.  Returns a floating-point
value that is the cube root of \fIarg\fR.  May return \fBInf\fR when the
argument is a numeric value that exceeds the cube of the maximum value of
the floating-point range.
.VE TIP745
.\" COMMAND: ceil
.TP
\fBceil \fIarg\fR
.
Returns the smallest integral floating-point value (i.e. with a zero
fractional part) not less than \fIarg\fR.  The argument may be any
numeric value.
.\" COMMAND: copysign
.TP
\fBcopysign \fIx y\fR
.VS TIP745
Returns the floating-point value with the magnitude of \fIx\fR and sign of \fIy\fR.
.VE TIP745
.\" COMMAND: cos
.TP
\fBcos \fIarg\fR
.
Returns the cosine of \fIarg\fR, measured in radians.
.\" COMMAND: cosh
.TP
\fBcosh \fIarg\fR
.
Returns the hyperbolic cosine of \fIarg\fR.  If the result would cause
an overflow, an error is returned.
.\" COMMAND: dim
.TP
\fBdim \fIx y\fR
.VS TIP745
Returns the floating-point value that is the maximum of 0 and \fIx\fR\-\fIy\fR.
.VE TIP745
.\" COMMAND: double
.TP
\fBdouble \fIarg\fR
.
The argument may be any numeric value,
If \fIarg\fR is a floating-point value, returns \fIarg\fR, otherwise converts
\fIarg\fR to floating-point and returns the converted value.  May return
\fBInf\fR or \fB\-Inf\fR when the argument is a numeric value that exceeds
the floating-point range.
.\" COMMAND: entier
.TP
\fBentier \fIarg\fR
.
The argument may be any numeric value.  The integer part of \fIarg\fR
is determined and returned.  The integer range returned by this function
is unlimited, unlike \fBint\fR and \fBwide\fR which
truncate their range to fit in particular storage widths.
.\" COMMAND: erf
.TP
\fBerf \fIarg\fR
.VS TIP745
Computes the Gauss error function of the numeric value \fIarg\fR.
.VE TIP745
.\" COMMAND: erfc
.TP
\fBerfc \fIarg\fR
.VS TIP745
Computes the complementary error function of the numeric value \fIarg\fR.
.VE TIP745
.\" COMMAND: exp
.TP
\fBexp \fIarg\fR
.
Returns the exponential of \fIarg\fR, defined as \fIe\fR**\fIarg\fR.
If the result would cause an overflow, an error is returned.
.\" COMMAND: exp2
.TP
\fBexp2 \fIarg\fR
.VS TIP745
Returns the 2 to the power of \fIarg\fR, defined as \fB2\fR**\fIarg\fR.
The result is always a floating point number except if it would cause an
overflow, when an error is returned.
.VE TIP745
.\" COMMAND: expm1
.TP
\fBexpm1 \fIarg\fR
.VS TIP745
Returns the exponential of \fIarg\fR, minus 1, defined as \fIe\fR**\fIarg\fR\-\fB1\fR.
If the result would cause an overflow, an error is returned.
Use of this function can be numerically preferable to of \fBexp\fR for values
close to 1, and is matched with \fBlog1p\fR.
.VE TIP745
.\" COMMAND: floor
.TP
\fBfloor \fIarg\fR
.
Returns the largest integral floating-point value (i.e. with a zero
fractional part) not greater than \fIarg\fR.  The argument may be
any numeric value.
.\" COMMAND: fma
.TP
\fBfma \fIx y z\fR
.VS TIP745
Returns the floating-point value that is the sum of the product of \fIx\fR and
\fIy\fR, and \fIz\fR, without unnecessarily losing intermediate accuracy.
.VE TIP745
.\" COMMAND: fmod
.TP
\fBfmod \fIx y\fR
.
Returns the floating-point remainder of the division of \fIx\fR by
\fIy\fR.  If \fIy\fR is 0, an error is returned.
.\" COMMAND: gamma
.TP
\fBgamma \fIarg\fR
.VS TIP745
Returns the absolute value of the gamma function of \fIarg\fR (a generalized factorial).
If the result would cause an overflow, an error is returned.
.VE TIP745
.\" COMMAND: hypot
.TP
\fBhypot \fIx y\fR
.
Computes the length of the hypotenuse of a right-angled triangle,
approximately
.QW "\fBsqrt\fR [\fBexpr\fR {\fIx\fB*\fIx\fB+\fIy\fB*\fIy\fR}]"

.VS TIP521
Returns 1 if \fIx\fR and \fIy\fR cannot be compared for ordering, that is, if
either one is NaN. Returns 0 if both values can be ordered, that is, if they
are both chosen from among the set of zero, subnormal, normal and infinite
values. Throws an error if either \fIx\fR or \fIy\fR cannot be promoted to a
floating-point value.
.VE TIP521
.\" COMMAND: ldexp
.TP
\fBldexp \fIx y\fR
.VS TIP745
Multiplies a floating-point value \fIx\fR by the number 2 raised to the \fIy\fR power.
.VE TIP745
.\" COMMAND: lgamma
.TP
\fBlgamma \fIarg\fR
.VS TIP745
Returns the natural logarithm of the absolute value of the gamma function of \fIarg\fR.
If the result would cause an overflow, an error is returned.
.VE TIP745
.\" COMMAND: log
.TP
\fBlog \fIarg\fR
.
Returns the natural logarithm of \fIarg\fR.  \fIArg\fR must be a
positive value.
.\" COMMAND: log10
.TP
\fBlog10 \fIarg\fR
.
Returns the base 10 logarithm of \fIarg\fR.  \fIArg\fR must be a
positive value.
.\" COMMAND: log1p
.TP
\fBlog1p \fIarg\fR
.VS TIP745
Returns the natural logarithm of \fIarg\fR+\fB1\fR.  \fIArg\fR must be a
value greater than \-1. This function is numerically preferable to \fBlog\fR
for values very close to 1, and is matched with \fBexpm1\fR.
.VE TIP745
.\" COMMAND: log2
.TP
\fBlog2 \fIarg\fR
.VS TIP745
Returns the base 2 logarithm of \fIarg\fR.  \fIArg\fR must be a
positive value.
.VE TIP745
.\" COMMAND: logb
.TP
\fBlogb \fIarg\fR
.VS TIP745
Returns the value of the unbiased radix-independent exponent from the
floating-point argument \fIarg\fR.
.VE TIP745
.\" COMMAND: max
.TP
\fBmax \fIarg\fB \fR...
.
Accepts one or more numeric arguments.  Returns the one argument
with the greatest value.
.\" COMMAND: min
.TP
\fBmin \fIarg\fB \fR...
.
Accepts one or more numeric arguments.  Returns the one argument
with the least value.
.\" COMMAND: nextafter
.TP
\fBnextafter \fIx y\fR
.VS TIP745
Returns the next floating-point value after (or before) \fIx\fR in the
direction of \fIy\fR. If \fIx\fR and \fIy\fR are equal, returns \fIy\fR.
.VE TIP745
.\" COMMAND: pow
.TP
\fBpow \fIx y\fR
.
Computes the value of \fIx\fR raised to the power \fIy\fR.  If \fIx\fR
is negative, \fIy\fR must be an integer value.
.\" COMMAND: rand
.TP
\fBrand\fR
.
Returns a pseudo-random floating-point value in the range (\fI0\fR,\fI1\fR).
The generator algorithm is a simple linear congruential generator that
is not cryptographically secure.  Each result from \fBrand\fR completely
determines all future results from subsequent calls to \fBrand\fR, so
\fBrand\fR should not be used to generate a sequence of secrets, such as
one-time passwords.  The seed of the generator is initialized from the
internal clock of the machine or may be set with the \fBsrand\fR function.
.\" COMMAND: remainder
.TP
\fBremainder \fIx y\fR
.VS TIP745
Computes the IEEE remainder of the floating point division operation \fIx\fR/\fIy\fR.
.VE TIP745
.\" COMMAND: round
.TP
\fBround \fIarg\fR
.
If \fIarg\fR is an integer value, returns \fIarg\fR, otherwise converts
\fIarg\fR to integer by rounding and returns the converted value.
.\" COMMAND: signbit
.TP
\fBsignbit \fIarg\fR
.VS TIP745
Get the sign bit of the numeric value, \fIarg\fR, as 0 (positive) or 1 (negative).
.VE TIP745
.\" COMMAND: sin
.TP
\fBsin \fIarg\fR
.
Returns the sine of \fIarg\fR, measured in radians.
.\" COMMAND: sinh
.TP

.
Returns the tangent of \fIarg\fR, measured in radians.
.\" COMMAND: tanh
.TP
\fBtanh \fIarg\fR
.
Returns the hyperbolic tangent of \fIarg\fR.
.\" COMMAND: trunc
.TP
\fBtrunc \fIarg\fR
.VS TIP745
Returns the nearest integer not greater in magnitude than \fIarg\fR.
.VE TIP745
.\" COMMAND: wide
.TP
\fBwide \fIarg\fR
.
The argument may be any numeric value.  The integer part of \fIarg\fR
is determined, and then the low order 64 bits of that integer value
are returned as an integer value.
.SH "SEE ALSO"
divmod(n), expr(n), fpclassify(n), frexp(n),
mathop(n), modf(n), namespace(n), remquo(n)
.SH "COPYRIGHT"
.nf
Copyright \(co 1993 The Regents of the University of California.
Copyright \(co 1994-2000 Sun Microsystems Incorporated.
Copyright \(co 2005-2006 Kevin B. Kenny <kennykb@acm.org>.
.fi
'\" Local Variables:
'\" mode: nroff
'\" fill-column: 78
'\" End:

'\"
'\" Copyright (c) 2025 Donal Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH modf n 9.1 Tcl "Tcl Float Decomposition"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
modf \- Split a floating-point number into integer and fraction parts
.SH SYNOPSIS
\fBpackage require tcl 9.1\fR
.sp
\fBmodf \fIvalue\fR
.BE
.SH DESCRIPTION
The \fBmodf\fR command takes a floating-point number, \fIvalue\fR, and
returns a list of two values. The first element of the result is the
whole integer part (as a floating-point number) of \fIvalue\fR, and the
second element of the result is the fractional part of \fIvalue\fR.
The signs of the two elements will match the sign of \fIvalue\fR.
.SH EXAMPLE
.PP
It should be noted that the fractional part may have some digits that
appear to be undetermined by the input. This is due to the nature of
approximation inherent in floating-point arithmetic; the digits will
apparently disappear if the two parts are added back together.
.PP
.CS
set value 123.456
lassign [\fBmodf\fR $value] whole part
set sum [expr {$whole + $part}]
puts "$value -> $whole $part -> $sum"
#       123.456 -> 123.0 0.45600000000000307 -> 123.456
.CE
.SH "SEE ALSO"
expr(n), frexp(n), mathfunc(n)
.SH KEYWORDS
floating point
'\" Local Variables:
'\" mode: nroff
'\" End:

milliseconds.  Normally a receive or transmit data signal stays at the mark
(on=1) voltage until the next character is transferred. A BREAK is sometimes
used to reset the communications line or change the operating mode of
communications hardware.
.SS "ERROR CODES (Windows only)"
.PP
A lot of different errors may occur during serial read operations or during
event polling in background. The external device may have been switched
off, the data lines may be noisy, system buffers may overrun or your mode
settings may be wrong.  That is why a reliable software should always
\fBcatch\fR serial read operations.  In cases of an error Tcl returns a
general file I/O error.  Then \fBfconfigure\fR \fB\-lasterror\fR may help to
locate the problem.  The following error codes may be returned.
.IP \fBRXOVER\fR
Windows input buffer overrun. The data comes faster than your scripts reads

.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
registry \- Manipulate the Windows registry
.SH SYNOPSIS
.nf
\fBtcl::registry \fR?\fI\-mode\fR? \fIoption keyName\fR ?\fIarg arg ...\fR?
\fBpackage require registry 1.4\fR

\fBregistry \fR?\fI\-mode\fR? \fIoption keyName\fR ?\fIarg arg ...\fR?
.fi
.BE
.SH DESCRIPTION
.PP
The \fBregistry\fR package provides a general set of operations for
manipulating the Windows registry.  The package implements the
\fBregistry\fR Tcl command.  This command is only supported on the
Windows platform.  Warning: this command should be used with caution
as a corrupted registry can leave your system in an unusable state.
.PP
Starting with Tcl 9.1, the command is also available as \fBtcl::registry\fR
without requiring the \fBregistry\fR package to be loaded.
.PP
\fIKeyName\fR is the name of a registry key.  Registry keys must be
one of the following forms:
.RS
.PP
\fB\e\e\fIhostname\fB\e\fIrootname\fB\e\fIkeypath\fR
.PP
\fIrootname\fB\e\fIkeypath\fR

'\"
'\" Copyright (c) 2025 Donal Fellows
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH remquo n 9.1 Tcl "Tcl Float Remainder"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
remquo \- Compute floating point remainder and quadrant determinant
.SH SYNOPSIS
\fBpackage require tcl 9.1\fR
.sp
\fBremquo \fIx y\fR
.BE
.SH DESCRIPTION
The \fBremquo\fR command computes the floating-point remainder of
\fIx\fR/\fIy\fR, much like the \fBremainder\fR function. Its result is a list
of two values; the first value is the remainder, and the second value is an
integer containing sign and bits sufficient to determine which octant the
gradient was located within.
.SH EXAMPLE
.PP
.CS
lassign [\fBremquo\fR 12.3 3.89] rem quo
puts "rem=$rem, quo=$quo"
#       rem=0.6300000000000003, quo=3
.CE
.SH "SEE ALSO"
expr(n), mathfunc(n)
.SH KEYWORDS
floating point
'\" Local Variables:
'\" mode: nroff
'\" End:

.TH subst n 7.4 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
subst \- Perform backslash, command, and variable substitutions
.SH SYNOPSIS
.nf
\fBsubst \fR?\fB\-nobackslashes\fR? ?\fB\-nocommands\fR? ?\fB\-novariables\fR? \fIstring\fR
\fBsubst \fR?\fB\-backslashes\fR? ?\fB\-commands\fR? ?\fB\-variables\fR? \fIstring\fR
.fi
.BE
.SH DESCRIPTION
.PP
This command performs variable substitutions, command substitutions,
and backslash substitutions on its \fIstring\fR argument and
returns the fully-substituted result.
The substitutions are performed in exactly the same way as for
Tcl commands.
As a result, the \fIstring\fR argument is actually substituted twice,
once by the Tcl parser in the usual fashion for Tcl commands, and
again by the \fIsubst\fR command.
.PP
If any of the \fB\-nobackslashes\fR, \fB\-nocommands\fR, or
\fB\-novariables\fR are specified, then the corresponding substitutions
are not performed.
For example, if \fB\-nocommands\fR is specified, command substitution
is not performed:  open and close brackets are treated as ordinary characters
with no special interpretation.
.PP
If any of the \fB\-backslashes\fR, \fB\-commands\fR, or
\fB\-variables\fR are specified, then only the corresponding
substitutions are performed. This means that the following lines are
equivalent:
.PP
.CS
\fBsubst\fR -nobackslashes -nocommands $string
\fBsubst\fR -variables $string
.CE
.PP
It is not allowed to combine positive and negated options.
.PP
Note that the substitution of one kind can include substitution of
other kinds.  For example, even when the \fB\-novariables\fR option
is specified, command substitution is performed without restriction.
This means that any variable substitution necessary to complete the
command substitution will still take place.  Likewise, any command
substitution necessary to complete a variable substitution will
take place, even when \fB\-nocommands\fR is specified.  See the

.TH switch n 8.5 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
switch \- Evaluate one of several scripts, depending on a given value
.SH SYNOPSIS
\fBswitch \fR?\fIoptions\fR?\fI value pattern body \fR?\fIpattern body ...\fR?
.sp
\fBswitch \fR?\fIoptions\fR?\fI value \fR{\fIpattern body \fR?\fIpattern body ...\fR?}
.BE
.SH DESCRIPTION
.PP
The \fBswitch\fR command matches its \fIvalue\fR argument against each of
the \fIpattern\fR arguments in order.
As soon as it finds a \fIpattern\fR that matches \fIvalue\fR it
evaluates the following \fIbody\fR argument by passing it recursively
to the Tcl interpreter and returns the result of that evaluation.
If the last \fIpattern\fR argument is \fBdefault\fR then it matches
anything.
If no \fIpattern\fR argument
matches \fIvalue\fR and no default is given, then the \fBswitch\fR
command returns an empty string.
.PP
If the initial arguments to \fBswitch\fR start with \fB\-\fR then
they are treated as options
unless there are exactly two arguments to \fBswitch\fR (in which case the
first must the \fIvalue\fR and the second must be the
\fIpattern\fR/\fIbody\fR list).
The following options are currently supported:
.\" OPTION: -exact
.TP 10
\fB\-exact\fR
.
Use exact matching when comparing \fIvalue\fR to a pattern.  This
is the default.
.\" OPTION: -glob
.TP 10
\fB\-glob\fR
.
When matching \fIvalue\fR to the patterns, use glob-style matching
(i.e. the same as implemented by the \fBstring match\fR command).
.\" OPTION: -integer
.TP 10
\fB\-integer\fR
.VS 9.1
.\" TIP #730
When matching \fIvalue\fR to the patterns, use integer comparisons. Note
that this makes using a non-integer \fIvalue\fR or \fIpattern\fR (other
than a final \fBdefault\fR) into an error.
.VE 9.1
.\" OPTION: -regexp
.TP 10
\fB\-regexp\fR
.
When matching \fIvalue\fR to the patterns, use regular
expression matching
(as described in the \fBre_syntax\fR reference page).
.\" OPTION: -nocase
.TP 10
\fB\-nocase\fR
.
Causes comparisons to be handled in a case-insensitive manner.
Not supported with the \fB\-integer\fR option.
.\" OPTION: -matchvar
.TP 10
\fB\-matchvar\fI varName\fR
.
This option (only legal when \fB\-regexp\fR is also specified)
specifies the name of a variable into which the list of matches
found by the regular expression engine will be written.  The first
element of the list written will be the overall substring of the input
string (i.e. the \fIvalue\fR argument to \fBswitch\fR) matched, the
second element of the list will be the substring matched by the first
capturing parenthesis in the regular expression that matched, and so
on.  When a \fBdefault\fR branch is taken, the variable will have the
empty list written to it.  This option may be specified at the same
time as the \fB\-indexvar\fR option.
.\" OPTION: -indexvar
.TP 10
\fB\-indexvar\fI varName\fR
.
This option (only legal when \fB\-regexp\fR is also specified)
specifies the name of a variable into which the list of indices
referring to matching substrings
found by the regular expression engine will be written.  The first
element of the list written will be a two-element list specifying the
index of the start and index of the first character after the end of
the overall substring of the input
string (i.e. the \fIvalue\fR argument to \fBswitch\fR) matched, in a
similar way to the \fB\-indices\fR option to the \fBregexp\fR can
obtain.  Similarly, the second element of the list refers to the first
capturing parenthesis in the regular expression that matched, and so
on.  When a \fBdefault\fR branch is taken, the variable will have the
empty list written to it.  This option may be specified at the same
time as the \fB\-matchvar\fR option.
.\" OPTION: --
.TP 10
\fB\-\|\-\fR
.
Marks the end of options.  The argument following this one will
be treated as \fIvalue\fR even if it starts with a \fB\-\fR.
This is not required when the matching patterns and bodies are grouped
together in a single argument.
.PP
Two syntaxes are provided for the \fIpattern\fR and \fIbody\fR arguments.
The first uses a separate argument for each of the patterns and commands;
this form is convenient if substitutions are desired on some of the
patterns or commands.

    }
    d(e*)f(g*)h {
        puts "Found [string length [lindex $foo 1]] 'e's and\e
                [string length [lindex $foo 2]] 'g's"
    }
}
.CE
.PP
.VS 9.1
Deciding what to do with a procedure based on the number of arguments:
.PP
.CS
proc example args {
    \fBswitch\fR -integer -- [llength $args] {
        0 {
            puts "no arguments"
        }
        1 {
            puts "one argument: [lindex $args 0]"
        }
        default {
            puts "many arguments: $args"
        }
    }
}
.CE
.VE 9.1
.SH "SEE ALSO"
for(n), if(n), regexp(n)
.SH KEYWORDS
switch, match, regular expression
.\" Local Variables:
.\" mode: nroff
.\" End:

'\"
'\" Copyright (c) 1990-1994 The Regents of the University of California
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\" Copyright (c) 1998-1999 Scriptics Corporation
'\" Copyright (c) 2000 Ajuba Solutions
'\" Contributions from Don Porter, NIST, 2002. (not subject to US copyright)
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH "tcltest" n 2.6 tcltest "Tcl Bundled Packages"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
tcltest \- Test harness support code and utilities
.SH SYNOPSIS
.nf
\fBpackage require tcltest\fR ?\fB2.6\fR?

\fBtcltest::test \fIname description\fR ?\fI\-option value ...\fR?
\fBtcltest::test \fIname description\fR ?\fIconstraints\fR? \fIbody result\fR

\fBtcltest::loadTestedCommands\fR
\fBtcltest::makeDirectory \fIname\fR ?\fIdirectory\fR?
\fBtcltest::removeDirectory \fIname\fR ?\fIdirectory\fR?

\fBtcltest::outputFile \fR?\fIfilename\fR?
\fBtcltest::preserveCore \fR?\fIlevel\fR?
\fBtcltest::singleProcess \fR?\fIboolean\fR?
\fBtcltest::skip \fR?\fIpatternList\fR?
\fBtcltest::skipDirectories \fR?\fIpatternList\fR?
\fBtcltest::skipFiles \fR?\fIpatternList\fR?
\fBtcltest::temporaryDirectory \fR?\fIdirectory\fR?
\fBtcltest::testIterations \fR?\fIcount\fR?
\fBtcltest::testsDirectory \fR?\fIdirectory\fR?
\fBtcltest::verbose \fR?\fIlevel\fR?

\fBtcltest::test \fIname description optionList\fR
\fBtcltest::normalizeMsg \fImsg\fR
\fBtcltest::normalizePath \fIpathVar\fR
\fBtcltest::workingDirectory \fR?\fIdir\fR?

.QW "\fBconfigure \-notfile\fR ?\fIpatternList\fR?" .
.\" COMMAND: temporaryDirectory
.TP
\fBtemporaryDirectory\fR ?\fIdirectory\fR?
.
Same as
.QW "\fBconfigure \-tmpdir\fR ?\fIdirectory\fR?" .
.\" COMMAND: testIterations
.TP
\fBtestIterations\fR ?\fIcount\fR?
.
Same as
.QW "\fBconfigure \-iterations\fR ?\fIcount\fR?" .
.\" COMMAND: testsDirectory
.TP
\fBtestsDirectory\fR ?\fIdirectory\fR?
.
Same as
.QW "\fBconfigure \-testdir\fR ?\fIdirectory\fR?" .
.\" COMMAND: verbose

.TP
\fB\-errfile \fIfilename\fR
.
Sets the file to which all error output produced by tcltest
should be written.  A file named \fIfilename\fR will be \fBopen\fRed
for writing, and the resulting channel will be set as the value
of \fBerrorChannel\fR.
.\" OPTION: -iterations
.TP
\fB\-iterations \fIcount\fR
.
Sets the number of times each test is executed. Default value is \fB1\fR.
.SH "CREATING TEST SUITES WITH TCLTEST"
.PP
The fundamental element of a test suite is the individual \fBtest\fR
command.  We begin with several examples.
.IP [1]
Test of a script that returns normally.
.RS

After all \fBtest\fRs in a test file, the command \fBcleanupTests\fR
should be called.
.IP [7]
Here is a sketch of a sample test file illustrating those points:
.RS
.PP
.CS
\fBpackage require tcltest 2.6\fR
\fB::tcltest::configure\fR {*}$::argv
\fBpackage require example\fR
namespace eval ::example::test {
    namespace import ::tcltest::*
    \fBtestConstraint\fR X [expr {...}]
    variable SETUP {#common setup code}
    variable CLEANUP {#common cleanup code}

because that is the default name used by \fBrunAllTests\fR when combining
multiple test suites into one testing run.
.IP [8]
Here is a sketch of a sample test suite main script:
.RS
.PP
.CS
\fBpackage require tcltest 2.6\fR
\fBpackage require example\fR
\fB::tcltest::configure\fR -testdir \e
        [file dirname [file normalize [info script]]]
\fB::tcltest::configure\fR {*}$::argv
\fB::tcltest::runAllTests\fR
.CE
.RE

'\"
'\" Copyright (c) 1993 The Regents of the University of California.
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH tclvars n 9.1 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
argc, argv, argv0, auto_path, env, errorCode, errorInfo, tcl_interactive, tcl_library, tcl_patchLevel, tcl_pkgPath, tcl_platform, tcl_rcFileName, tcl_traceCompile, tcl_traceExec, tcl_version \- Variables used by Tcl
.BE
.SH DESCRIPTION

Its contents take the form of a stack trace showing the various
nested Tcl commands that had been invoked at the time of the error.
.\" VARIABLE: tcl_library
.TP
\fBtcl_library\fR
.
This variable holds the name of a directory containing the
system library of Tcl scripts and encodings.
The value of this variable is returned by the \fBinfo library\fR command.
See the \fBlibrary\fR manual entry for details of the facilities
provided by the Tcl script library.
Normally each application or package will have its own application-specific
script library in addition to the Tcl script library;
each application should set a global variable with a name like
\fB$\fIapp\fB_library\fR (where \fIapp\fR is the application's name)
to hold the network file name for that application's library directory.
The initial value of \fBtcl_library\fR is set when an interpreter
is created by searching several different directories until one is
found that contains an appropriate Tcl startup script. If an
application has already set the \fBtcl_library\fR variable in
the interpreter, it is used directly. Otherwise,
if the \fBTCL_LIBRARY\fR environment variable exists, then
the directory it names is used to initialize \fBtcl_library\fR.
In both cases, no further directories are searched. If neither

of the above is set, Tcl will search several other directories
in the following order: the ZipFS archive attached to the application
or shared library for ZipFS-enabled builds, a platform specific default
directory, the directory configured at build time, the directory
\fBlib/tcl\fIVERSION\fR under the parent directory of the directory
containing the application executable.
.\" VARIABLE: tcl_patchLevel
.TP
\fBtcl_patchLevel\fR
.
When an interpreter is created Tcl initializes this variable to
hold a string giving the current patch level for Tcl, such as
\fB8.4.16\fR for Tcl 8.4 with the first sixteen official patches, or

'\"
'\" Copyright (c) 2025 The TCL Association
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH timer n 9.1 Tcl "Tcl Built-In Commands"
.so man.macros
.BS
'\" Note:  do not modify the .SH NAME line immediately below!
.SH NAME
timer \- timer events for monotonic and wall clock time
.SH SYNOPSIS
.nf
\fBtimer in\fR \fIdelay\fR \fIunit\fR \fIscript\fR
\fBtimer at\fR \fItimepoint\fR \fIunit\fR \fIscript\fR
\fBtimer idle\fR \fIscript\fR
\fBtimer sleep for\fR \fIdelay\fR ?\fIunit\fR?
\fBtimer sleep until\fR \fItimepoint\fR ?\fIunit\fR?
\fBtimer cancel\fR \fIid\fR
\fBtimer info\fR ?\fIid\fR?
.fi
.BE
.SH DESCRIPTION
.PP
This command is used to delay execution of the program or to execute
a command in background sometime in the future.
Time may be specified by a monotonic time delay or by wall clock time point.
It has the following methods:
.\" METHOD: in
.TP
\fBtimer in\fR \fIdelay\fR \fIunit\fR \fIscript\fR
.
In this form the command returns immediately, but it arranges
for a Tcl command to be executed after the given monotonic time \fIdelay\fR elapsed as an
event handler.
The \fIdelay\fR value is given in the specified \fIunit\fR.
See \fBTIME UNITS\fR below for available units.
The command will be executed exactly once, after the given time delay.
The delayed command is given by the argument \fIscript\fR.
The command will be executed at global level (outside the context
of any Tcl procedure).
If an error occurs while executing the delayed command then
the background error will be reported by the command
registered with \fBinterp bgerror\fR.
The command returns an identifier that can be used
to cancel the delayed command using \fBtimer cancel\fR or \fBafter cancel\fR.
A \fIdelay\fR value of 0 (or negative) queues the event immediately with
priority over other event types (if not installed with an event proc,
which will wait for next round of events).
.TP
The command \fBafter ms script\fR may also be used to register monotonic clock timer events.
Theey are handled by the same que as this form of the \fBtimer\fR command.
.\" METHOD: at
.TP
\fBtimer at \fItimepoint\fR \fIunit\fR \fIscript\fR
.
Same as \fBtimer in\fR, but specifying a wall clock time point (epoc).
A typical use-case is to pass result of a \fBclock scan\fR as time point.
See example below.
.TP
Wall clock events have second priority after monotonic clock events.
If both fire the same instant, the monotonic clock command is always handled first.
.\" METHOD: idle
.TP
\fBtimer idle \fIscript\fR
.
Arranges for the \fIscript\fR to be evaluated later as an idle callback.
The script will be run exactly once, the next time the event
loop is entered and there are no events to process.
The command returns an identifier that can be used
to cancel the delayed command using \fBtimer cancel\fR or \fBafter cancel\fR.
If an error occurs while executing the script then the
background error will be reported by the command
registered with \fBinterp bgerror\fR.
.\" METHOD: wait for
.TP
\fBtimer wait for \fIdelay\fR ?\fIunit\fR?
\fIdelay\fR must be a wide integer giving a time in the given unit (default: \fBmilliseconds\fR).
A negative number is treated as 0.
The command sleeps for the given monotonic delay and then returns.
While the command is sleeping the application does not respond to
events.
.\" METHOD: wait until
.TP
\fBtimer wait until \fItimepoint\fR ?\fIunit\fR?
\fItimepoint\fR must be a wide integer giving a wall clock time point in the given unit (default: \fBseconds\fR).
A negative number is treated as 0.
The command sleeps (at least) until the given wall clock time point and then returns.
While the command is sleeping the application does not respond to
events.
.\" METHOD: cancel
.TP
\fBafter cancel \fIid\fR
.
Cancels the execution of a delayed command that
was previously scheduled.
\fIId\fR indicates which command should be canceled;  it must have
been the return value from a previous \fBtimer\fR or \fBafter\fR command.
If the command given by \fIid\fR has already been executed then
the \fBtimer cancel\fR command has no effect.
.\" METHOD: info
.TP
\fBtimer info \fR?\fIid\fR?
.
This command returns information about existing event handlers.
If no \fIid\fR argument is supplied, the command returns
a list of the identifiers for all existing
event handlers created by the \fBtimer\fR and \fBafter\fR command for this
interpreter.
If \fIid\fR is supplied, it specifies an existing handler;
\fIid\fR must have been the return value from some previous call
to \fBtimer\fR or \fBafter\fR and it must not have triggered yet or been canceled.
In this case the command returns a list with two to three elements.
The first element of the list is the script associated
with \fIid\fR, and the second element is either
\fBidle\fR, \fBmonotonic\fR or \fBwallclock\fR to indicate what kind of event
handler it is.
A thierd list element is present for the kinds \fB monotonic\fR or \fBwallclock\fR.
This element is the scheduled execution time point in microseconds of the given clock type.
.LP
The \fBtimer in\fR, \fBtimer at\fR and \fBtimer idle\fR forms of the command
assume that the application is event driven:  the delayed commands
will not be executed unless the application enters the event loop.
In applications that are not normally event-driven, such as
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
and \fBupdate\fR commands.
.LP
Note, that the output differs from \fBafter info\fR.
.SH "TIME UNITS"
Some forms of the command take a time unit.
Available units are: \fBus\fR (for microseconds), \fBmicroseconds\fR,
\fBms\fR (for milliseconds), \fBmilliseconds\fR,
\fBs\fR (for seconds), \fBseconds\fR or any unique abbreviation.
.SH "TIME MAXIMUM VALUE"
The arguments \fIdelay\fR and \fItimepoint\fR are bound to a resulting 63 bit clock value
(in unit microseconds).
Any higher value (which is after year 294441) will result in a \fBtime to far\fR error.
.SH "EXAMPLES"
This arranges for the command \fIwake_up\fR to be run in eight hours
wall clock time (providing the event loop is active at that time):
.PP
.CS
\fBtime at\fR [\fBclock add\fR [\fBclock seconds\fR] 24 hours] seconds wake_up
.CE
.PP
.SH "SEE ALSO"
concat(n), interp(n), timer(n), update(n), vwait(n)
.SH KEYWORDS
cancel, delay, idle callback, sleep, time
'\" Local Variables:
'\" mode: nroff
'\" End:

'\"
'\" Copyright (c) 2025 Ashok P. Nadkarni.
'\"
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
.TH unicode n "9.1" Tcl "Tcl Built-In Commands"
.so man.macros
.BS
.SH NAME
unicode \- Unicode character transforms
.SH SYNOPSIS
\fBunicode \fIfunction\fR ?\fIoptions\fR? \fIstring\fR
.BE
.SH DESCRIPTION
.PP
The command performs one of several Unicode character transformations, depending on
\fIfunction\fR which may take the values described below.
.\" METHOD: tonfc
.VS "TIP726"
.TP
\fBunicode tonfc\fR ?\fB-profile\fR \fIprofile\fR? \fIstring\fR
.VE "TIP726"
.
Returns \fIstring\fR normalized as per Unicode \fBNormalization Form C\fR (NFC).
.PP
.\" METHOD: tonfd
.VS "TIP726"
.TP
\fBunicode tonfd\fR ?\fB-profile\fR \fIprofile\fR? \fIstring\fR
.VE "TIP726"
.
Returns \fIstring\fR normalized as per Unicode \fBNormalization Form D\fR (NFD).
.PP
.\" METHOD: tonfkc
.VS "TIP726"
.TP
\fBunicode tonfkc\fR ?\fB-profile\fR \fIprofile\fR? \fIstring\fR
.VE "TIP726"
.
Returns \fIstring\fR normalized as per Unicode \fBNormalization Form KC\fR (NFKC).
.PP
.\" METHOD: tonfkd
.VS "TIP726"
.TP
\fBunicode tonfkd\fR ?\fB-profile\fR \fIprofile\fR? \fIstring\fR
.VE "TIP726"
.
Returns \fIstring\fR normalized as per Unicode \fBNormalization Form KD\fR (NFKD).
.PP
The normalization forms NFC, NFD, NFKC and NFKD referenced above are defined
in \fBSection 3.11\fR of the Unicode standard
(see https://www.unicode.org/versions/Unicode16.0.0/core-spec/chapter-3/).
.PP
The \fB-profile\fR option determines the command behavior in the presence
of conversion errors. The passed profile must be \fBstrict\fR or \fBreplace\fR.
See the \fBPROFILES\fR section in the documentation
of the \fBencoding\fR command for details on profiles.
.PP
.SH "SEE ALSO"
Tcl_UtfToNormalized(3)
.SH KEYWORDS
Unicode, normalize
.\" Local Variables:
.\" mode: nroff
.\" End:

.br
\fBunload \fR?\fIswitches\fR? \fIfileName prefix interp\fR
.BE
.SH DESCRIPTION
.PP
This command tries to unload shared libraries previously loaded
with \fBload\fR from the application's address space.  \fIfileName\fR
is the name of the file containing the library file unload;  it
must be the same as the filename provided to \fBload\fR for
loading the library.
The \fIprefix\fR argument is the prefix (as
determined by or passed to \fBload\fR), and is used to
compute the name of the unload procedure; if not supplied, it is
computed from \fIfileName\fR in the same manner as \fBload\fR.
The \fIinterp\fR argument is the path name of the interpreter from

or \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR. In case the library will remain
attached to the process after the unload procedure returns (i.e. because
the library is used by other interpreters),
\fBTCL_UNLOAD_DETACH_FROM_INTERPRETER\fR will be defined. However, if the
library is used only by the target interpreter and the library will be
detached from the application as soon as the unload procedure returns,
the \fIflags\fR argument will be set to \fBTCL_UNLOAD_DETACH_FROM_PROCESS\fR.
.PP
The unload procedure must take care to delete any commands it owns, rescind
callbacks or event handler, and free all resources such as file handles, memory,
TSD storage.
.SS NOTES
.PP
The \fBunload\fR command cannot unload libraries that are statically
linked with the application.
If \fIfileName\fR is an empty string, then the \fIprefix\fR argument must
be specified.
.PP

\fIChannel\fR must name a Tcl channel open for reading. If \fIchannel\fR
is or becomes readable the wait operation completes.
.\" OPTION: -timeout
.TP
\fB\-timeout\fI milliseconds\fR
.
The wait operation is constrained to \fImilliseconds\fR.
A monotonic clock is used if available.
.\" OPTION: -variable
.TP
\fB\-variable\fI varName\fR
.
\fIVarName\fR must be the name of a global variable. Writing or
unsetting this variable completes the wait operation.
.\" OPTION: -writable

.AP int copy in
If non-zero, the ZIP archive in the data buffer will be internally copied
before mounting, allowing the data buffer to be disposed once
\fBTclZipfs_MountBuffer\fR returns. If zero, the caller guarantees that the
buffer will be valid to read from for the duration of the mount.
.BE
.SH DESCRIPTION
\fBTclZipfs_AppHook\fR performs all functions required to initialize Tcl
for use in an application, taking into account available ZIP archives as
follows:
.IP [1]
If the current application executable has a mountable ZIP archive, that archive
is mounted under \fIZIPFS_VOLUME\fB/app\fR as a read-only Tcl virtual file
system (VFS). If the Tcl shared library has a mountable ZIP archive, that
archive mounted under \fIZIPFS_VOLUME\fB/lib/tcl\fR as a read-only Tcl VFS. The
value of \fIZIPFS_VOLUME\fR can be retrieved using the Tcl command \fBzipfs
root\fR. Both are included in the search path for locating Tcl support scripts as
described in the \fBtcl_library\fR global variable documentation.
.IP [2]
If a file named \fBmain.tcl\fR is located in the root directory of that file
system (i.e., at \fIZIPFS_VOLUME\fB/app/main.tcl\fR after the ZIP archive is
mounted as described above) it is treated as the startup script for the
process.












.PP
On Windows, \fBTclZipfs_AppHook\fR has a slightly different signature, since
it uses WCHAR instead of char. As a result, it requires the application to
be compiled with the UNICODE preprocessor symbol defined (e.g., via the
\fB\-DUNICODE\fR compiler flag).
.PP
The result of \fBTclZipfs_AppHook\fR is the full Tcl version with build

    pcolor co)
{
    color sco;			/* new subcolor */

    sco = cm->cd[co].sub;
    if (sco == NOSUB) {		/* color has no open subcolor */
	if (cm->cd[co].nchrs == 1) {	/* optimization */
	    return (color)co;
	}
	sco = newcolor(cm);	/* must create subcolor */
	if (sco == COLORLESS) {
	    assert(CISERR());
	    return COLORLESS;
	}
	cm->cd[co].sub = sco;

    {0x19B0, 0x19C9}, {0x1A00, 0x1A16}, {0x1A20, 0x1A54}, {0x1B05, 0x1B33},
    {0x1B45, 0x1B4C}, {0x1B83, 0x1BA0}, {0x1BBA, 0x1BE5}, {0x1C00, 0x1C23},
    {0x1C4D, 0x1C4F}, {0x1C5A, 0x1C7D}, {0x1C80, 0x1C8A}, {0x1C90, 0x1CBA},
    {0x1CBD, 0x1CBF}, {0x1CE9, 0x1CEC}, {0x1CEE, 0x1CF3}, {0x1D00, 0x1DBF},
    {0x1E00, 0x1F15}, {0x1F18, 0x1F1D}, {0x1F20, 0x1F45}, {0x1F48, 0x1F4D},
    {0x1F50, 0x1F57}, {0x1F5F, 0x1F7D}, {0x1F80, 0x1FB4}, {0x1FB6, 0x1FBC},
    {0x1FC2, 0x1FC4}, {0x1FC6, 0x1FCC}, {0x1FD0, 0x1FD3}, {0x1FD6, 0x1FDB},
    {0x1FE0, 0x1FEC}, {0x1FF2, 0x1FF4}, {0x1FF6, 0x1FFC}, {0x208F, 0x209F},
    {0x210A, 0x2113}, {0x2119, 0x211D}, {0x212A, 0x212D}, {0x212F, 0x2139},
    {0x213C, 0x213F}, {0x2145, 0x2149}, {0x2C00, 0x2CE4}, {0x2CEB, 0x2CEE},
    {0x2D00, 0x2D25}, {0x2D30, 0x2D67}, {0x2D80, 0x2D96}, {0x2DA0, 0x2DA6},
    {0x2DA8, 0x2DAE}, {0x2DB0, 0x2DB6}, {0x2DB8, 0x2DBE}, {0x2DC0, 0x2DC6},
    {0x2DC8, 0x2DCE}, {0x2DD0, 0x2DD6}, {0x2DD8, 0x2DDE}, {0x3031, 0x3035},
    {0x3041, 0x3096}, {0x309D, 0x309F}, {0x30A1, 0x30FA}, {0x30FC, 0x30FF},
    {0x3105, 0x312F}, {0x3131, 0x318E}, {0x31A0, 0x31BF}, {0x31F0, 0x31FF},
    {0x3400, 0x4DBF}, {0x4E00, 0xA48C}, {0xA4D0, 0xA4FD}, {0xA500, 0xA60C},
    {0xA610, 0xA61F}, {0xA640, 0xA66E}, {0xA67F, 0xA69D}, {0xA6A0, 0xA6E5},
    {0xA717, 0xA71F}, {0xA722, 0xA788}, {0xA78B, 0xA7DD}, {0xA7F1, 0xA801},
    {0xA803, 0xA805}, {0xA807, 0xA80A}, {0xA80C, 0xA822}, {0xA840, 0xA873},
    {0xA882, 0xA8B3}, {0xA8F2, 0xA8F7}, {0xA90A, 0xA925}, {0xA930, 0xA946},
    {0xA960, 0xA97C}, {0xA984, 0xA9B2}, {0xA9E0, 0xA9E4}, {0xA9E6, 0xA9EF},
    {0xA9FA, 0xA9FE}, {0xAA00, 0xAA28}, {0xAA40, 0xAA42}, {0xAA44, 0xAA4B},
    {0xAA60, 0xAA76}, {0xAA7E, 0xAAAF}, {0xAAB9, 0xAABD}, {0xAADB, 0xAADD},
    {0xAAE0, 0xAAEA}, {0xAAF2, 0xAAF4}, {0xAB01, 0xAB06}, {0xAB09, 0xAB0E},
    {0xAB11, 0xAB16}, {0xAB20, 0xAB26}, {0xAB28, 0xAB2E}, {0xAB30, 0xAB5A},

    {0x10050, 0x1005D}, {0x10080, 0x100FA}, {0x10280, 0x1029C}, {0x102A0, 0x102D0},
    {0x10300, 0x1031F}, {0x1032D, 0x10340}, {0x10342, 0x10349}, {0x10350, 0x10375},
    {0x10380, 0x1039D}, {0x103A0, 0x103C3}, {0x103C8, 0x103CF}, {0x10400, 0x1049D},
    {0x104B0, 0x104D3}, {0x104D8, 0x104FB}, {0x10500, 0x10527}, {0x10530, 0x10563},
    {0x10570, 0x1057A}, {0x1057C, 0x1058A}, {0x1058C, 0x10592}, {0x10597, 0x105A1},
    {0x105A3, 0x105B1}, {0x105B3, 0x105B9}, {0x105C0, 0x105F3}, {0x10600, 0x10736},
    {0x10740, 0x10755}, {0x10760, 0x10767}, {0x10780, 0x10785}, {0x10787, 0x107B0},
    {0x107B2, 0x107BF}, {0x10800, 0x10805}, {0x1080A, 0x10835}, {0x1083F, 0x10855},
    {0x10860, 0x10876}, {0x10880, 0x1089E}, {0x108E0, 0x108F2}, {0x10900, 0x10915},
    {0x10920, 0x10939}, {0x10940, 0x10959}, {0x10980, 0x109B7}, {0x10A10, 0x10A13},
    {0x10A15, 0x10A17}, {0x10A19, 0x10A35}, {0x10A60, 0x10A7C}, {0x10A80, 0x10A9C},
    {0x10AC0, 0x10AC7}, {0x10AC9, 0x10AE4}, {0x10B00, 0x10B35}, {0x10B40, 0x10B55},
    {0x10B60, 0x10B72}, {0x10B80, 0x10B91}, {0x10C00, 0x10C48}, {0x10C80, 0x10CB2},
    {0x10CC0, 0x10CF2}, {0x10D00, 0x10D23}, {0x10D4A, 0x10D65}, {0x10D6F, 0x10D85},
    {0x10E80, 0x10EA9}, {0x10EC2, 0x10EC7}, {0x10ED9, 0x10EEE}, {0x10F00, 0x10F1C},
    {0x10F30, 0x10F45}, {0x10F70, 0x10F81}, {0x10FB0, 0x10FC4}, {0x10FE0, 0x10FF6},
    {0x11003, 0x11037}, {0x11083, 0x110AF}, {0x110D0, 0x110E8}, {0x11103, 0x11126},
    {0x11150, 0x11172}, {0x11183, 0x111B2}, {0x111C1, 0x111C4}, {0x11200, 0x11211},
    {0x11213, 0x1122B}, {0x11280, 0x11286}, {0x1128A, 0x1128D}, {0x1128F, 0x1129D},
    {0x1129F, 0x112A8}, {0x112B0, 0x112DE}, {0x11305, 0x1130C}, {0x11313, 0x11328},
    {0x1132A, 0x11330}, {0x11335, 0x11339}, {0x1135D, 0x11361}, {0x11380, 0x11389},
    {0x11390, 0x113B5}, {0x11400, 0x11434}, {0x11447, 0x1144A}, {0x1145F, 0x11461},
    {0x11480, 0x114AF}, {0x11580, 0x115AE}, {0x115D8, 0x115DB}, {0x11600, 0x1162F},
    {0x11680, 0x116AA}, {0x11700, 0x1171A}, {0x11740, 0x11746}, {0x11800, 0x1182B},
    {0x118A0, 0x118DF}, {0x118FF, 0x11906}, {0x1190C, 0x11913}, {0x11918, 0x1192F},
    {0x119A0, 0x119A7}, {0x119AA, 0x119D0}, {0x11A0B, 0x11A32}, {0x11A5C, 0x11A89},
    {0x11AB0, 0x11AF8}, {0x11BC0, 0x11BE0}, {0x11C00, 0x11C08}, {0x11C0A, 0x11C2E},
    {0x11C72, 0x11C8F}, {0x11D00, 0x11D06}, {0x11D0B, 0x11D30}, {0x11D60, 0x11D65},
    {0x11D6A, 0x11D89}, {0x11DB0, 0x11DDB}, {0x11EE0, 0x11EF2}, {0x11F04, 0x11F10},
    {0x11F12, 0x11F33}, {0x12000, 0x12399}, {0x12480, 0x12543}, {0x12F90, 0x12FF0},
    {0x13000, 0x1342F}, {0x13441, 0x13446}, {0x13460, 0x143FA}, {0x14400, 0x14646},
    {0x16100, 0x1611D}, {0x16800, 0x16A38}, {0x16A40, 0x16A5E}, {0x16A70, 0x16ABE},
    {0x16AD0, 0x16AED}, {0x16B00, 0x16B2F}, {0x16B40, 0x16B43}, {0x16B63, 0x16B77},
    {0x16B7D, 0x16B8F}, {0x16D40, 0x16D6C}, {0x16D80, 0x16D97}, {0x16D99, 0x16D9C},
    {0x16E40, 0x16E7F}, {0x16EA0, 0x16EB8}, {0x16EBB, 0x16ED3}, {0x16F00, 0x16F4A},
    {0x16F93, 0x16F9F}, {0x17000, 0x18CDA}, {0x18CFF, 0x18D20}, {0x18D80, 0x18DF2},
    {0x18E00, 0x19191}, {0x191A0, 0x191D2}, {0x1AFF0, 0x1AFF3}, {0x1AFF5, 0x1AFFB},
    {0x1B000, 0x1B128}, {0x1B150, 0x1B152}, {0x1B164, 0x1B168}, {0x1B170, 0x1B2FB},
    {0x1BC00, 0x1BC6A}, {0x1BC70, 0x1BC7C}, {0x1BC80, 0x1BC88}, {0x1BC90, 0x1BC99},
    {0x1D400, 0x1D454}, {0x1D456, 0x1D49C}, {0x1D4A9, 0x1D4AC}, {0x1D4AE, 0x1D4B9},
    {0x1D4BD, 0x1D4C3}, {0x1D4C5, 0x1D505}, {0x1D507, 0x1D50A}, {0x1D50D, 0x1D514},
    {0x1D516, 0x1D51C}, {0x1D51E, 0x1D539}, {0x1D53B, 0x1D53E}, {0x1D540, 0x1D544},
    {0x1D54A, 0x1D550}, {0x1D552, 0x1D6A6}, {0x1D6A8, 0x1D6C0}, {0x1D6C2, 0x1D6DA},
    {0x1D6DC, 0x1D6FA}, {0x1D6FC, 0x1D714}, {0x1D716, 0x1D734}, {0x1D736, 0x1D74E},
    {0x1D750, 0x1D76E}, {0x1D770, 0x1D788}, {0x1D78A, 0x1D7A8}, {0x1D7AA, 0x1D7C2},
    {0x1D7C4, 0x1D7CB}, {0x1DF00, 0x1DF81}, {0x1DF90, 0x1DF96}, {0x1DFCD, 0x1DFFF},
    {0x1E030, 0x1E06D}, {0x1E100, 0x1E12C}, {0x1E137, 0x1E13D}, {0x1E290, 0x1E2AD},
    {0x1E2C0, 0x1E2EB}, {0x1E4D0, 0x1E4EB}, {0x1E5D0, 0x1E5ED}, {0x1E6C0, 0x1E6DE},
    {0x1E6E0, 0x1E6E2}, {0x1E6E7, 0x1E6ED}, {0x1E6F0, 0x1E6F4}, {0x1E7E0, 0x1E7E6},
    {0x1E7E8, 0x1E7EB}, {0x1E7F0, 0x1E7FE}, {0x1E800, 0x1E8C4}, {0x1E900, 0x1E943},
    {0x1EE00, 0x1EE03}, {0x1EE05, 0x1EE1F}, {0x1EE29, 0x1EE32}, {0x1EE34, 0x1EE37},
    {0x1EE4D, 0x1EE4F}, {0x1EE67, 0x1EE6A}, {0x1EE6C, 0x1EE72}, {0x1EE74, 0x1EE77},
    {0x1EE79, 0x1EE7C}, {0x1EE80, 0x1EE89}, {0x1EE8B, 0x1EE9B}, {0x1EEA1, 0x1EEA3},
    {0x1EEA5, 0x1EEA9}, {0x1EEAB, 0x1EEBB}, {0x20000, 0x2A6DF}, {0x2A700, 0x2B81E},
    {0x2B820, 0x2CEAD}, {0x2CEB0, 0x2EBE0}, {0x2EBF0, 0x2EE5D}, {0x2F800, 0x2FA1D},
    {0x30000, 0x3134A}, {0x31350, 0x33479}, {0x3D000, 0x3FC3F}
#endif
};

#define NUM_ALPHA_RANGE ((int)(sizeof(alphaRangeTable)/sizeof(crange)))

static const chr alphaCharTable[] = {
    0xAA, 0xB5, 0xBA, 0x2EC, 0x2EE, 0x376, 0x377, 0x37F, 0x386,
    0x38C, 0x558, 0x559, 0x58B, 0x58C, 0x66E, 0x66F, 0x6D5, 0x6E5,
    0x6E6, 0x6EE, 0x6EF, 0x6FF, 0x710, 0x7B1, 0x7F4, 0x7F5, 0x7FA,
    0x81A, 0x824, 0x828, 0x93D, 0x950, 0x98F, 0x990, 0x9B2, 0x9BD,
    0x9CE, 0x9DC, 0x9DD, 0x9F0, 0x9F1, 0x9FC, 0xA0F, 0xA10, 0xA32,
    0xA33, 0xA35, 0xA36, 0xA38, 0xA39, 0xA5E, 0xAB2, 0xAB3, 0xABD,
    0xAD0, 0xAE0, 0xAE1, 0xAF9, 0xB0F, 0xB10, 0xB32, 0xB33, 0xB3D,
    0xB5C, 0xB5D, 0xB71, 0xB83, 0xB99, 0xB9A, 0xB9C, 0xB9E, 0xB9F,
    0xBA3, 0xBA4, 0xBD0, 0xC3D, 0xC5C, 0xC5D, 0xC60, 0xC61, 0xC80,
    0xCBD, 0xCE0, 0xCE1, 0xCF1, 0xCF2, 0xD3D, 0xD4E, 0xDBD, 0xE32,
    0xE33, 0xE81, 0xE82, 0xE84, 0xEA5, 0xEB2, 0xEB3, 0xEBD, 0xEC6,
    0xF00, 0x103F, 0x1061, 0x1065, 0x1066, 0x108E, 0x10C7, 0x10CD, 0x1258,
    0x12C0, 0x17D7, 0x17DC, 0x18AA, 0x1AA7, 0x1BAE, 0x1BAF, 0x1CF5, 0x1CF6,
    0x1CFA, 0x1F59, 0x1F5B, 0x1F5D, 0x1FBE, 0x2071, 0x207F, 0x2102, 0x2107,
    0x2115, 0x2124, 0x2126, 0x2128, 0x214E, 0x2183, 0x2184, 0x2CF2, 0x2CF3,
    0x2D27, 0x2D2D, 0x2D6F, 0x2E2F, 0x3005, 0x3006, 0x303B, 0x303C, 0xA62A,
    0xA62B, 0xA7E2, 0xA8FB, 0xA8FD, 0xA8FE, 0xA9CF, 0xAA7A, 0xAAB1, 0xAAB5,
    0xAAB6, 0xAAC0, 0xAAC2, 0xAB6C, 0xAB6D, 0xFB1D, 0xFB3E, 0xFB40, 0xFB41,
    0xFB43, 0xFB44
#if CHRBITS > 16
    ,0x1003C, 0x1003D, 0x10594, 0x10595, 0x105BB, 0x105BC, 0x10808, 0x10837, 0x10838,
    0x1083C, 0x108F4, 0x108F5, 0x109BE, 0x109BF, 0x10A00, 0x10EB0, 0x10EB1, 0x10F27,
    0x11071, 0x11072, 0x11075, 0x11144, 0x11147, 0x11176, 0x111DA, 0x111DC, 0x1123F,
    0x11240, 0x11288, 0x1130F, 0x11310, 0x11332, 0x11333, 0x1133D, 0x11350, 0x1138B,
    0x1138E, 0x113B7, 0x113D1, 0x113D3, 0x114C4, 0x114C5, 0x114C7, 0x11644, 0x116B8,
    0x11909, 0x11915, 0x11916, 0x1193F, 0x11941, 0x119E1, 0x119E3, 0x11A00, 0x11A3A,
    0x11A50, 0x11A9D, 0x11B0A, 0x11C40, 0x11D08, 0x11D09, 0x11D46, 0x11D67, 0x11D68,
    0x11D98, 0x11DF1, 0x11F02, 0x11FB0, 0x16F50, 0x16FE0, 0x16FE1, 0x16FE3, 0x16FF2,
    0x16FF3, 0x1AFFD, 0x1AFFE, 0x1B132, 0x1B155, 0x1D49E, 0x1D49F, 0x1D4A2, 0x1D4A5,
    0x1D4A6, 0x1D4BB, 0x1D546, 0x1E14E, 0x1E5F0, 0x1E6E4, 0x1E6E5, 0x1E6FE, 0x1E6FF,
    0x1E7ED, 0x1E7EE, 0x1E94B, 0x1EE21, 0x1EE22, 0x1EE24, 0x1EE27, 0x1EE39, 0x1EE3B,
    0x1EE42, 0x1EE47, 0x1EE49, 0x1EE4B, 0x1EE51, 0x1EE52, 0x1EE54, 0x1EE57, 0x1EE59,
    0x1EE5B, 0x1EE5D, 0x1EE5F, 0x1EE61, 0x1EE62, 0x1EE64, 0x1EE7E
#endif
};

#define NUM_ALPHA_CHAR ((int)(sizeof(alphaCharTable)/sizeof(chr)))

/*
 * Unicode: control characters.

#if CHRBITS > 16
    ,{0x104A0, 0x104A9}, {0x10D30, 0x10D39}, {0x10D40, 0x10D49}, {0x11066, 0x1106F},
    {0x110F0, 0x110F9}, {0x11136, 0x1113F}, {0x111D0, 0x111D9}, {0x112F0, 0x112F9},
    {0x11450, 0x11459}, {0x114D0, 0x114D9}, {0x11650, 0x11659}, {0x116C0, 0x116C9},
    {0x116D0, 0x116E3}, {0x11730, 0x11739}, {0x118E0, 0x118E9}, {0x11950, 0x11959},
    {0x11BF0, 0x11BF9}, {0x11C50, 0x11C59}, {0x11D50, 0x11D59}, {0x11DA0, 0x11DA9},
    {0x11DE0, 0x11DE9}, {0x11F50, 0x11F59}, {0x16130, 0x16139}, {0x16A60, 0x16A69},
    {0x16AC0, 0x16AC9}, {0x16B50, 0x16B59}, {0x16D70, 0x16D79}, {0x16DA0, 0x16DA9},
    {0x1CCF0, 0x1CCF9}, {0x1D7CE, 0x1D7FF}, {0x1E140, 0x1E149}, {0x1E2F0, 0x1E2F9},
    {0x1E4F0, 0x1E4F9}, {0x1E5F1, 0x1E5FA}, {0x1E950, 0x1E959}, {0x1FBF0, 0x1FBF9}
#endif
};

#define NUM_DIGIT_RANGE ((int)(sizeof(digitRangeTable)/sizeof(crange)))

/*
 * no singletons of digit characters.

    {0x7F7, 0x7F9}, {0x830, 0x83E}, {0xF04, 0xF12}, {0xF3A, 0xF3D},
    {0xFD0, 0xFD4}, {0x104A, 0x104F}, {0x1360, 0x1368}, {0x16EB, 0x16ED},
    {0x17D4, 0x17D6}, {0x17D8, 0x17DA}, {0x1800, 0x180A}, {0x1AA0, 0x1AA6},
    {0x1AA8, 0x1AAD}, {0x1B5A, 0x1B60}, {0x1B7D, 0x1B7F}, {0x1BFC, 0x1BFF},
    {0x1C3B, 0x1C3F}, {0x1CC0, 0x1CC7}, {0x2010, 0x2027}, {0x2030, 0x2043},
    {0x2045, 0x2051}, {0x2053, 0x205E}, {0x2308, 0x230B}, {0x2768, 0x2775},
    {0x27E6, 0x27EF}, {0x2983, 0x2998}, {0x29D8, 0x29DB}, {0x2CF9, 0x2CFC},
    {0x2E00, 0x2E2E}, {0x2E30, 0x2E4F}, {0x2E52, 0x2E5D}, {0x2E60, 0x2E63},
    {0x3001, 0x3003}, {0x3008, 0x3011}, {0x3014, 0x301F}, {0xA60D, 0xA60F},
    {0xA6F2, 0xA6F7}, {0xA874, 0xA877}, {0xA8F8, 0xA8FA}, {0xA9C1, 0xA9CD},
    {0xAA5C, 0xAA5F}, {0xFE10, 0xFE19}, {0xFE30, 0xFE52}, {0xFE54, 0xFE61},
    {0xFF01, 0xFF03}, {0xFF05, 0xFF0A}, {0xFF0C, 0xFF0F}, {0xFF3B, 0xFF3D},
    {0xFF5F, 0xFF65}
#if CHRBITS > 16
    ,{0x10100, 0x10102}, {0x10A50, 0x10A58}, {0x10AF0, 0x10AF6}, {0x10B39, 0x10B3F},
    {0x10B99, 0x10B9C}, {0x10F55, 0x10F59}, {0x10F86, 0x10F89}, {0x11047, 0x1104D},
    {0x110BE, 0x110C1}, {0x11140, 0x11143}, {0x111C5, 0x111C8}, {0x111DD, 0x111DF},
    {0x11238, 0x1123D}, {0x1144B, 0x1144F}, {0x115C1, 0x115D7}, {0x11641, 0x11643},
    {0x11660, 0x1166C}, {0x1173C, 0x1173E}, {0x11944, 0x11946}, {0x11A3F, 0x11A46},
    {0x11A9A, 0x11A9C}, {0x11A9E, 0x11AA2}, {0x11B00, 0x11B09}, {0x11C41, 0x11C45},

#if CHRBITS > 16
    ,{0x10428, 0x1044F}, {0x104D8, 0x104FB}, {0x10597, 0x105A1}, {0x105A3, 0x105B1},
    {0x105B3, 0x105B9}, {0x10CC0, 0x10CF2}, {0x10D70, 0x10D85}, {0x118C0, 0x118DF},
    {0x16E60, 0x16E7F}, {0x16EBB, 0x16ED3}, {0x1D41A, 0x1D433}, {0x1D44E, 0x1D454},
    {0x1D456, 0x1D467}, {0x1D482, 0x1D49B}, {0x1D4B6, 0x1D4B9}, {0x1D4BD, 0x1D4C3},
    {0x1D4C5, 0x1D4CF}, {0x1D4EA, 0x1D503}, {0x1D51E, 0x1D537}, {0x1D552, 0x1D56B},
    {0x1D586, 0x1D59F}, {0x1D5BA, 0x1D5D3}, {0x1D5EE, 0x1D607}, {0x1D622, 0x1D63B},
    {0x1D656, 0x1D66F}, {0x1D68A, 0x1D6A6}, {0x1D6C2, 0x1D6DA}, {0x1D6DC, 0x1D6E1},
    {0x1D6FC, 0x1D714}, {0x1D716, 0x1D71B}, {0x1D736, 0x1D74E}, {0x1D750, 0x1D755},
    {0x1D770, 0x1D788}, {0x1D78A, 0x1D78F}, {0x1D7AA, 0x1D7C2}, {0x1D7C4, 0x1D7C9},
    {0x1DF00, 0x1DF09}, {0x1DF0B, 0x1DF3F}, {0x1DF41, 0x1DF47}, {0x1DF4E, 0x1DF50},
    {0x1DF52, 0x1DF67}, {0x1DF6F, 0x1DF71}, {0x1DF90, 0x1DF96}, {0x1E922, 0x1E943}
#endif
};

#define NUM_LOWER_RANGE ((int)(sizeof(lowerRangeTable)/sizeof(crange)))

static const chr lowerCharTable[] = {
    0xB5, 0x101, 0x103, 0x105, 0x107, 0x109, 0x10B, 0x10D, 0x10F,

    0xA761, 0xA763, 0xA765, 0xA767, 0xA769, 0xA76B, 0xA76D, 0xA76F, 0xA77A,
    0xA77C, 0xA77F, 0xA781, 0xA783, 0xA785, 0xA787, 0xA78C, 0xA78E, 0xA791,
    0xA797, 0xA799, 0xA79B, 0xA79D, 0xA79F, 0xA7A1, 0xA7A3, 0xA7A5, 0xA7A7,
    0xA7A9, 0xA7AF, 0xA7B5, 0xA7B7, 0xA7B9, 0xA7BB, 0xA7BD, 0xA7BF, 0xA7C1,
    0xA7C3, 0xA7C8, 0xA7CA, 0xA7CD, 0xA7CF, 0xA7D1, 0xA7D3, 0xA7D5, 0xA7D7,
    0xA7D9, 0xA7DB, 0xA7F6, 0xA7FA
#if CHRBITS > 16
    ,0x105BB, 0x105BC, 0x1D4BB, 0x1D7CB, 0x1DF49, 0x1DF4B, 0x1DF4C, 0x1DF69, 0x1DF6B,
    0x1DF6D, 0x1DF73, 0x1DF75, 0x1DF77, 0x1DF79, 0x1DF7B, 0x1DF7D, 0x1DF7F
#endif
};

#define NUM_LOWER_CHAR ((int)(sizeof(lowerCharTable)/sizeof(chr)))

/*
 * Unicode: uppercase characters.

    0xA742, 0xA744, 0xA746, 0xA748, 0xA74A, 0xA74C, 0xA74E, 0xA750, 0xA752,
    0xA754, 0xA756, 0xA758, 0xA75A, 0xA75C, 0xA75E, 0xA760, 0xA762, 0xA764,
    0xA766, 0xA768, 0xA76A, 0xA76C, 0xA76E, 0xA779, 0xA77B, 0xA77D, 0xA77E,
    0xA780, 0xA782, 0xA784, 0xA786, 0xA78B, 0xA78D, 0xA790, 0xA792, 0xA796,
    0xA798, 0xA79A, 0xA79C, 0xA79E, 0xA7A0, 0xA7A2, 0xA7A4, 0xA7A6, 0xA7A8,
    0xA7B6, 0xA7B8, 0xA7BA, 0xA7BC, 0xA7BE, 0xA7C0, 0xA7C2, 0xA7C9, 0xA7CB,
    0xA7CC, 0xA7CE, 0xA7D0, 0xA7D2, 0xA7D4, 0xA7D6, 0xA7D8, 0xA7DA, 0xA7DC,
    0xA7DD, 0xA7E2, 0xA7F5, 0xAB6C, 0xAB6D
#if CHRBITS > 16
    ,0x10594, 0x10595, 0x1D49C, 0x1D49E, 0x1D49F, 0x1D4A2, 0x1D4A5, 0x1D4A6, 0x1D504,
    0x1D505, 0x1D538, 0x1D539, 0x1D546, 0x1D7CA, 0x1DF40, 0x1DF48, 0x1DF4A, 0x1DF4D,
    0x1DF51, 0x1DF68, 0x1DF6A, 0x1DF6C, 0x1DF6E, 0x1DF72, 0x1DF74, 0x1DF76, 0x1DF78,
    0x1DF7A, 0x1DF7C, 0x1DF7E
#endif
};

#define NUM_UPPER_CHAR ((int)(sizeof(upperCharTable)/sizeof(chr)))

/*
 * Unicode: unicode print characters excluding space.
 */

static const crange graphRangeTable[] = {
    {0x21, 0x7E}, {0xA1, 0xAC}, {0xAE, 0x377}, {0x37A, 0x37F},
    {0x384, 0x38A}, {0x38E, 0x3A1}, {0x3A3, 0x52F}, {0x531, 0x556},
    {0x558, 0x58F}, {0x591, 0x5C9}, {0x5D0, 0x5EA}, {0x5EF, 0x5F4},
    {0x606, 0x61B}, {0x61D, 0x6DC}, {0x6DE, 0x70D}, {0x710, 0x74A},
    {0x74D, 0x7B1}, {0x7C0, 0x7FA}, {0x7FD, 0x82D}, {0x830, 0x83E},
    {0x840, 0x85B}, {0x860, 0x86A}, {0x870, 0x88F}, {0x897, 0x8E1},
    {0x8E3, 0x983}, {0x985, 0x98C}, {0x993, 0x9A8}, {0x9AA, 0x9B0},
    {0x9B6, 0x9B9}, {0x9BC, 0x9C4}, {0x9CB, 0x9CE}, {0x9DF, 0x9E3},
    {0x9E6, 0x9FE}, {0xA01, 0xA03}, {0xA05, 0xA0A}, {0xA13, 0xA28},
    {0xA2A, 0xA30}, {0xA3E, 0xA42}, {0xA4B, 0xA4D}, {0xA59, 0xA5C},
    {0xA66, 0xA76}, {0xA81, 0xA83}, {0xA85, 0xA8D}, {0xA8F, 0xA91},
    {0xA93, 0xAA8}, {0xAAA, 0xAB0}, {0xAB5, 0xAB9}, {0xABC, 0xAC5},
    {0xAC7, 0xAC9}, {0xACB, 0xACD}, {0xAE0, 0xAE3}, {0xAE6, 0xAF1},
    {0xAF9, 0xAFF}, {0xB01, 0xB03}, {0xB05, 0xB0C}, {0xB13, 0xB28},
    {0xB2A, 0xB30}, {0xB35, 0xB39}, {0xB3C, 0xB44}, {0xB4B, 0xB4D},
    {0xB53, 0xB57}, {0xB5F, 0xB63}, {0xB66, 0xB77}, {0xB85, 0xB8A},
    {0xB8E, 0xB90}, {0xB92, 0xB95}, {0xBA8, 0xBAA}, {0xBAE, 0xBB9},
    {0xBBE, 0xBC2}, {0xBC6, 0xBC8}, {0xBCA, 0xBCD}, {0xBE6, 0xBFA},
    {0xC00, 0xC0C}, {0xC0E, 0xC10}, {0xC12, 0xC28}, {0xC2A, 0xC39},
    {0xC3C, 0xC44}, {0xC46, 0xC48}, {0xC4A, 0xC4D}, {0xC58, 0xC5A},
    {0xC60, 0xC63}, {0xC66, 0xC6F}, {0xC77, 0xC8C}, {0xC8E, 0xC90},
    {0xC92, 0xCA8}, {0xCAA, 0xCB3}, {0xCB5, 0xCB9}, {0xCBC, 0xCC4},
    {0xCC6, 0xCC8}, {0xCCA, 0xCCD}, {0xCDC, 0xCDE}, {0xCE0, 0xCE3},
    {0xCE6, 0xCEF}, {0xCF1, 0xCF3}, {0xD00, 0xD0C}, {0xD0E, 0xD10},
    {0xD12, 0xD44}, {0xD46, 0xD48}, {0xD4A, 0xD4F}, {0xD54, 0xD63},
    {0xD66, 0xD7F}, {0xD81, 0xD83}, {0xD85, 0xD96}, {0xD9A, 0xDB1},
    {0xDB3, 0xDBB}, {0xDC0, 0xDC6}, {0xDCF, 0xDD4}, {0xDD8, 0xDDF},
    {0xDE6, 0xDEF}, {0xDF2, 0xDF4}, {0xE01, 0xE3A}, {0xE3F, 0xE5B},
    {0xE86, 0xE8A}, {0xE8C, 0xEA3}, {0xEA7, 0xEBD}, {0xEC0, 0xEC4},
    {0xEC8, 0xECE}, {0xED0, 0xED9}, {0xEDC, 0xEDF}, {0xF00, 0xF47},
    {0xF49, 0xF6C}, {0xF71, 0xF97}, {0xF99, 0xFBC}, {0xFBE, 0xFCC},
    {0xFCE, 0xFDA}, {0x1000, 0x10C5}, {0x10D0, 0x1248}, {0x124A, 0x124D},
    {0x1250, 0x1256}, {0x125A, 0x125D}, {0x1260, 0x1288}, {0x128A, 0x128D},
    {0x1290, 0x12B0}, {0x12B2, 0x12B5}, {0x12B8, 0x12BE}, {0x12C2, 0x12C5},
    {0x12C8, 0x12D6}, {0x12D8, 0x1310}, {0x1312, 0x1315}, {0x1318, 0x135A},
    {0x135D, 0x137C}, {0x1380, 0x1399}, {0x13A0, 0x13F5}, {0x13F8, 0x13FD},
    {0x1400, 0x167F}, {0x1681, 0x169C}, {0x16A0, 0x16F8}, {0x1700, 0x1715},
    {0x171F, 0x1736}, {0x1740, 0x1753}, {0x1760, 0x176C}, {0x176E, 0x1770},
    {0x1780, 0x17DD}, {0x17E0, 0x17E9}, {0x17F0, 0x17F9}, {0x1800, 0x180D},
    {0x180F, 0x1819}, {0x1820, 0x1878}, {0x1880, 0x18AA}, {0x18B0, 0x18F5},
    {0x1900, 0x191E}, {0x1920, 0x192B}, {0x1930, 0x193B}, {0x1944, 0x196D},
    {0x1970, 0x1974}, {0x1980, 0x19AB}, {0x19B0, 0x19C9}, {0x19D0, 0x19DA},
    {0x19DE, 0x1A1B}, {0x1A1E, 0x1A5E}, {0x1A60, 0x1A7C}, {0x1A7F, 0x1A89},
    {0x1A90, 0x1A99}, {0x1AA0, 0x1AAD}, {0x1AB0, 0x1AF0}, {0x1B00, 0x1B4C},
    {0x1B4E, 0x1BF3}, {0x1BFC, 0x1C37}, {0x1C3B, 0x1C49}, {0x1C4D, 0x1C8A},
    {0x1C90, 0x1CBA}, {0x1CBD, 0x1CC7}, {0x1CD0, 0x1CFA}, {0x1D00, 0x1F15},
    {0x1F18, 0x1F1D}, {0x1F20, 0x1F45}, {0x1F48, 0x1F4D}, {0x1F50, 0x1F57},
    {0x1F5F, 0x1F7D}, {0x1F80, 0x1FB4}, {0x1FB6, 0x1FC4}, {0x1FC6, 0x1FD3},
    {0x1FD6, 0x1FDB}, {0x1FDD, 0x1FEF}, {0x1FF2, 0x1FF4}, {0x1FF6, 0x1FFE},
    {0x2010, 0x2027}, {0x2030, 0x205E}, {0x2074, 0x20C4}, {0x20D0, 0x20F0},

    {0x2100, 0x218B}, {0x2190, 0x2429}, {0x2440, 0x244A}, {0x2460, 0x2B73},
    {0x2B76, 0x2CF3}, {0x2CF9, 0x2D25}, {0x2D30, 0x2D67}, {0x2D7F, 0x2D96},
    {0x2DA0, 0x2DA6}, {0x2DA8, 0x2DAE}, {0x2DB0, 0x2DB6}, {0x2DB8, 0x2DBE},
    {0x2DC0, 0x2DC6}, {0x2DC8, 0x2DCE}, {0x2DD0, 0x2DD6}, {0x2DD8, 0x2DDE},
    {0x2DE0, 0x2E5D}, {0x2E60, 0x2E63}, {0x2E80, 0x2E99}, {0x2E9B, 0x2EF3},
    {0x2F00, 0x2FD5}, {0x2FF0, 0x2FFF}, {0x3001, 0x303F}, {0x3041, 0x3096},
    {0x3099, 0x30FF}, {0x3105, 0x312F}, {0x3131, 0x318E}, {0x3190, 0x31E5},
    {0x31EF, 0x321E}, {0x3220, 0xA48C}, {0xA490, 0xA4C6}, {0xA4D0, 0xA62B},
    {0xA640, 0xA6F7}, {0xA700, 0xA7DD}, {0xA7F1, 0xA82C}, {0xA830, 0xA839},
    {0xA840, 0xA877}, {0xA880, 0xA8C5}, {0xA8CE, 0xA8D9}, {0xA8E0, 0xA953},
    {0xA95F, 0xA97C}, {0xA980, 0xA9CD}, {0xA9CF, 0xA9D9}, {0xA9DE, 0xA9FE},
    {0xAA00, 0xAA36}, {0xAA40, 0xAA4D}, {0xAA50, 0xAA59}, {0xAA5C, 0xAAC2},
    {0xAADB, 0xAAF6}, {0xAB01, 0xAB06}, {0xAB09, 0xAB0E}, {0xAB11, 0xAB16},
    {0xAB20, 0xAB26}, {0xAB28, 0xAB2E}, {0xAB30, 0xAB6D}, {0xAB70, 0xABED},
    {0xABF0, 0xABF9}, {0xAC00, 0xD7A3}, {0xD7B0, 0xD7C6}, {0xD7CB, 0xD7FB},
    {0xF900, 0xFA6D}, {0xFA70, 0xFAD9}, {0xFB00, 0xFB06}, {0xFB13, 0xFB17},
    {0xFB1D, 0xFB36}, {0xFB38, 0xFB3C}, {0xFB46, 0xFDCF}, {0xFDF0, 0xFE19},
    {0xFE20, 0xFE52}, {0xFE54, 0xFE66}, {0xFE68, 0xFE6B}, {0xFE70, 0xFE74},
    {0xFE76, 0xFEFC}, {0xFF01, 0xFFBE}, {0xFFC2, 0xFFC7}, {0xFFCA, 0xFFCF},
    {0xFFD2, 0xFFD7}, {0xFFDA, 0xFFDC}, {0xFFE0, 0xFFE6}, {0xFFE8, 0xFFEE}
#if CHRBITS > 16
    ,{0x10000, 0x1000B}, {0x1000D, 0x10026}, {0x10028, 0x1003A}, {0x1003F, 0x1004D},
    {0x10050, 0x1005D}, {0x10080, 0x100FA}, {0x10100, 0x10102}, {0x10107, 0x10133},
    {0x10137, 0x1018E}, {0x10190, 0x1019C}, {0x101D0, 0x101FD}, {0x10280, 0x1029C},
    {0x102A0, 0x102D0}, {0x102E0, 0x102FB}, {0x10300, 0x10323}, {0x1032D, 0x1034A},
    {0x10350, 0x1037A}, {0x10380, 0x1039D}, {0x1039F, 0x103C3}, {0x103C8, 0x103D5},
    {0x10400, 0x1049D}, {0x104A0, 0x104A9}, {0x104B0, 0x104D3}, {0x104D8, 0x104FB},
    {0x10500, 0x10527}, {0x10530, 0x10563}, {0x1056F, 0x1057A}, {0x1057C, 0x1058A},
    {0x1058C, 0x10592}, {0x10597, 0x105A1}, {0x105A3, 0x105B1}, {0x105B3, 0x105B9},
    {0x105C0, 0x105F3}, {0x10600, 0x10736}, {0x10740, 0x10755}, {0x10760, 0x10767},
    {0x10780, 0x10785}, {0x10787, 0x107B0}, {0x107B2, 0x107BF}, {0x10800, 0x10805},
    {0x1080A, 0x10835}, {0x1083F, 0x10855}, {0x10857, 0x1089E}, {0x108A7, 0x108AF},
    {0x108E0, 0x108F2}, {0x108FB, 0x1091B}, {0x1091F, 0x10939}, {0x1093F, 0x10959},
    {0x10980, 0x109B7}, {0x109BC, 0x109CF}, {0x109D2, 0x10A03}, {0x10A0C, 0x10A13},
    {0x10A15, 0x10A17}, {0x10A19, 0x10A35}, {0x10A38, 0x10A3A}, {0x10A3F, 0x10A48},
    {0x10A50, 0x10A58}, {0x10A60, 0x10A9F}, {0x10AC0, 0x10AE6}, {0x10AEB, 0x10AF6},
    {0x10B00, 0x10B35}, {0x10B39, 0x10B55}, {0x10B58, 0x10B72}, {0x10B78, 0x10B91},
    {0x10B99, 0x10B9C}, {0x10BA9, 0x10BAF}, {0x10C00, 0x10C48}, {0x10C80, 0x10CB2},
    {0x10CC0, 0x10CF2}, {0x10CFA, 0x10D27}, {0x10D30, 0x10D39}, {0x10D40, 0x10D65},
    {0x10D69, 0x10D85}, {0x10E60, 0x10E7E}, {0x10E80, 0x10EA9}, {0x10EAB, 0x10EAD},
    {0x10EC2, 0x10EC7}, {0x10EC9, 0x10EEE}, {0x10EF0, 0x10F27}, {0x10F30, 0x10F59},
    {0x10F70, 0x10F89}, {0x10FB0, 0x10FCB}, {0x10FE0, 0x10FF6}, {0x11000, 0x1104D},
    {0x11052, 0x11075}, {0x1107F, 0x110BC}, {0x110BE, 0x110C2}, {0x110D0, 0x110E8},
    {0x110F0, 0x110F9}, {0x11100, 0x11134}, {0x11136, 0x11147}, {0x11150, 0x11176},
    {0x11180, 0x111DF}, {0x111E1, 0x111F4}, {0x11200, 0x11211}, {0x11213, 0x11241},
    {0x11280, 0x11286}, {0x1128A, 0x1128D}, {0x1128F, 0x1129D}, {0x1129F, 0x112A9},
    {0x112B0, 0x112EA}, {0x112F0, 0x112F9}, {0x11300, 0x11303}, {0x11305, 0x1130C},
    {0x11313, 0x11328}, {0x1132A, 0x11330}, {0x11335, 0x11339}, {0x1133B, 0x11344},
    {0x1134B, 0x1134D}, {0x1135D, 0x11363}, {0x11366, 0x1136C}, {0x11370, 0x11374},
    {0x11380, 0x11389}, {0x11390, 0x113B5}, {0x113B7, 0x113C0}, {0x113C7, 0x113CA},
    {0x113CC, 0x113D5}, {0x11400, 0x1145B}, {0x1145D, 0x11461}, {0x11480, 0x114C7},
    {0x114D0, 0x114D9}, {0x11580, 0x115B5}, {0x115B8, 0x115DD}, {0x11600, 0x11644},
    {0x11650, 0x11659}, {0x11660, 0x1166C}, {0x11680, 0x116B9}, {0x116C0, 0x116C9},
    {0x116D0, 0x116E3}, {0x11700, 0x1171A}, {0x1171D, 0x1172B}, {0x11730, 0x11746},
    {0x11800, 0x1183B}, {0x118A0, 0x118F2}, {0x118FF, 0x11906}, {0x1190C, 0x11913},
    {0x11918, 0x11935}, {0x1193B, 0x11946}, {0x11950, 0x11959}, {0x119A0, 0x119A7},
    {0x119AA, 0x119D7}, {0x119DA, 0x119E4}, {0x11A00, 0x11A47}, {0x11A50, 0x11AA2},
    {0x11AB0, 0x11AF8}, {0x11B00, 0x11B0A}, {0x11B60, 0x11B67}, {0x11BC0, 0x11BE1},
    {0x11BF0, 0x11BF9}, {0x11C00, 0x11C08}, {0x11C0A, 0x11C36}, {0x11C38, 0x11C45},
    {0x11C50, 0x11C6C}, {0x11C70, 0x11C8F}, {0x11C92, 0x11CA7}, {0x11CA9, 0x11CB6},
    {0x11D00, 0x11D06}, {0x11D0B, 0x11D36}, {0x11D3F, 0x11D47}, {0x11D50, 0x11D59},
    {0x11D60, 0x11D65}, {0x11D6A, 0x11D8E}, {0x11D93, 0x11D98}, {0x11DA0, 0x11DA9},
    {0x11DB0, 0x11DDB}, {0x11DE0, 0x11DE9}, {0x11EE0, 0x11EF8}, {0x11F00, 0x11F10},
    {0x11F12, 0x11F3A}, {0x11F3E, 0x11F5A}, {0x11FC0, 0x11FF1}, {0x11FFF, 0x12399},
    {0x12400, 0x12543}, {0x12550, 0x12686}, {0x12F90, 0x12FF2}, {0x13000, 0x1342F},
    {0x13440, 0x13455}, {0x13460, 0x143FA}, {0x14400, 0x14646}, {0x16100, 0x16139},
    {0x16800, 0x16A38}, {0x16A40, 0x16A5E}, {0x16A60, 0x16A69}, {0x16A6E, 0x16ABE},
    {0x16AC0, 0x16AC9}, {0x16AD0, 0x16AED}, {0x16AF0, 0x16AF5}, {0x16B00, 0x16B45},
    {0x16B50, 0x16B59}, {0x16B5B, 0x16B61}, {0x16B63, 0x16B77}, {0x16B7D, 0x16B8F},
    {0x16D40, 0x16D79}, {0x16D80, 0x16D9D}, {0x16DA0, 0x16DA9}, {0x16E40, 0x16E9A},
    {0x16EA0, 0x16EB8}, {0x16EBB, 0x16ED3}, {0x16F00, 0x16F4A}, {0x16F4F, 0x16F87},
    {0x16F8F, 0x16F9F}, {0x16FE0, 0x16FE4}, {0x16FF0, 0x16FF6}, {0x17000, 0x18CDA},
    {0x18CFF, 0x18D20}, {0x18D80, 0x18DF2}, {0x18E00, 0x19191}, {0x191A0, 0x191D2},
    {0x1AFF0, 0x1AFF3}, {0x1AFF5, 0x1AFFB}, {0x1B000, 0x1B128}, {0x1B150, 0x1B152},
    {0x1B164, 0x1B168}, {0x1B170, 0x1B2FB}, {0x1BC00, 0x1BC6A}, {0x1BC70, 0x1BC7C},
    {0x1BC80, 0x1BC88}, {0x1BC90, 0x1BC99}, {0x1BC9C, 0x1BC9F}, {0x1CC00, 0x1CCFC},
    {0x1CD00, 0x1CEB3}, {0x1CEBA, 0x1CED0}, {0x1CED2, 0x1CED4}, {0x1CEDD, 0x1CEFD},
    {0x1CF00, 0x1CF2D}, {0x1CF30, 0x1CF46}, {0x1CF50, 0x1CFC3}, {0x1D000, 0x1D0F5},
    {0x1D100, 0x1D172}, {0x1D17B, 0x1D245}, {0x1D250, 0x1D281}, {0x1D2C0, 0x1D2D3},
    {0x1D2E0, 0x1D2F3}, {0x1D300, 0x1D356}, {0x1D360, 0x1D378}, {0x1D400, 0x1D454},
    {0x1D456, 0x1D49C}, {0x1D4A9, 0x1D4AC}, {0x1D4AE, 0x1D4B9}, {0x1D4BD, 0x1D4C3},
    {0x1D4C5, 0x1D505}, {0x1D507, 0x1D50A}, {0x1D50D, 0x1D514}, {0x1D516, 0x1D51C},
    {0x1D51E, 0x1D539}, {0x1D53B, 0x1D53E}, {0x1D540, 0x1D544}, {0x1D54A, 0x1D550},
    {0x1D552, 0x1D6A6}, {0x1D6A8, 0x1D7CB}, {0x1D7CE, 0x1DA8B}, {0x1DA9B, 0x1DA9F},
    {0x1DAA1, 0x1DAAF}, {0x1DB00, 0x1DB1C}, {0x1DF00, 0x1DF81}, {0x1DF90, 0x1DF96},
    {0x1DFCD, 0x1E006}, {0x1E008, 0x1E018}, {0x1E01B, 0x1E021}, {0x1E026, 0x1E02A},
    {0x1E030, 0x1E06D}, {0x1E100, 0x1E12C}, {0x1E130, 0x1E13D}, {0x1E140, 0x1E149},
    {0x1E290, 0x1E2AE}, {0x1E2C0, 0x1E2F9}, {0x1E4D0, 0x1E4F9}, {0x1E5D0, 0x1E5FA},
    {0x1E6C0, 0x1E6DE}, {0x1E6E0, 0x1E6F5}, {0x1E7E0, 0x1E7E6}, {0x1E7E8, 0x1E7EB},
    {0x1E7F0, 0x1E7FE}, {0x1E800, 0x1E8C4}, {0x1E8C7, 0x1E8D6}, {0x1E900, 0x1E94B},
    {0x1E950, 0x1E959}, {0x1EC71, 0x1ECB4}, {0x1ED01, 0x1ED3D}, {0x1EE00, 0x1EE03},
    {0x1EE05, 0x1EE1F}, {0x1EE29, 0x1EE32}, {0x1EE34, 0x1EE37}, {0x1EE4D, 0x1EE4F},
    {0x1EE67, 0x1EE6A}, {0x1EE6C, 0x1EE72}, {0x1EE74, 0x1EE77}, {0x1EE79, 0x1EE7C},
    {0x1EE80, 0x1EE89}, {0x1EE8B, 0x1EE9B}, {0x1EEA1, 0x1EEA3}, {0x1EEA5, 0x1EEA9},
    {0x1EEAB, 0x1EEBB}, {0x1F000, 0x1F02B}, {0x1F030, 0x1F093}, {0x1F0A0, 0x1F0AE},
    {0x1F0B1, 0x1F0BF}, {0x1F0C1, 0x1F0CF}, {0x1F0D1, 0x1F0F5}, {0x1F100, 0x1F1AE},
    {0x1F1E6, 0x1F202}, {0x1F210, 0x1F23B}, {0x1F240, 0x1F248}, {0x1F260, 0x1F265},
    {0x1F300, 0x1F6D9}, {0x1F6DC, 0x1F6EC}, {0x1F6F0, 0x1F6FC}, {0x1F700, 0x1F7DB},
    {0x1F7E0, 0x1F7EB}, {0x1F7F0, 0x1F80B}, {0x1F810, 0x1F847}, {0x1F850, 0x1F859},
    {0x1F860, 0x1F887}, {0x1F890, 0x1F8AD}, {0x1F8B0, 0x1F8BB}, {0x1F8D0, 0x1F8D8},
    {0x1F900, 0x1FA57}, {0x1FA60, 0x1FA6D}, {0x1FA70, 0x1FA7C}, {0x1FA80, 0x1FAC6},
    {0x1FACC, 0x1FADD}, {0x1FADF, 0x1FAEB}, {0x1FAEF, 0x1FAFA}, {0x1FB00, 0x1FB92},
    {0x1FB94, 0x1FBFA}, {0x20000, 0x2A6DF}, {0x2A700, 0x2B81E}, {0x2B820, 0x2CEAD},
    {0x2CEB0, 0x2EBE0}, {0x2EBF0, 0x2EE5D}, {0x2F800, 0x2FA1D}, {0x30000, 0x3134A},
    {0x31350, 0x33479}, {0x3D000, 0x3FC3F}, {0xE0100, 0xE01EF}
#endif
};

#define NUM_GRAPH_RANGE ((int)(sizeof(graphRangeTable)/sizeof(crange)))

static const chr graphCharTable[] = {
    0x38C, 0x85E, 0x98F, 0x990, 0x9B2, 0x9C7, 0x9C8, 0x9D7, 0x9DC,
    0x9DD, 0xA0F, 0xA10, 0xA32, 0xA33, 0xA35, 0xA36, 0xA38, 0xA39,
    0xA3C, 0xA47, 0xA48, 0xA51, 0xA5E, 0xAB2, 0xAB3, 0xAD0, 0xB0F,
    0xB10, 0xB32, 0xB33, 0xB47, 0xB48, 0xB5C, 0xB5D, 0xB82, 0xB83,
    0xB99, 0xB9A, 0xB9C, 0xB9E, 0xB9F, 0xBA3, 0xBA4, 0xBD0, 0xBD7,
    0xC55, 0xC56, 0xC5C, 0xC5D, 0xCD5, 0xCD6, 0xDBD, 0xDCA, 0xDD6,
    0xE81, 0xE82, 0xE84, 0xEA5, 0xEC6, 0x10C7, 0x10CD, 0x1258, 0x12C0,
    0x1772, 0x1773, 0x1940, 0x1F59, 0x1F5B, 0x1F5D, 0x2070, 0x2071, 0x2D27,
    0x2D2D, 0x2D6F, 0x2D70, 0xA7E2, 0xFB3E, 0xFB40, 0xFB41, 0xFB43, 0xFB44,
    0xFFFC, 0xFFFD
#if CHRBITS > 16
    ,0x1003C, 0x1003D, 0x101A0, 0x10594, 0x10595, 0x105BB, 0x105BC, 0x10808, 0x10837,
    0x10838, 0x1083C, 0x108F4, 0x108F5, 0x10A05, 0x10A06, 0x10D8E, 0x10D8F, 0x10EB0,
    0x10EB1, 0x11288, 0x1130F, 0x11310, 0x11332, 0x11333, 0x11347, 0x11348, 0x11350,
    0x11357, 0x1138B, 0x1138E, 0x113C2, 0x113C5, 0x113D7, 0x113D8, 0x113E1, 0x113E2,
    0x11909, 0x11915, 0x11916, 0x11937, 0x11938, 0x11D08, 0x11D09, 0x11D3A, 0x11D3C,
    0x11D3D, 0x11D67, 0x11D68, 0x11D90, 0x11D91, 0x11DF0, 0x11DF1, 0x11FB0, 0x1AFFD,
    0x1AFFE, 0x1B132, 0x1B155, 0x1D49E, 0x1D49F, 0x1D4A2, 0x1D4A5, 0x1D4A6, 0x1D4BB,
    0x1D546, 0x1E023, 0x1E024, 0x1E08F, 0x1E14E, 0x1E14F, 0x1E2FF, 0x1E5FF, 0x1E6FE,
    0x1E6FF, 0x1E7ED, 0x1E7EE, 0x1E95E, 0x1E95F, 0x1EE21, 0x1EE22, 0x1EE24, 0x1EE27,
    0x1EE39, 0x1EE3B, 0x1EE42, 0x1EE47, 0x1EE49, 0x1EE4B, 0x1EE51, 0x1EE52, 0x1EE54,
    0x1EE57, 0x1EE59, 0x1EE5B, 0x1EE5D, 0x1EE5F, 0x1EE61, 0x1EE62, 0x1EE64, 0x1EE7E,
    0x1EEF0, 0x1EEF1, 0x1F250, 0x1F251, 0x1F8C0, 0x1F8C1, 0x1FAC8
#endif
};

#define NUM_GRAPH_CHAR ((int)(sizeof(graphCharTable)/sizeof(chr)))

/*
 *	End of auto-generated Unicode character ranges declarations.

static void
sortins(
    struct nfa * nfa,
    struct state * s)
{
    struct arc **sortarray;
    struct arc *a;
    size_t n = s->nins;
    size_t i;

    if (n <= 1) {
	return;		/* nothing to do */
    }
    /* make an array of arc pointers ... */
    sortarray = (struct arc **) MALLOC(n * sizeof(struct arc *));
    if (sortarray == NULL) {

}

static int
sortins_cmp(
    const void *a,
    const void *b)
{
    const struct arc *aa = *((const struct arc *const *) a);
    const struct arc *bb = *((const struct arc *const *) b);

    /* we check the fields in the order they are most likely to be different */
    if (aa->from->no < bb->from->no) {
	return -1;
    }
    if (aa->from->no > bb->from->no) {
	return 1;

static void
sortouts(
    struct nfa * nfa,
    struct state * s)
{
    struct arc **sortarray;
    struct arc *a;
    size_t	n = s->nouts;
    size_t	i;

    if (n <= 1) {
	return;					/* nothing to do */
    }
    /* make an array of arc pointers ... */
    sortarray = (struct arc **) MALLOC(n * sizeof(struct arc *));
    if (sortarray == NULL) {

}

static int
sortouts_cmp(
    const void *a,
    const void *b)
{
    const struct arc *aa = *((const struct arc *const *) a);
    const struct arc *bb = *((const struct arc *const *) b);

    /* we check the fields in the order they are most likely to be different */
    if (aa->to->no < bb->to->no) {
	return -1;
    }
    if (aa->to->no > bb->to->no) {
	return 1;

 * and are not guaranteed unique.  It's okay to clobber the array contents.
 */
static void
mergeins(
    struct nfa * nfa,
    struct state * s,
    struct arc ** arcarray,
    size_t arccount)
{
    struct arc *na;
    size_t i;
    size_t j;

    if (arccount <= 0) {
	return;
    }

    /*
     * Because we bypass newarc() in this code path, we'd better include a

    FILE *f)			/* for debug output; NULL none */
{
    struct state *s;
    struct state *s2;
    struct state *nexts;
    struct arc *a;
    struct arc *nexta;
    size_t totalinarcs;
    struct arc **inarcsorig;
    struct arc **arcarray;
    size_t arccount;
    size_t prevnins;
    size_t nskip;

    /*
     * First, get rid of any states whose sole out-arc is an EMPTY,
     * since they're basically just aliases for their successor.  The
     * parsing algorithm creates enough of these that it's worth
     * special-casing this.
     */

static void makesearch(struct vars *, struct nfa *);
static struct subre *parse(struct vars *, int, int, struct state *, struct state *);
static struct subre *parsebranch(struct vars *, int, int, struct state *, struct state *, int);
static void parseqatom(struct vars *, int, int, struct state *, struct state *, struct subre *);
static void nonword(struct vars *, int, struct state *, struct state *);
static void word(struct vars *, int, struct state *, struct state *);
static int scannum(struct vars *);
static void repeat(struct vars *, struct state *, struct state *, size_t, size_t);
static void bracket(struct vars *, struct state *, struct state *);
static void cbracket(struct vars *, struct state *, struct state *);
static void brackpart(struct vars *, struct state *, struct state *);
static const chr *scanplain(struct vars *);
static void onechr(struct vars *, pchr, struct state *, struct state *);
static void dovec(struct vars *, struct cvec *, struct state *, struct state *);
static void wordchrs(struct vars *);
static struct subre *sub_re(struct vars *, int, int, struct state *, struct state *);
static void freesubre(struct vars *, struct subre *);
static void freesrnode(struct vars *, struct subre *);
static size_t numst(struct subre *, size_t);
static void markst(struct subre *);
static void cleanst(struct vars *);
static long nfatree(struct vars *, struct subre *, FILE *);
static long nfanode(struct vars *, struct subre *, FILE *);
static size_t newlacon(struct vars *, struct state *, struct state *, size_t);
static void freelacons(struct subre *, size_t);
static void rfree(regex_t *);
static void dump(regex_t *, FILE *);
static void dumpst(struct subre *, FILE *, int);
static void stdump(struct subre *, FILE *, int);
static const char *stid(struct subre *, char *, size_t);
/* === regc_lex.c === */
static void lexstart(struct vars *);

static void cparc(struct nfa *, struct arc *, struct state *, struct state *);
static void sortins(struct nfa *, struct state *);
static int sortins_cmp(const void *, const void *);
static void sortouts(struct nfa *, struct state *);
static int sortouts_cmp(const void *, const void *);
static void moveins(struct nfa *, struct state *, struct state *);
static void copyins(struct nfa *, struct state *, struct state *);
static void mergeins(struct nfa *, struct state *, struct arc **, size_t);
static void moveouts(struct nfa *, struct state *, struct state *);
static void copyouts(struct nfa *, struct state *, struct state *);
static void cloneouts(struct nfa *, struct state *, struct state *, struct state *, int);
static void delsub(struct nfa *, struct state *, struct state *);
static void deltraverse(struct nfa *, struct state *, struct state *);
static void dupnfa(struct nfa *, struct state *, struct state *, struct state *, struct state *);
static void duptraverse(struct nfa *, struct state *, struct state *, int);

    const chr *stop;		/* end of string */
    const chr *savenow;		/* saved now and stop for "subroutine call" */
    const chr *savestop;
    int err;			/* error code (0 if none) */
    int cflags;			/* copy of compile flags */
    int lasttype;		/* type of previous token */
    int nexttype;		/* type of next token */
    chr nextvalue;		/* value (if any) of next token */
    int lexcon;			/* lexical context type (see lex.c) */
    size_t nsubexp;		/* subexpression count */
    struct subre **subs;	/* subRE pointer vector */
    size_t nsubs;		/* length of vector */
    struct subre *sub10[10];	/* initial vector, enough for most */
    struct nfa *nfa;		/* the NFA */
    struct colormap *cm;	/* character color map */

	right = newstate(v->nfa);
	NOERRN();
	EMPTYARC(init, left);
	EMPTYARC(right, final);
	NOERRN();
	branch->left = parsebranch(v, stopper, type, left, right, 0);
	NOERRN();
	branch->flags |= (char)(UP(branch->flags | branch->left->flags));
	if ((branch->flags &~ branches->flags) != 0) {	/* new flags */
	    for (t = branches; t != branch; t = t->right) {
		t->flags |= branch->flags;
	    }
	}
    } while (EAT('|'));
    assert(SEE(stopper) || SEE(EOS));

    int type,			/* LACON (lookahead subRE) or PLAIN */
    struct state *lp,		/* left state to hang it on */
    struct state *rp,		/* right state to hang it on */
    struct subre *top)		/* subtree top */
{
    struct state *s;		/* temporaries for new states */
    struct state *s2;
#define	ARCV(t, val)	newarc(v->nfa, (t), (pcolor)(val), lp, rp)
    size_t m, n;
    struct subre *atom;		/* atom's subtree */
    struct subre *t;
    size_t cap;			/* capturing parens? */
    size_t pos;			/* positive lookahead? */
    size_t subno;		/* capturing-parens or backref number */
    int atomtype;
    int qprefer;		/* quantifier short/long preference */
    int f;
    struct subre **atomp;	/* where the pointer to atom is */

    /*

	/*
	 * Postpone everything else pending possible {0}.
	 */

	break;
    case BACKREF:		/* the Feature From The Black Lagoon */
	INSIST(type != LACON, REG_ESUBREG);
	INSIST((size_t)v->nextvalue < v->nsubs, REG_ESUBREG);
	INSIST(v->subs[v->nextvalue] != NULL, REG_ESUBREG);
	NOERR();
	assert(v->nextvalue > 0);
	atom = sub_re(v, 'b', BACKR, lp, rp);
	NOERR();
	subno = v->nextvalue;
	atom->subno = subno;

    if (atomtype != '(' && atomtype != BACKREF && !MESSY(UP(f))) {
	if (!(m == 1 && n == 1)) {
	    repeat(v, lp, rp, m, n);
	}
	if (atom != NULL) {
	    freesubre(v, atom);
	}
	top->flags = (char)f;
	return;
    }

    /*
     * hard part: something messy
     * That is, capturing parens, back reference, short/long clash, or an atom
     * with substructure containing one of those.

	/*
	 * Just stuff everything into atom.
	 */

	repeat(v, atom->begin, atom->end, m, n);
	atom->min = (short) m;
	atom->max = (short) n;
	atom->flags |= (char)COMBINE(qprefer, atom->flags);
	/* rest of branch can be strung starting from atom->end */
	s2 = atom->end;
    } else if (m == 1 && n == 1) {
	/*
	 * No/vacuous quantifier: done.
	 */

	t->right = parsebranch(v, stopper, type, s2, rp, 1);
    } else {
	EMPTYARC(s2, rp);
	t->right = sub_re(v, '=', 0, s2, rp);
    }
    NOERR();
    assert(SEE('|') || SEE(stopper) || SEE(EOS));
    t->flags |= (char)COMBINE(t->flags, t->right->flags);
    top->flags |= (char)COMBINE(top->flags, t->flags);
}

/*
 - nonword - generate arcs for non-word-character ahead or behind
 ^ static void nonword(struct vars *, int, struct state *, struct state *);
 */
static void

 ^ static void repeat(struct vars *, struct state *, struct state *, int, int);
 */
static void
repeat(
    struct vars *v,
    struct state *lp,
    struct state *rp,
    size_t m,
    size_t n)
{
#define	SOME		2
#define	INF		3
#define	PAIR(x, y)	((x)*4 + (y))
#define	REDUCE(x)	( ((x) == DUPINF) ? INF : (((x) > 1) ? SOME : (int)(x)) )
    const int rm = REDUCE(m);
    const int rn = REDUCE(n);
    struct state *s, *s2;

    switch (PAIR(rm, rn)) {
    case PAIR(0, 0):		/* empty string */
	delsub(v->nfa, lp, rp);

    struct vars *v,
    struct cvec *cv,
    struct state *lp,
    struct state *rp)
{
    chr ch, from, to;
    const chr *p;
    size_t i;

    for (p = cv->chrs, i = cv->nchrs; i > 0; p++, i--) {
	ch = *p;
	newarc(v->nfa, PLAIN, subcolor(v->cm, ch), lp, rp);
    }

    for (p = cv->ranges, i = cv->nranges; i > 0; p += 2, i--) {

	}
	ret->chain = v->treechain;
	v->treechain = ret;
    }

    assert(strchr("=b|.*(", op) != NULL);

    ret->op = (char)op;
    ret->flags = (char)flags;
    ret->id = 0;		/* will be assigned later */
    ret->subno = 0;
    ret->min = ret->max = 1;
    ret->left = NULL;
    ret->right = NULL;
    ret->begin = begin;
    ret->end = end;

    freenfa(nfa);
    return ret;
}

/*
 - newlacon - allocate a lookahead-constraint subRE
 ^ static size_t newlacon(struct vars *, struct state *, struct state *, size_t);
 */
static size_t		/* lacon number */
newlacon(
    struct vars *v,
    struct state *begin,
    struct state *end,
    size_t pos)
{
    size_t n;
    struct subre *newlacons;
    struct subre *sub;

    if (v->nlacons == 0) {
	n = 1;		/* skip 0th */
	newlacons = (struct subre *) MALLOC(2 * sizeof(struct subre));
    } else {

/*
 - freelacons - free lookahead-constraint subRE vector
 ^ static void freelacons(struct subre *, int);
 */
static void
freelacons(
    struct subre *subs,
    size_t n)
{
    struct subre *sub;
    size_t i;

    assert(n > 0);
    for (sub=subs+1, i=n-1; i>0; sub++, i--) {	/* no 0th */
	if (!NULLCNFA(sub->cnfa)) {
	    freecnfa(&sub->cnfa);
	}
    }

    if (t->flags&BACKR) {
	fprintf(f, " hasbackref");
    }
    if (!(t->flags&INUSE)) {
	fprintf(f, " UNUSED");
    }
    if (t->subno != 0) {
	fprintf(f, " (#%" TCL_Z_MODIFIER "d)", t->subno);
    }
    if (t->min != 1 || t->max != 1) {
	fprintf(f, " {%d,", t->min);
	if (t->max != DUPINF) {
	    fprintf(f, "%d", t->max);
	}
	fprintf(f, "}");

/*
 * Copyright © 1998, 1999 Henry Spencer.  All rights reserved.
 *
 * Development of this software was funded, in part, by Cray Research Inc.,
 * UUNET Communications Services Inc., Sun Microsystems Inc., and Scriptics
 * Corporation, none of whom are responsible for the results. The author
 * thanks all of them.
 *
 * Redistribution and use in source and binary forms - with or without

	FREE(d->mallocarea);
    }
}

/*
 - hash - construct a hash code for a bitvector
 * There are probably better ways, but they're more expensive.
 ^ static unsigned hash(unsigned *, size_t);
 */
static unsigned
hash(
    unsigned *const uv,
    size_t n)
{
    size_t i;
    unsigned h;

    h = 0;
    for (i = 0; i < n; i++) {
	h ^= uv[i];
    }
    return h;

#ifndef _REGEX_H_
#define	_REGEX_H_	/* never again */

#include "tclInt.h"

/*
 * regular expressions
 *
 * Copyright © 1998, 1999 Henry Spencer.  All rights reserved.
 *
 * Development of this software was funded, in part, by Cray Research Inc.,
 * UUNET Communications Services Inc., Sun Microsystems Inc., and Scriptics
 * Corporation, none of whom are responsible for the results. The author
 * thanks all of them.
 *
 * Redistribution and use in source and binary forms -- with or without

static int creviterdissect(struct vars *, struct subre *, chr *, chr *);
/* === rege_dfa.c === */
static chr *longest(struct vars *const, struct dfa *const, chr *const, chr *const, int *const);
static chr *shortest(struct vars *const, struct dfa *const, chr *const, chr *const, chr *const, chr **const, int *const);
static chr *lastCold(struct vars *const, struct dfa *const);
static struct dfa *newDFA(struct vars *const, struct cnfa *const, struct colormap *const, struct smalldfa *);
static void freeDFA(struct dfa *const);
static unsigned hash(unsigned *const, size_t);
static struct sset *initialize(struct vars *const, struct dfa *const, chr *const);
static struct sset *miss(struct vars *const, struct dfa *const, struct sset *const, const pcolor, chr *const, chr *const);
static int checkLAConstraint(struct vars *const, struct cnfa *const, chr *const, const pcolor);
static struct sset *getVacantSS(struct vars *const, struct dfa *const, chr *const, chr *const);
static struct sset *pickNextSS(struct vars *const, struct dfa *const, chr *const, chr *const);
/* automatically gathered by fwd; do not hand-edit */
/* =====^!^===== end forwards =====^!^===== */

    rm_detail_t *details,
    size_t nmatch,
    regmatch_t pmatch[],
    int flags)
{
    AllocVars(v);
    int st, backref;
    size_t n;
    size_t i;
#define	LOCALMAT	20
    regmatch_t mat[LOCALMAT];
#define LOCALDFAS	40
    struct dfa *subdfas[LOCALDFAS];

    /*
     * Sanity checks.

static void
subset(
    struct vars *const v,
    struct subre *const sub,
    chr *const begin,
    chr *const end)
{
    size_t n = sub->subno;

    assert(n > 0);
    if ((size_t)n >= v->nmatch) {
	return;
    }

    MDEBUG(("setting %d\n", n));

static int			/* regexec return code */
cbrdissect(
    struct vars *v,
    struct subre *t,
    chr *begin,		/* beginning of relevant substring */
    chr *end)		/* end of same */
{
    size_t n = t->subno;
    int min = t->min, max = t->max;
    size_t numreps;
    size_t tlen;
    size_t brlen;
    chr *brstring;
    chr *p;

    assert(t != NULL);
    assert(t->op == 'b');

    assert((size_t)n < v->nmatch);

    MDEBUG(("cbackref n%d %d{%d-%d}\n", t->id, n, min, max));

    /* get the backreferenced string */
    if (v->pmatch[n].rm_so == FREESTATE) {
	return REG_NOMATCH;