Tcl Source Code

Check-in [a72a317ba0]
Login
Bounty program for improvements to Tcl and certain Tcl packages.
Tcl 2019 Conference, Houston/TX, US, Nov 4-8
Send your abstracts to [email protected]
or submit via the online form by Sep 9.

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:merge novem
Downloads: Tarball | ZIP archive | SQL archive
Timelines: family | ancestors | descendants | both | novem-purge-literals
Files: files | file ages | folders
SHA3-256: a72a317ba0c2cc89e32117dda75541fc1ac7ba133da140b17dcbf49720b69e56
User & Date: dgp 2019-06-12 19:34:43
Context
2019-06-17
18:38
merge novem Leaf check-in: 5f6508a146 user: dgp tags: novem-purge-literals
2019-06-12
19:34
merge novem check-in: a72a317ba0 user: dgp tags: novem-purge-literals
18:41
merge trunk check-in: 9b0d0c83a1 user: dgp tags: novem
2018-03-15
15:43
merge novem check-in: 700b9a198f user: dgp tags: novem-purge-literals
Changes
Hide Diffs Side-by-Side Diffs Ignore Whitespace Patch

Deleted .fossil-settings/crnl-glob.

     1         -compat/zlib/contrib/dotzlib/DotZLib/UnitTests.cs
     2         -compat/zlib/contrib/vstudio/readme.txt
     3         -compat/zlib/contrib/vstudio/*/zlib.rc
     4         -compat/zlib/win32/*.txt
     5         -compat/zlib/win64/*.txt
     6         -libtommath/*.dsp
     7         -libtommath/*.sln
     8         -libtommath/*.vcproj
     9         -tools/tcl.hpj.in
    10         -tools/tcl.wse.in
    11         -win/buildall.vc.bat
    12         -win/coffbase.txt
    13         -win/makefile.vc
    14         -win/rules.vc
    15         -win/rules-ext.vc
    16         -win/targets.vc
    17         -win/tcl.dsp
    18         -win/tcl.dsw
    19         -win/tcl.hpj.in

Changes to .fossil-settings/ignore-glob.

    15     15   */config.log
    16     16   */config.status
    17     17   */tclConfig.sh
    18     18   */tclsh*
    19     19   */tcltest*
    20     20   */versions.vc
    21     21   */version.vc
           22  +*/libtcl.vfs
           23  +*/libtcl_*.zip
    22     24   html
    23     25   libtommath/bn.ilg
    24     26   libtommath/bn.ind
    25     27   libtommath/pretty.build
    26     28   libtommath/tommath.src
           29  +libtommath/*.log
    27     30   libtommath/*.pdf
    28     31   libtommath/*.pl
    29     32   libtommath/*.sh
           33  +libtommath/doc/*
    30     34   libtommath/tombc/*
    31     35   libtommath/pre_gen/*
    32     36   libtommath/pics/*
    33     37   libtommath/mtest/*
    34     38   libtommath/logs/*
    35     39   libtommath/etc/*
    36     40   libtommath/demo/*

Added .github/ISSUE_TEMPLATE.md.

            1  +Important Note
            2  +==========
            3  +Please do not file issues with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.

Added .github/PULL_REQUEST_TEMPLATE.md.

            1  +Important Note
            2  +==========
            3  +Please do not file pull requests with Tcl on Github. They are unlikely to be noticed in a timely fashion. Tcl issues (including patches) are hosted in the [tcl fossil repository on core.tcl.tk](https://core.tcl.tk/tcl/tktnew); please post them there.

Added .travis.yml.

            1  +sudo: false
            2  +language: c
            3  +
            4  +matrix:
            5  +  include:
            6  +    - os: linux
            7  +      dist: xenial
            8  +      compiler: clang
            9  +      env:
           10  +        - BUILD_DIR=unix
           11  +    - os: linux
           12  +      dist: xenial
           13  +      compiler: clang
           14  +      env:
           15  +        - CFGOPT=--disable-shared
           16  +        - BUILD_DIR=unix
           17  +    - os: linux
           18  +      dist: xenial
           19  +      compiler: gcc
           20  +      env:
           21  +        - BUILD_DIR=unix
           22  +    - os: linux
           23  +      dist: xenial
           24  +      compiler: gcc
           25  +      env:
           26  +        - CFGOPT=--disable-shared
           27  +        - BUILD_DIR=unix
           28  +    - os: linux
           29  +      dist: xenial
           30  +      compiler: gcc-4.9
           31  +      addons:
           32  +        apt:
           33  +          sources:
           34  +            - ubuntu-toolchain-r-test
           35  +          packages:
           36  +            - g++-4.9
           37  +      env:
           38  +        - BUILD_DIR=unix
           39  +    - os: linux
           40  +      dist: xenial
           41  +      compiler: gcc-5
           42  +      addons:
           43  +        apt:
           44  +          sources:
           45  +            - ubuntu-toolchain-r-test
           46  +          packages:
           47  +            - g++-5
           48  +      env:
           49  +        - BUILD_DIR=unix
           50  +    - os: linux
           51  +      dist: xenial
           52  +      compiler: gcc-6
           53  +      addons:
           54  +        apt:
           55  +          sources:
           56  +            - ubuntu-toolchain-r-test
           57  +          packages:
           58  +            - g++-6
           59  +      env:
           60  +        - BUILD_DIR=unix
           61  +    - os: linux
           62  +      dist: xenial
           63  +      compiler: gcc-7
           64  +      addons:
           65  +        apt:
           66  +          sources:
           67  +            - ubuntu-toolchain-r-test
           68  +          packages:
           69  +            - g++-7
           70  +      env:
           71  +        - BUILD_DIR=unix
           72  +    - os: linux
           73  +      dist: xenial
           74  +      compiler: gcc-7
           75  +      addons:
           76  +        apt:
           77  +          sources:
           78  +            - ubuntu-toolchain-r-test
           79  +          packages:
           80  +            - g++-7
           81  +      env:
           82  +        - BUILD_DIR=unix
           83  +        - CFGOPT=CFLAGS=-DTCL_UTF_MAX=6
           84  +    - os: linux
           85  +      dist: xenial
           86  +      compiler: gcc-7
           87  +      addons:
           88  +        apt:
           89  +          sources:
           90  +            - ubuntu-toolchain-r-test
           91  +          packages:
           92  +            - g++-7
           93  +      env:
           94  +        - BUILD_DIR=unix
           95  +        - CFGOPT=CFLAGS=-DTCL_UTF_MAX=3
           96  +    - os: linux
           97  +      dist: xenial
           98  +      compiler: gcc-7
           99  +      addons:
          100  +        apt:
          101  +          sources:
          102  +            - ubuntu-toolchain-r-test
          103  +          packages:
          104  +            - g++-7
          105  +      env:
          106  +        - BUILD_DIR=unix
          107  +        - CFGOPT=CFLAGS=-DTCL_NO_DEPRECATED=1
          108  +    - os: osx
          109  +      osx_image: xcode8
          110  +      env:
          111  +        - BUILD_DIR=unix
          112  +    - os: osx
          113  +      osx_image: xcode8
          114  +      env:
          115  +        - BUILD_DIR=macosx
          116  +        - NO_DIRECT_CONFIGURE=1
          117  +    - os: osx
          118  +      osx_image: xcode9
          119  +      env:
          120  +        - BUILD_DIR=macosx
          121  +        - NO_DIRECT_CONFIGURE=1
          122  +    - os: osx
          123  +      osx_image: xcode10.2
          124  +      env:
          125  +        - BUILD_DIR=macosx
          126  +        - NO_DIRECT_CONFIGURE=1
          127  +### C builds not currently supported on Windows instances
          128  +#    - os: windows
          129  +#      env:
          130  +#        - BUILD_DIR=win
          131  +### ... so proxy with a Mingw cross-compile
          132  +# Test with mingw-w64 (32 bit)
          133  +    - os: linux
          134  +      dist: xenial
          135  +      compiler: i686-w64-mingw32-gcc
          136  +      addons:
          137  +        apt:
          138  +          packages:
          139  +            - gcc-mingw-w64-base
          140  +            - binutils-mingw-w64-i686
          141  +            - gcc-mingw-w64-i686
          142  +            - gcc-mingw-w64
          143  +            - gcc-multilib
          144  +            - wine
          145  +      env:
          146  +        - BUILD_DIR=win
          147  +        - CFGOPT=--host=i686-w64-mingw32
          148  +        - NO_DIRECT_TEST=1
          149  +    - os: linux
          150  +      dist: xenial
          151  +      compiler: i686-w64-mingw32-gcc
          152  +      addons:
          153  +        apt:
          154  +          packages:
          155  +            - gcc-mingw-w64-base
          156  +            - binutils-mingw-w64-i686
          157  +            - gcc-mingw-w64-i686
          158  +            - gcc-mingw-w64
          159  +            - gcc-multilib
          160  +            - wine
          161  +      env:
          162  +        - BUILD_DIR=win
          163  +        - CFGOPT="--host=i686-w64-mingw32 --disable-shared"
          164  +        - NO_DIRECT_TEST=1
          165  +    - os: linux
          166  +      dist: xenial
          167  +      compiler: i686-w64-mingw32-gcc
          168  +      addons:
          169  +        apt:
          170  +          packages:
          171  +            - gcc-mingw-w64-base
          172  +            - binutils-mingw-w64-i686
          173  +            - gcc-mingw-w64-i686
          174  +            - gcc-mingw-w64
          175  +            - gcc-multilib
          176  +            - wine
          177  +      env:
          178  +        - BUILD_DIR=win
          179  +        - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_UTF_MAX=6"
          180  +        - NO_DIRECT_TEST=1
          181  +    - os: linux
          182  +      dist: xenial
          183  +      compiler: i686-w64-mingw32-gcc
          184  +      addons:
          185  +        apt:
          186  +          packages:
          187  +            - gcc-mingw-w64-base
          188  +            - binutils-mingw-w64-i686
          189  +            - gcc-mingw-w64-i686
          190  +            - gcc-mingw-w64
          191  +            - gcc-multilib
          192  +            - wine
          193  +      env:
          194  +        - BUILD_DIR=win
          195  +        - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_UTF_MAX=3"
          196  +        - NO_DIRECT_TEST=1
          197  +    - os: linux
          198  +      dist: xenial
          199  +      compiler: i686-w64-mingw32-gcc
          200  +      addons:
          201  +        apt:
          202  +          packages:
          203  +            - gcc-mingw-w64-base
          204  +            - binutils-mingw-w64-i686
          205  +            - gcc-mingw-w64-i686
          206  +            - gcc-mingw-w64
          207  +            - gcc-multilib
          208  +            - wine
          209  +      env:
          210  +        - BUILD_DIR=win
          211  +        - CFGOPT="--host=i686-w64-mingw32 CFLAGS=-DTCL_NO_DEPRECATED=1"
          212  +        - NO_DIRECT_TEST=1
          213  +# Test with mingw-w64 (64 bit)
          214  +    - os: linux
          215  +      dist: xenial
          216  +      compiler: x86_64-w64-mingw32-gcc
          217  +      addons:
          218  +        apt:
          219  +          packages:
          220  +            - gcc-mingw-w64-base
          221  +            - binutils-mingw-w64-x86-64
          222  +            - gcc-mingw-w64-x86-64
          223  +            - gcc-mingw-w64
          224  +            - wine
          225  +      env:
          226  +        - BUILD_DIR=win
          227  +        - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit"
          228  +        - NO_DIRECT_TEST=1
          229  +    - os: linux
          230  +      dist: xenial
          231  +      compiler: x86_64-w64-mingw32-gcc
          232  +      addons:
          233  +        apt:
          234  +          packages:
          235  +            - gcc-mingw-w64-base
          236  +            - binutils-mingw-w64-x86-64
          237  +            - gcc-mingw-w64-x86-64
          238  +            - gcc-mingw-w64
          239  +            - wine
          240  +      env:
          241  +        - BUILD_DIR=win
          242  +        - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit --disable-shared"
          243  +        - NO_DIRECT_TEST=1
          244  +    - os: linux
          245  +      dist: xenial
          246  +      compiler: x86_64-w64-mingw32-gcc
          247  +      addons:
          248  +        apt:
          249  +          packages:
          250  +            - gcc-mingw-w64-base
          251  +            - binutils-mingw-w64-x86-64
          252  +            - gcc-mingw-w64-x86-64
          253  +            - gcc-mingw-w64
          254  +            - wine
          255  +      env:
          256  +        - BUILD_DIR=win
          257  +        - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_UTF_MAX=6"
          258  +        - NO_DIRECT_TEST=1
          259  +    - os: linux
          260  +      dist: xenial
          261  +      compiler: x86_64-w64-mingw32-gcc
          262  +      addons:
          263  +        apt:
          264  +          packages:
          265  +            - gcc-mingw-w64-base
          266  +            - binutils-mingw-w64-x86-64
          267  +            - gcc-mingw-w64-x86-64
          268  +            - gcc-mingw-w64
          269  +            - wine
          270  +      env:
          271  +        - BUILD_DIR=win
          272  +        - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_UTF_MAX=3"
          273  +        - NO_DIRECT_TEST=1
          274  +    - os: linux
          275  +      dist: xenial
          276  +      compiler: x86_64-w64-mingw32-gcc
          277  +      addons:
          278  +        apt:
          279  +          packages:
          280  +            - gcc-mingw-w64-base
          281  +            - binutils-mingw-w64-x86-64
          282  +            - gcc-mingw-w64-x86-64
          283  +            - gcc-mingw-w64
          284  +            - wine
          285  +      env:
          286  +        - BUILD_DIR=win
          287  +        - CFGOPT="--host=x86_64-w64-mingw32 --enable-64bit CFLAGS=-DTCL_NO_DEPRECATED=1"
          288  +        - NO_DIRECT_TEST=1
          289  +before_install:
          290  +  - export ERROR_ON_FAILURES=1
          291  +  - cd ${BUILD_DIR}
          292  +install:
          293  +  - test -n "$NO_DIRECT_CONFIGURE" || ./configure ${CFGOPT}
          294  +script:
          295  +  - make
          296  +  # The styles=develop avoids some weird problems on OSX
          297  +  - test -n "$NO_DIRECT_TEST" || make test styles=develop

Changes to ChangeLog.

     1      1   A NOTE ON THE CHANGELOG:
     2      2   Starting in early 2011, Tcl source code has been under the management of
     3         -fossil, hosted at http://core.tcl.tk/tcl/ .  Fossil presents a "Timeline"
            3  +fossil, hosted at https://core.tcl-lang.org/tcl/ .  Fossil presents a "Timeline"
     4      4   view of changes made that is superior in every way to a hand edited log file.
     5      5   Because of this, many Tcl developers are now out of the habit of maintaining
     6      6   this log file.  You may still find useful things in it, but the Timeline is
     7      7   a better first place to look now.
     8      8   ============================================================================
     9      9   
    10     10   2013-09-19  Don Porter  <[email protected]>

Changes to ChangeLog.2007.

  1422   1422   	an expr syntax error (masked by a [catch]).
  1423   1423   
  1424   1424   	* generic/tclCompCmds.c (TclCompileReturnCmd):	Added crash protection
  1425   1425   	to handle callers other than TclCompileScript() failing to meet the
  1426   1426   	initialization assumptions of the TIP 280 code in CompileWord().
  1427   1427   
  1428   1428   	* generic/tclCompExpr.c:	Suppress the attempt to convert to
  1429         -	numeric when pre-compiling a constant expresion indicates an error.
         1429  +	numeric when pre-compiling a constant expression indicates an error.
  1430   1430   
  1431   1431   2007-08-22  Miguel Sofer  <[email protected]>
  1432   1432   
  1433   1433   	* generic/tclExecute.c (TEBC): disable the new shortcut to frequent
  1434   1434   	INSTs for debug builds. REVERTED (collision with alternative fix)
  1435   1435   
  1436   1436   2007-08-21  Don Porter	<[email protected]>

Name change from README to README.md.

     1         -README:  Tcl
     2         -    This is the Tcl 9.0a0 source distribution.
     3         -	http://sourceforge.net/projects/tcl/files/Tcl/
     4         -    You can get any source release of Tcl from the URL above.
     5         -
     6         -Contents
     7         ---------
     8         -    1. Introduction
     9         -    2. Documentation
    10         -    3. Compiling and installing Tcl
    11         -    4. Development tools
    12         -    5. Tcl newsgroup
    13         -    6. The Tcler's Wiki
    14         -    7. Mailing lists
    15         -    8. Support and Training
    16         -    9. Tracking Development
    17         -    10. Thank You
    18         -
    19         -1. Introduction
    20         ----------------
            1  +# README:  Tcl
            2  +
            3  +This is the **Tcl 9.0a0** source distribution.
            4  +
            5  +You can get any source release of Tcl from [our distribution
            6  +site](https://sourceforge.net/projects/tcl/files/Tcl/).
            7  +
            8  +[![Build Status](https://travis-ci.org/tcltk/tcl.svg?branch=master)](https://travis-ci.org/tcltk/tcl)
            9  +
           10  +## Contents
           11  + 1. [Introduction](#intro)
           12  + 2. [Documentation](#doc)
           13  + 3. [Compiling and installing Tcl](#build)
           14  + 4. [Development tools](#devtools)
           15  + 5. [Tcl newsgroup](#complangtcl)
           16  + 6. [The Tcler's Wiki](#wiki)
           17  + 7. [Mailing lists](#email)
           18  + 8. [Support and Training](#support)
           19  + 9. [Tracking Development](#watch)
           20  + 10. [Thank You](#thanks)
           21  +
           22  +## <a id="intro">1.</a> Introduction
    21     23   Tcl provides a powerful platform for creating integration applications that
    22     24   tie together diverse applications, protocols, devices, and frameworks.
    23     25   When paired with the Tk toolkit, Tcl provides the fastest and most powerful
    24     26   way to create GUI applications that run on PCs, Unix, and Mac OS X.
    25     27   Tcl can also be used for a variety of web-related tasks and for creating
    26     28   powerful command languages for applications.
    27     29   
    28     30   Tcl is maintained, enhanced, and distributed freely by the Tcl community.
    29     31   Source code development and tracking of bug reports and feature requests
    30         -takes place at:
    31         -
    32         -	http://core.tcl.tk/
    33         -
    34         -Tcl/Tk release and mailing list services are hosted by SourceForge:
    35         -
    36         -	http://sourceforge.net/projects/tcl/
    37         -
    38         -with the Tcl Developer Xchange hosted at:
    39         -
    40         -	http://www.tcl.tk/
           32  +takes place at [core.tcl-lang.org](https://core.tcl-lang.org/).
           33  +Tcl/Tk release and mailing list services are [hosted by
           34  +SourceForge](https://sourceforge.net/projects/tcl/)
           35  +with the Tcl Developer Xchange hosted at
           36  +[www.tcl-lang.org](https://www.tcl-lang.org).
    41     37   
    42     38   Tcl is a freely available open source package.  You can do virtually
    43     39   anything you like with it, such as modifying it, redistributing it,
    44     40   and selling it either in whole or in part.  See the file
    45         -"license.terms" for complete information.
           41  +`license.terms` for complete information.
    46     42   
    47         -2. Documentation
    48         -----------------
    49         -
           43  +## <a id="doc">2.</a> Documentation
    50     44   Extensive documentation is available at our website.
    51     45   The home page for this release, including new features, is
    52         -	http://www.tcl.tk/software/tcltk/9.0.html
    53         -
    54         -Detailed release notes can be found at the file distributions page
           46  +[here](https://www.tcl.tk/software/tcltk/9.0.html).
           47  +Detailed release notes can be found at the
           48  +[file distributions page](https://sourceforge.net/projects/tcl/files/Tcl/)
    55     49   by clicking on the relevant version.
    56         -	http://sourceforge.net/projects/tcl/files/Tcl/
    57     50   
    58         -Information about Tcl itself can be found at
    59         -	http://www.tcl.tk/about/
           51  +Information about Tcl itself can be found at the [Developer
           52  +Xchange](https://www.tcl-lang.org/about/).
           53  +There have been many Tcl books on the market.  Many are mentioned in
           54  +[the Wiki](https://wiki.tcl-lang.org/_/ref?N=25206).
    60     55   
    61         -There have been many Tcl books on the market.  Many are mentioned in the Wiki:
    62         -	http://wiki.tcl.tk/_/ref?N=25206
           56  +The complete set of reference manual entries for Tcl 9.0 is [online,
           57  +here](https://www.tcl-lang.org/man/tcl9.0/).
    63     58   
    64         -To view the complete set of reference manual entries for Tcl 9.0 online,
    65         -visit the URL:
    66         -	http://www.tcl.tk/man/tcl9.0/
    67         -
    68         -2a. Unix Documentation
    69         -----------------------
    70         -
    71         -The "doc" subdirectory in this release contains a complete set of
    72         -reference manual entries for Tcl.  Files with extension ".1" are for
    73         -programs (for example, tclsh.1); files with extension ".3" are for C
    74         -library procedures; and files with extension ".n" describe Tcl
    75         -commands.  The file "doc/Tcl.n" gives a quick summary of the Tcl
           59  +### <a id="doc.unix">2a.</a> Unix Documentation
           60  +The `doc` subdirectory in this release contains a complete set of
           61  +reference manual entries for Tcl.  Files with extension "`.1`" are for
           62  +programs (for example, `tclsh.1`); files with extension "`.3`" are for C
           63  +library procedures; and files with extension "`.n`" describe Tcl
           64  +commands.  The file "`doc/Tcl.n`" gives a quick summary of the Tcl
    76     65   language syntax.  To print any of the man pages on Unix, cd to the
    77     66   "doc" directory and invoke your favorite variant of troff using the
    78     67   normal -man macros, for example
    79     68   
    80         -		ditroff -man Tcl.n
           69  +		groff -man -Tpdf Tcl.n >output.pdf
    81     70   
    82         -to print Tcl.n.  If Tcl has been installed correctly and your "man" program
           71  +to print Tcl.n to PDF.  If Tcl has been installed correctly and your "man" program
    83     72   supports it, you should be able to access the Tcl manual entries using the
    84     73   normal "man" mechanisms, such as
    85     74   
    86     75   		man Tcl
    87     76   
    88         -2b. Windows Documentation
    89         --------------------------
    90         -
           77  +### <a id="doc.win">2b.</a> Windows Documentation
    91     78   The "doc" subdirectory in this release contains a complete set of Windows
    92     79   help files for Tcl.  Once you install this Tcl release, a shortcut to the
    93     80   Windows help Tcl documentation will appear in the "Start" menu:
    94     81   
    95         -	Start | Programs | Tcl | Tcl Help
           82  +		Start | Programs | Tcl | Tcl Help
    96     83   
    97         -3. Compiling and installing Tcl
    98         --------------------------------
    99         -
   100         -There are brief notes in the unix/README, win/README, and macosx/README about
   101         -compiling on these different platforms.  There is additional information
   102         -about building Tcl from sources at
           84  +## <a id="build">3.</a> Compiling and installing Tcl
           85  +There are brief notes in the `unix/README`, `win/README`, and `macosx/README`
           86  +about compiling on these different platforms.  There is additional information
           87  +about building Tcl from sources
           88  +[online](https://www.tcl-lang.org/doc/howto/compile.html).
   103     89   
   104         -	http://www.tcl.tk/doc/howto/compile.html
   105         -
   106         -4. Development tools
   107         ----------------------------
   108         -
           90  +## <a id="devtools">4.</a> Development tools
   109     91   ActiveState produces a high quality set of commercial quality development
   110     92   tools that is available to accelerate your Tcl application development.
   111     93   Tcl Dev Kit builds on the earlier TclPro toolset and provides a debugger,
   112     94   static code checker, single-file wrapping utility, bytecode compiler and
   113     95   more.  More information can be found at
   114     96   
   115     97   	http://www.ActiveState.com/Tcl
   116     98   
   117         -5. Tcl newsgroup
   118         -----------------
   119         -
   120         -There is a USENET news group, "comp.lang.tcl", intended for the exchange of
           99  +## <a id="complangtcl">5.</a> Tcl newsgroup
          100  +There is a USENET news group, "`comp.lang.tcl`", intended for the exchange of
   121    101   information about Tcl, Tk, and related applications.  The newsgroup is a
   122    102   great place to ask general information questions.  For bug reports, please
   123    103   see the "Support and bug fixes" section below.
   124    104   
   125         -6. Tcl'ers Wiki
   126         ----------------
   127         -
   128         -A Wiki-based open community site covering all aspects of Tcl/Tk is at:
   129         -
   130         -	http://wiki.tcl.tk/
          105  +## <a id="wiki">6.</a> Tcl'ers Wiki
          106  +There is a [wiki-based open community site](https://wiki.tcl-lang.org/)
          107  +covering all aspects of Tcl/Tk.
   131    108   
   132    109   It is dedicated to the Tcl programming language and its extensions.  A
   133    110   wealth of useful information can be found there.  It contains code
   134    111   snippets, references to papers, books, and FAQs, as well as pointers to
   135    112   development tools, extensions, and applications.  You can also recommend
   136    113   additional URLs by editing the wiki yourself.
   137    114   
   138         -7. Mailing lists
   139         -----------------
   140         -
   141         -Several mailing lists are hosted at SourceForge to discuss development or
   142         -use issues (like Macintosh and Windows topics).  For more information and
   143         -to subscribe, visit:
          115  +## <a id="email">7.</a> Mailing lists
          116  +Several mailing lists are hosted at SourceForge to discuss development or use
          117  +issues (like Macintosh and Windows topics).  For more information and to
          118  +subscribe, visit [here](https://sourceforge.net/projects/tcl/) and go to the
          119  +Mailing Lists page.
   144    120   
   145         -	http://sourceforge.net/projects/tcl/
   146         -
   147         -and go to the Mailing Lists page.
   148         -
   149         -8. Support and Training
   150         -------------------------
   151         -
   152         -We are very interested in receiving bug reports, patches, and suggestions
   153         -for improvements.  We prefer that you send this information to us as
   154         -tickets entered into our tracker at:
   155         -
   156         -	http://core.tcl.tk/tcl/reportlist
          121  +## <a id="support">8.</a> Support and Training
          122  +We are very interested in receiving bug reports, patches, and suggestions for
          123  +improvements.  We prefer that you send this information to us as tickets
          124  +entered into [our issue tracker](https://core.tcl-lang.org/tcl/reportlist).
   157    125   
   158    126   We will log and follow-up on each bug, although we cannot promise a
   159    127   specific turn-around time.  Enhancements may take longer and may not happen
   160    128   at all unless there is widespread support for them (we're trying to
   161    129   slow the rate at which Tcl/Tk turns into a kitchen sink).  It's very
   162    130   difficult to make incompatible changes to Tcl/Tk at this point, due to
   163    131   the size of the installed base.
   164    132   
   165         -The Tcl community is too large for us to provide much individual support
   166         -for users.  If you need help we suggest that you post questions to
   167         -comp.lang.tcl.  We read the newsgroup and will attempt to answer esoteric
   168         -questions for which no one else is likely to know the answer.  In addition,
   169         -see the following Web site for links to other organizations that offer
   170         -Tcl/Tk training:
          133  +The Tcl community is too large for us to provide much individual support for
          134  +users.  If you need help we suggest that you post questions to `comp.lang.tcl`
          135  +or ask a question on [Stack
          136  +Overflow](https://stackoverflow.com/questions/tagged/tcl).  We read the
          137  +newsgroup and will attempt to answer esoteric questions for which no one else
          138  +is likely to know the answer.  In addition, see the wiki for [links to other
          139  +organizations](https://wiki.tcl-lang.org/training) that offer Tcl/Tk training.
   171    140   
   172         -	http://wiki.tcl.tk/training
   173         -
   174         -9. Tracking Development
   175         ------------------------
          141  +## <a id="watch">9.</a> Tracking Development
          142  +Tcl is developed in public.  You can keep an eye on how Tcl is changing at
          143  +[core.tcl-lang.org](https://core.tcl-lang.org/).
   176    144   
   177         -Tcl is developed in public.  To keep an eye on how Tcl is changing, see
   178         -	http://core.tcl.tk/
   179         -
   180         -10. Thank You
   181         --------------
   182         -
          145  +## <a id="thanks">10.</a> Thank You
   183    146   We'd like to express our thanks to the Tcl community for all the
   184    147   helpful suggestions, bug reports, and patches we have received.
   185    148   Tcl/Tk has improved vastly and will continue to do so with your help.

Changes to changes.

  8827   8827   
  8828   8828   2017-12-08 (new)[TIP 477] nmake build system reform (nadkarni)
  8829   8829   
  8830   8830   2017-12-19 (bug)[586e71] EvalObjv exception handling at level #0 (sebres,porter)
  8831   8831   
  8832   8832   --- Released 8.6.8, December 22, 2017 --- http://core.tcl.tk/tcl/ for details
  8833   8833   
         8834  +2018-02-11 (enhance) stop blocking conversion of object to/from class (coulter)
         8835  +
         8836  +2018-02-12 (enhance) NR-enable [package require] (coulter)
         8837  +
         8838  +2018-02-14 (bug)[9fd5c6] crash in object deletion, test oo-11.5 (coulter)
         8839  +
         8840  +2018-02-14 (bug)[3c32a3] crash deleting object with class mixed in (coulter)
         8841  +
         8842  +2018-02-15 (platform) stop using -lieee, removed from glibc-2.27 (porter)
         8843  +***POTENTIAL INCOMPATIBILITY for math programs that embed Tcl***
         8844  +
         8845  +2018-02-23 (bug)[8e6a9a] bad binary [string match], test string-11.55 (porter)
         8846  +
         8847  +2018-03-05 (bug)[1873ea] repair multi-thread std channel init (sebres)
         8848  +
         8849  +2018-03-09 (bug)[db36fa] broken bytecode for index values (porter)
         8850  +
         8851  +2018-03-13 (bug) broken compiled [string replace], test string-14.19 (porter)
         8852  +
         8853  +2018-03-14 (bug) [string trim*] engine crashed on invalid UTF (sebres)
         8854  +
         8855  +2018-04-17 (bug) missing trace in compiled [array set], test var-20.11 (porter)
         8856  +
         8857  +2018-04-22 (bug)[46a241] crash in unset array with search, var-13.[23] (goth)
         8858  +
         8859  +2018-04-30 (bug)[27b682] race made [file delete] raise "no such file" (sebres)
         8860  +
         8861  +2018-06-04 (bug)[925643] 32/64 cleanup of filesystem DIR operations (sebres)
         8862  +
         8863  +2018-06-18 (bug) leaks in TclSetEnv and env cache (coulter)
         8864  +
         8865  +2018-06-24 (bug)[3592747] [yieldto] dying namespace, tailcall-14.1 (coulter)
         8866  +
         8867  +2018-07-09 (bug)[270f78] race in [file mkdir] (sebres)
         8868  +
         8869  +2018-07-12 (bug)[3f7af0] [file delete] raised "permission denied" (sebres)
         8870  +
         8871  +2018-07-26 (bug)[d051b7] overflow crash in [format] (sebres)
         8872  +
         8873  +2018-08-29 revised quoting of [exec] args in generated command line (sebres)
         8874  +***POTENTIAL INCOMPATIBILITY***
         8875  +
         8876  +2018-09-20 HTTP Keep-Alive with pipelined requests (nash)
         8877  +=> http 2.9.0
         8878  +
         8879  +2018-09-27 (new)[TIP 505] [lreplace] accepts all out of range indices (porter)
         8880  +
         8881  +2018-10-04 (bug) Prevent crash from NULL keyName (nijtmans)
         8882  +=> registry 1.3.3
         8883  +
         8884  +2018-10-26 (enhance) advance dde version (nijtmans)
         8885  +=> dde 1.4.1
         8886  +
         8887  +2018-10-27 tzdata updated to Olson's tzdata2018g (jima)
         8888  +
         8889  +2018-10-29 Update tcltest package for Travis support (fellows)
         8890  +=> tcltest 2.5.0
         8891  +
         8892  +2018-11-09 (bug)[35a8f1] overlong string length of some lists (owens)
         8893  +
         8894  +2018-11-16 (bug)[00d04c] Repair [binary encode base64] (sebres)
         8895  +
         8896  +- Released 8.6.9, November 16, 2018 - details at http://core.tcl-lang.org/tcl/ -
         8897  +
  8834   8898   Changes to 8.7a1 include all changes to the 8.6 line through 8.6.7,
  8835   8899   plus the following, which focuses on the high-level feature changes
  8836   8900   in this changeset (new minor version) rather than bug fixes:
  8837   8901   
  8838   8902   2016-03-17 (bug)[0b8c38] socket accept callbacks always in global ns (porter)
  8839   8903           *** POTENTIAL INCOMPATIBILITY ***
  8840   8904   
................................................................................
  8845   8909   2016-07-19 (bug)[0363f0] Partial array search ID reform (porter)
  8846   8910   
  8847   8911   2016-07-19 (feature removed) Tcl_ObjType "array search" unregistered (porter)
  8848   8912   	*** POTENTIAL INCOMPATIBILITY for Tcl_GetObjType("array search") ***
  8849   8913   
  8850   8914   2016-10-04 Server socket on port 0 chooses port supporting IPv4 * IPv6 (max)
  8851   8915   
  8852         -2016-11-25 [array named -regexp] supports backrefs (goth)
         8916  +2016-11-25 [array names -regexp] supports backrefs (goth)
  8853   8917   
  8854   8918   2017-01-04 (TIP 456) New routine Tcl_OpenTcpServerEx() (limeboy)
  8855   8919   
  8856   8920   2017-01-04 (TIP 459) New subcommand [package files] (nijtmans)
  8857   8921   
  8858   8922   2017-01-16 threaded allocator initialization repair (vasiljevic,nijtmans)
  8859   8923   
................................................................................
  8880   8944   
  8881   8945   --- Released 8.7a1, September 8, 2017 --- http://core.tcl.tk/tcl/ for details
  8882   8946   
  8883   8947   2018-03-12 (TIP 490) add oo support for msgcat => msgcat 1.7.0 (oehlmann)
  8884   8948   
  8885   8949   2018-03-12 (TIP 499) custom locale preference list (oehlmann)
  8886   8950   => msgcat 1.7.0
         8951  +
         8952  +- Released 8.7a3, Nov 30, 2018 --- http://core.tcl-lang.org/tcl/ for details -

Deleted compat/fixstrtod.c.

     1         -/*
     2         - * fixstrtod.c --
     3         - *
     4         - *	Source code for the "fixstrtod" procedure.  This procedure is
     5         - *	used in place of strtod under Solaris 2.4, in order to fix
     6         - *	a bug where the "end" pointer gets set incorrectly.
     7         - *
     8         - * Copyright (c) 1995 Sun Microsystems, Inc.
     9         - *
    10         - * See the file "license.terms" for information on usage and redistribution
    11         - * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    12         - */
    13         -
    14         -#include <stdio.h>
    15         -
    16         -#undef strtod
    17         -
    18         -/*
    19         - * Declare strtod explicitly rather than including stdlib.h, since in
    20         - * somes systems (e.g. SunOS 4.1.4) stdlib.h doesn't declare strtod.
    21         - */
    22         -
    23         -extern double strtod(char *, char **);
    24         -
    25         -double
    26         -fixstrtod(
    27         -    char *string,
    28         -    char **endPtr)
    29         -{
    30         -    double d;
    31         -    d = strtod(string, endPtr);
    32         -    if ((endPtr != NULL) && (*endPtr != string) && ((*endPtr)[-1] == 0)) {
    33         -	*endPtr -= 1;
    34         -    }
    35         -    return d;
    36         -}

Changes to compat/opendir.c.

    24     24       register int fd;
    25     25       char *myname;
    26     26   
    27     27       myname = ((*name == '\0') ? "." : name);
    28     28       if ((fd = open(myname, 0, 0)) == -1) {
    29     29   	return NULL;
    30     30       }
    31         -    dirp = (DIR *) ckalloc(sizeof(DIR));
           31  +    dirp = (DIR *) Tcl_Alloc(sizeof(DIR));
    32     32       if (dirp == NULL) {
    33     33   	/* unreachable? */
    34     34   	close(fd);
    35     35   	return NULL;
    36     36       }
    37     37       dirp->dd_fd = fd;
    38     38       dirp->dd_loc = 0;
................................................................................
   102    102   void
   103    103   closedir(
   104    104       register DIR *dirp)
   105    105   {
   106    106       close(dirp->dd_fd);
   107    107       dirp->dd_fd = -1;
   108    108       dirp->dd_loc = 0;
   109         -    ckfree(dirp);
          109  +    Tcl_Free(dirp);
   110    110   }

Changes to compat/stdlib.h.

    25     25   extern void		exit(int status);
    26     26   extern int		free(char *blockPtr);
    27     27   extern char *		getenv(const char *name);
    28     28   extern char *		malloc(unsigned int numBytes);
    29     29   extern void		qsort(void *base, int n, int size, int (*compar)(
    30     30   			    const void *element1, const void *element2));
    31     31   extern char *		realloc(char *ptr, unsigned int numBytes);
    32         -extern double		strtod(const char *string, char **endPtr);
    33     32   extern long		strtol(const char *string, char **endPtr, int base);
    34     33   extern unsigned long	strtoul(const char *string, char **endPtr, int base);
    35     34   
    36     35   #endif /* _STDLIB */

Deleted compat/strtod.c.

     1         -/*
     2         - * strtod.c --
     3         - *
     4         - *	Source code for the "strtod" library procedure.
     5         - *
     6         - * Copyright (c) 1988-1993 The Regents of the University of California.
     7         - * Copyright (c) 1994 Sun Microsystems, Inc.
     8         - *
     9         - * See the file "license.terms" for information on usage and redistribution
    10         - * of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    11         - */
    12         -
    13         -#include "tclInt.h"
    14         -
    15         -#ifndef TRUE
    16         -#define TRUE 1
    17         -#define FALSE 0
    18         -#endif
    19         -#ifndef NULL
    20         -#define NULL 0
    21         -#endif
    22         -
    23         -static const int maxExponent = 511;	/* Largest possible base 10 exponent.  Any
    24         -				 * exponent larger than this will already
    25         -				 * produce underflow or overflow, so there's
    26         -				 * no need to worry about additional digits.
    27         -				 */
    28         -static const double powersOf10[] = {	/* Table giving binary powers of 10.  Entry */
    29         -    10.,			/* is 10^2^i.  Used to convert decimal */
    30         -    100.,			/* exponents into floating-point numbers. */
    31         -    1.0e4,
    32         -    1.0e8,
    33         -    1.0e16,
    34         -    1.0e32,
    35         -    1.0e64,
    36         -    1.0e128,
    37         -    1.0e256
    38         -};
    39         -
    40         -/*
    41         - *----------------------------------------------------------------------
    42         - *
    43         - * strtod --
    44         - *
    45         - *	This procedure converts a floating-point number from an ASCII
    46         - *	decimal representation to internal double-precision format.
    47         - *
    48         - * Results:
    49         - *	The return value is the double-precision floating-point
    50         - *	representation of the characters in string.  If endPtr isn't
    51         - *	NULL, then *endPtr is filled in with the address of the
    52         - *	next character after the last one that was part of the
    53         - *	floating-point number.
    54         - *
    55         - * Side effects:
    56         - *	None.
    57         - *
    58         - *----------------------------------------------------------------------
    59         - */
    60         -
    61         -double
    62         -strtod(
    63         -    const char *string,		/* A decimal ASCII floating-point number,
    64         -				 * optionally preceded by white space. Must
    65         -				 * have form "-I.FE-X", where I is the integer
    66         -				 * part of the mantissa, F is the fractional
    67         -				 * part of the mantissa, and X is the
    68         -				 * exponent. Either of the signs may be "+",
    69         -				 * "-", or omitted. Either I or F may be
    70         -				 * omitted, or both. The decimal point isn't
    71         -				 * necessary unless F is present. The "E" may
    72         -				 * actually be an "e". E and X may both be
    73         -				 * omitted (but not just one). */
    74         -    char **endPtr)		/* If non-NULL, store terminating character's
    75         -				 * address here. */
    76         -{
    77         -    int sign, expSign = FALSE;
    78         -    double fraction, dblExp;
    79         -    const double *d;
    80         -    register const char *p;
    81         -    register int c;
    82         -    int exp = 0;		/* Exponent read from "EX" field. */
    83         -    int fracExp = 0;		/* Exponent that derives from the fractional
    84         -				 * part. Under normal circumstatnces, it is
    85         -				 * the negative of the number of digits in F.
    86         -				 * However, if I is very long, the last digits
    87         -				 * of I get dropped (otherwise a long I with a
    88         -				 * large negative exponent could cause an
    89         -				 * unnecessary overflow on I alone). In this
    90         -				 * case, fracExp is incremented one for each
    91         -				 * dropped digit. */
    92         -    int mantSize;		/* Number of digits in mantissa. */
    93         -    int decPt;			/* Number of mantissa digits BEFORE decimal
    94         -				 * point. */
    95         -    const char *pExp;		/* Temporarily holds location of exponent in
    96         -				 * string. */
    97         -
    98         -    /*
    99         -     * Strip off leading blanks and check for a sign.
   100         -     */
   101         -
   102         -    p = string;
   103         -    while (isspace(UCHAR(*p))) {
   104         -	p += 1;
   105         -    }
   106         -    if (*p == '-') {
   107         -	sign = TRUE;
   108         -	p += 1;
   109         -    } else {
   110         -	if (*p == '+') {
   111         -	    p += 1;
   112         -	}
   113         -	sign = FALSE;
   114         -    }
   115         -
   116         -    /*
   117         -     * Count the number of digits in the mantissa (including the decimal
   118         -     * point), and also locate the decimal point.
   119         -     */
   120         -
   121         -    decPt = -1;
   122         -    for (mantSize = 0; ; mantSize += 1)
   123         -    {
   124         -	c = *p;
   125         -	if (!isdigit(c)) {
   126         -	    if ((c != '.') || (decPt >= 0)) {
   127         -		break;
   128         -	    }
   129         -	    decPt = mantSize;
   130         -	}
   131         -	p += 1;
   132         -    }
   133         -
   134         -    /*
   135         -     * Now suck up the digits in the mantissa. Use two integers to collect 9
   136         -     * digits each (this is faster than using floating-point). If the mantissa
   137         -     * has more than 18 digits, ignore the extras, since they can't affect the
   138         -     * value anyway.
   139         -     */
   140         -
   141         -    pExp  = p;
   142         -    p -= mantSize;
   143         -    if (decPt < 0) {
   144         -	decPt = mantSize;
   145         -    } else {
   146         -	mantSize -= 1;		/* One of the digits was the point. */
   147         -    }
   148         -    if (mantSize > 18) {
   149         -	fracExp = decPt - 18;
   150         -	mantSize = 18;
   151         -    } else {
   152         -	fracExp = decPt - mantSize;
   153         -    }
   154         -    if (mantSize == 0) {
   155         -	fraction = 0.0;
   156         -	p = string;
   157         -	goto done;
   158         -    } else {
   159         -	int frac1, frac2;
   160         -
   161         -	frac1 = 0;
   162         -	for ( ; mantSize > 9; mantSize -= 1) {
   163         -	    c = *p;
   164         -	    p += 1;
   165         -	    if (c == '.') {
   166         -		c = *p;
   167         -		p += 1;
   168         -	    }
   169         -	    frac1 = 10*frac1 + (c - '0');
   170         -	}
   171         -	frac2 = 0;
   172         -	for (; mantSize > 0; mantSize -= 1) {
   173         -	    c = *p;
   174         -	    p += 1;
   175         -	    if (c == '.') {
   176         -		c = *p;
   177         -		p += 1;
   178         -	    }
   179         -	    frac2 = 10*frac2 + (c - '0');
   180         -	}
   181         -	fraction = (1.0e9 * frac1) + frac2;
   182         -    }
   183         -
   184         -    /*
   185         -     * Skim off the exponent.
   186         -     */
   187         -
   188         -    p = pExp;
   189         -    if ((*p == 'E') || (*p == 'e')) {
   190         -	p += 1;
   191         -	if (*p == '-') {
   192         -	    expSign = TRUE;
   193         -	    p += 1;
   194         -	} else {
   195         -	    if (*p == '+') {
   196         -		p += 1;
   197         -	    }
   198         -	    expSign = FALSE;
   199         -	}
   200         -	if (!isdigit(UCHAR(*p))) {
   201         -	    p = pExp;
   202         -	    goto done;
   203         -	}
   204         -	while (isdigit(UCHAR(*p))) {
   205         -	    exp = exp * 10 + (*p - '0');
   206         -	    p += 1;
   207         -	}
   208         -    }
   209         -    if (expSign) {
   210         -	exp = fracExp - exp;
   211         -    } else {
   212         -	exp = fracExp + exp;
   213         -    }
   214         -
   215         -    /*
   216         -     * Generate a floating-point number that represents the exponent. Do this
   217         -     * by processing the exponent one bit at a time to combine many powers of
   218         -     * 2 of 10. Then combine the exponent with the fraction.
   219         -     */
   220         -
   221         -    if (exp < 0) {
   222         -	expSign = TRUE;
   223         -	exp = -exp;
   224         -    } else {
   225         -	expSign = FALSE;
   226         -    }
   227         -    if (exp > maxExponent) {
   228         -	exp = maxExponent;
   229         -	errno = ERANGE;
   230         -    }
   231         -    dblExp = 1.0;
   232         -    for (d = powersOf10; exp != 0; exp >>= 1, ++d) {
   233         -	if (exp & 01) {
   234         -	    dblExp *= *d;
   235         -	}
   236         -    }
   237         -    if (expSign) {
   238         -	fraction /= dblExp;
   239         -    } else {
   240         -	fraction *= dblExp;
   241         -    }
   242         -
   243         -  done:
   244         -    if (endPtr != NULL) {
   245         -	*endPtr = (char *) p;
   246         -    }
   247         -
   248         -    if (sign) {
   249         -	return -fraction;
   250         -    }
   251         -    return fraction;
   252         -}

Changes to compat/strtol.c.

    49     49       long result;
    50     50   
    51     51       /*
    52     52        * Skip any leading blanks.
    53     53        */
    54     54   
    55     55       p = string;
    56         -    while (isspace(UCHAR(*p))) {
           56  +    while (TclIsSpaceProc(*p)) {
    57     57   	p += 1;
    58     58       }
    59     59   
    60     60       /*
    61     61        * Check for a sign.
    62     62        */
    63     63   

Changes to compat/strtoul.c.

    70     70       int overflow=0;
    71     71   
    72     72       /*
    73     73        * Skip any leading blanks.
    74     74        */
    75     75   
    76     76       p = string;
    77         -    while (isspace(UCHAR(*p))) {
           77  +    while (TclIsSpaceProc(*p)) {
    78     78   	p += 1;
    79     79       }
    80     80       if (*p == '-') {
    81     81           negative = 1;
    82     82           p += 1;
    83     83       } else {
    84     84           if (*p == '+') {

Deleted compat/unistd.h.

     1         -/*
     2         - * unistd.h --
     3         - *
     4         - *      Macros, constants and prototypes for Posix conformance.
     5         - *
     6         - * Copyright 1989 Regents of the University of California Permission to use,
     7         - * copy, modify, and distribute this software and its documentation for any
     8         - * purpose and without fee is hereby granted, provided that the above
     9         - * copyright notice appear in all copies. The University of California makes
    10         - * no representations about the suitability of this software for any purpose.
    11         - * It is provided "as is" without express or implied warranty.
    12         - */
    13         -
    14         -#ifndef _UNISTD
    15         -#define _UNISTD
    16         -
    17         -#include <sys/types.h>
    18         -
    19         -#ifndef NULL
    20         -#define NULL    0
    21         -#endif
    22         -
    23         -/*
    24         - * Strict POSIX stuff goes here. Extensions go down below, in the ifndef
    25         - * _POSIX_SOURCE section.
    26         - */
    27         -
    28         -extern void		_exit(int status);
    29         -extern int		access(const char *path, int mode);
    30         -extern int		chdir(const char *path);
    31         -extern int		chown(const char *path, uid_t owner, gid_t group);
    32         -extern int		close(int fd);
    33         -extern int		dup(int oldfd);
    34         -extern int		dup2(int oldfd, int newfd);
    35         -extern int		execl(const char *path, ...);
    36         -extern int		execle(const char *path, ...);
    37         -extern int		execlp(const char *file, ...);
    38         -extern int		execv(const char *path, char **argv);
    39         -extern int		execve(const char *path, char **argv, char **envp);
    40         -extern int		execvpw(const char *file, char **argv);
    41         -extern pid_t		fork(void);
    42         -extern char *		getcwd(char *buf, size_t size);
    43         -extern gid_t		getegid(void);
    44         -extern uid_t		geteuid(void);
    45         -extern gid_t		getgid(void);
    46         -extern int		getgroups(int bufSize, int *buffer);
    47         -extern pid_t		getpid(void);
    48         -extern uid_t		getuid(void);
    49         -extern int		isatty(int fd);
    50         -extern long		lseek(int fd, long offset, int whence);
    51         -extern int		pipe(int *fildes);
    52         -extern int		read(int fd, char *buf, size_t size);
    53         -extern int		setgid(gid_t group);
    54         -extern int		setuid(uid_t user);
    55         -extern unsigned		sleep(unsigned seconds);
    56         -extern char *		ttyname(int fd);
    57         -extern int		unlink(const char *path);
    58         -extern int		write(int fd, const char *buf, size_t size);
    59         -
    60         -#ifndef	_POSIX_SOURCE
    61         -extern char *		crypt(const char *, const char *);
    62         -extern int		fchown(int fd, uid_t owner, gid_t group);
    63         -extern int		flock(int fd, int operation);
    64         -extern int		ftruncate(int fd, unsigned long length);
    65         -extern int		ioctl(int fd, int request, ...);
    66         -extern int		readlink(const char *path, char *buf, int bufsize);
    67         -extern int		setegid(gid_t group);
    68         -extern int		seteuidw(uid_t user);
    69         -extern int		setreuid(int ruid, int euid);
    70         -extern int		symlink(const char *, const char *);
    71         -extern int		ttyslot(void);
    72         -extern int		truncate(const char *path, unsigned long length);
    73         -extern int		vfork(void);
    74         -#endif /* _POSIX_SOURCE */
    75         -
    76         -#endif /* _UNISTD */

Changes to compat/waitpid.c.

    96     96   	result = waitPtr->pid;
    97     97   	*statusPtr = *((int *) &waitPtr->status);
    98     98   	if (prevPtr == NULL) {
    99     99   	    deadList = waitPtr->nextPtr;
   100    100   	} else {
   101    101   	    prevPtr->nextPtr = waitPtr->nextPtr;
   102    102   	}
   103         -	ckfree(waitPtr);
          103  +	Tcl_Free(waitPtr);
   104    104   	return result;
   105    105       }
   106    106   
   107    107       /*
   108    108        * Wait for any process to stop or exit. If it's an acceptable one then
   109    109        * return it to the caller; otherwise store information about it in the
   110    110        * list of exited processes and try again. On systems that have only wait
................................................................................
   152    152       saveInfo:
   153    153   	for (waitPtr = deadList; waitPtr != NULL; waitPtr = waitPtr->nextPtr) {
   154    154   	    if (waitPtr->pid == result) {
   155    155   		waitPtr->status = status;
   156    156   		goto waitAgain;
   157    157   	    }
   158    158   	}
   159         -	waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo));
          159  +	waitPtr = (WaitInfo *) Tcl_Alloc(sizeof(WaitInfo));
   160    160   	waitPtr->pid = result;
   161    161   	waitPtr->status = status;
   162    162   	waitPtr->nextPtr = deadList;
   163    163   	deadList = waitPtr;
   164    164   
   165    165       waitAgain:
   166    166   	continue;
   167    167       }
   168    168   }

Changes to compat/zlib/contrib/minizip/crypt.h.

    24     24   
    25     25      The new AES encryption added on Zip format by Winzip (see the page
    26     26      http://www.winzip.com/aes_info.htm ) and PKWare PKZip 5.x Strong
    27     27      Encryption is not supported.
    28     28   */
    29     29   
    30     30   #define CRC32(c, b) ((*(pcrc_32_tab+(((int)(c) ^ (b)) & 0xff))) ^ ((c) >> 8))
           31  +
           32  +#ifdef Z_U4
           33  +   typedef Z_U4 z_crc_t;
           34  +#else
           35  +   typedef unsigned long z_crc_t;
           36  +#endif
    31     37   
    32     38   /***********************************************************************
    33     39    * Return the next byte in the pseudo-random sequence
    34     40    */
    35     41   static int decrypt_byte(unsigned long* pkeys, const z_crc_t* pcrc_32_tab)
    36     42   {
    37     43       unsigned temp;  /* POTENTIAL BUG:  temp*(temp^1) may overflow in an

Changes to compat/zlib/contrib/minizip/miniunz.c.

    93     93                         0,NULL,OPEN_EXISTING,0,NULL);
    94     94     GetFileTime(hFile,&ftCreate,&ftLastAcc,&ftLastWrite);
    95     95     DosDateTimeToFileTime((WORD)(dosdate>>16),(WORD)dosdate,&ftLocal);
    96     96     LocalFileTimeToFileTime(&ftLocal,&ftm);
    97     97     SetFileTime(hFile,&ftm,&ftLastAcc,&ftm);
    98     98     CloseHandle(hFile);
    99     99   #else
   100         -#ifdef unix || __APPLE__
          100  +#if defined(unix) || defined(__APPLE__)
   101    101     struct utimbuf ut;
   102    102     struct tm newdate;
   103    103     newdate.tm_sec = tmu_date.tm_sec;
   104    104     newdate.tm_min=tmu_date.tm_min;
   105    105     newdate.tm_hour=tmu_date.tm_hour;
   106    106     newdate.tm_mday=tmu_date.tm_mday;
   107    107     newdate.tm_mon=tmu_date.tm_mon;

Changes to compat/zlib/contrib/minizip/minizip.c.

     8      8            Modifications of Unzip for Zip64
     9      9            Copyright (C) 2007-2008 Even Rouault
    10     10   
    11     11            Modifications for Zip64 support on both zip and unzip
    12     12            Copyright (C) 2009-2010 Mathias Svensson ( http://result42.com )
    13     13   */
    14     14   
    15         -
    16     15   #if (!defined(_WIN32)) && (!defined(WIN32)) && (!defined(__APPLE__))
    17     16           #ifndef __USE_FILE_OFFSET64
    18     17                   #define __USE_FILE_OFFSET64
    19     18           #endif
    20     19           #ifndef __USE_LARGEFILE64
    21     20                   #define __USE_LARGEFILE64
    22     21           #endif
................................................................................
    24     23                   #define _LARGEFILE64_SOURCE
    25     24           #endif
    26     25           #ifndef _FILE_OFFSET_BIT
    27     26                   #define _FILE_OFFSET_BIT 64
    28     27           #endif
    29     28   #endif
    30     29   
    31         -#ifdef __APPLE__
           30  +#if defined(__APPLE__) || defined(IOAPI_NO_64)
    32     31   // In darwin and perhaps other BSD variants off_t is a 64 bit value, hence no need for specific 64 bit functions
    33     32   #define FOPEN_FUNC(filename, mode) fopen(filename, mode)
    34     33   #define FTELLO_FUNC(stream) ftello(stream)
    35     34   #define FSEEKO_FUNC(stream, offset, origin) fseeko(stream, offset, origin)
    36     35   #else
    37     36   #define FOPEN_FUNC(filename, mode) fopen64(filename, mode)
    38     37   #define FTELLO_FUNC(stream) ftello64(stream)
    39     38   #define FSEEKO_FUNC(stream, offset, origin) fseeko64(stream, offset, origin)
    40     39   #endif
    41     40   
    42         -
    43         -
           41  +#include "tinydir.h"
    44     42   #include <stdio.h>
    45     43   #include <stdlib.h>
    46     44   #include <string.h>
    47     45   #include <time.h>
    48     46   #include <errno.h>
    49     47   #include <fcntl.h>
    50     48   
................................................................................
    90     88           FindClose(hFind);
    91     89           ret = 1;
    92     90         }
    93     91     }
    94     92     return ret;
    95     93   }
    96     94   #else
    97         -#ifdef unix || __APPLE__
           95  +#if defined(unix) || defined(__APPLE__)
    98     96   uLong filetime(f, tmzip, dt)
    99     97       char *f;               /* name of file to get info on */
   100     98       tm_zip *tmzip;         /* return value: access, modific. and creation times */
   101     99       uLong *dt;             /* dostime */
   102    100   {
   103    101     int ret=0;
   104    102     struct stat s;        /* results of stat() */
................................................................................
   168    166       printf("MiniZip 1.1, demo of zLib + MiniZip64 package, written by Gilles Vollant\n");
   169    167       printf("more info on MiniZip at http://www.winimage.com/zLibDll/minizip.html\n\n");
   170    168   }
   171    169   
   172    170   void do_help()
   173    171   {
   174    172       printf("Usage : minizip [-o] [-a] [-0 to -9] [-p password] [-j] file.zip [files_to_add]\n\n" \
          173  +           "  -r  Scan directories recursively\n" \
   175    174              "  -o  Overwrite existing file.zip\n" \
   176    175              "  -a  Append to existing file.zip\n" \
   177    176              "  -0  Store only\n" \
   178    177              "  -1  Compress faster\n" \
   179    178              "  -9  Compress better\n\n" \
   180    179              "  -j  exclude path. store only the file name.\n\n");
   181    180   }
................................................................................
   238    237        largeFile = 1;
   239    238   
   240    239                   fclose(pFile);
   241    240     }
   242    241   
   243    242    return largeFile;
   244    243   }
          244  +
          245  +void addFileToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) {
          246  +    FILE * fin;
          247  +    int size_read;
          248  +    const char *savefilenameinzip;
          249  +    zip_fileinfo zi;
          250  +    unsigned long crcFile=0;
          251  +    int zip64 = 0;
          252  +    int err=0;
          253  +    int size_buf=WRITEBUFFERSIZE;
          254  +    unsigned char buf[WRITEBUFFERSIZE];
          255  +    zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour =
          256  +    zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0;
          257  +    zi.dosDate = 0;
          258  +    zi.internal_fa = 0;
          259  +    zi.external_fa = 0;
          260  +    filetime(filenameinzip,&zi.tmz_date,&zi.dosDate);
          261  +
          262  +/*
          263  +    err = zipOpenNewFileInZip(zf,filenameinzip,&zi,
          264  +                     NULL,0,NULL,0,NULL / * comment * /,
          265  +                     (opt_compress_level != 0) ? Z_DEFLATED : 0,
          266  +                     opt_compress_level);
          267  +*/
          268  +    if ((password != NULL) && (err==ZIP_OK))
          269  +        err = getFileCrc(filenameinzip,buf,size_buf,&crcFile);
          270  +
          271  +    zip64 = isLargeFile(filenameinzip);
          272  +
          273  +   /* The path name saved, should not include a leading slash. */
          274  +   /*if it did, windows/xp and dynazip couldn't read the zip file. */
          275  +     savefilenameinzip = filenameinzip;
          276  +     while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' )
          277  +     {
          278  +         savefilenameinzip++;
          279  +     }
          280  +
          281  +     /*should the zip file contain any path at all?*/
          282  +     if( opt_exclude_path )
          283  +     {
          284  +         const char *tmpptr;
          285  +         const char *lastslash = 0;
          286  +         for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++)
          287  +         {
          288  +             if( *tmpptr == '\\' || *tmpptr == '/')
          289  +             {
          290  +                 lastslash = tmpptr;
          291  +             }
          292  +         }
          293  +         if( lastslash != NULL )
          294  +         {
          295  +             savefilenameinzip = lastslash+1; // base filename follows last slash.
          296  +         }
          297  +     }
          298  +
          299  +     /**/
          300  +    err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi,
          301  +                     NULL,0,NULL,0,NULL /* comment*/,
          302  +                     (opt_compress_level != 0) ? Z_DEFLATED : 0,
          303  +                     opt_compress_level,0,
          304  +                     /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */
          305  +                     -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY,
          306  +                     password,crcFile, zip64);
          307  +
          308  +    if (err != ZIP_OK)
          309  +        printf("error in opening %s in zipfile\n",filenameinzip);
          310  +    else
          311  +    {
          312  +        fin = FOPEN_FUNC(filenameinzip,"rb");
          313  +        if (fin==NULL)
          314  +        {
          315  +            err=ZIP_ERRNO;
          316  +            printf("error in opening %s for reading\n",filenameinzip);
          317  +        }
          318  +    }
          319  +
          320  +    if (err == ZIP_OK)
          321  +        do
          322  +        {
          323  +            err = ZIP_OK;
          324  +            size_read = (int)fread(buf,1,size_buf,fin);
          325  +            if (size_read < size_buf)
          326  +                if (feof(fin)==0)
          327  +            {
          328  +                printf("error in reading %s\n",filenameinzip);
          329  +                err = ZIP_ERRNO;
          330  +            }
          331  +
          332  +            if (size_read>0)
          333  +            {
          334  +                err = zipWriteInFileInZip (zf,buf,size_read);
          335  +                if (err<0)
          336  +                {
          337  +                    printf("error in writing %s in the zipfile\n",
          338  +                                     filenameinzip);
          339  +                }
          340  +
          341  +            }
          342  +        } while ((err == ZIP_OK) && (size_read>0));
          343  +
          344  +    if (fin)
          345  +        fclose(fin);
          346  +
          347  +    if (err<0)
          348  +        err=ZIP_ERRNO;
          349  +    else
          350  +    {
          351  +        err = zipCloseFileInZip(zf);
          352  +        if (err!=ZIP_OK)
          353  +            printf("error in closing %s in the zipfile\n",
          354  +                        filenameinzip);
          355  +    }
          356  +}
          357  +
          358  +
          359  +void addPathToZip(zipFile zf, const char *filenameinzip, const char *password, int opt_exclude_path,int opt_compress_level) {
          360  +    tinydir_dir dir;
          361  +    int i;
          362  +    char newname[512];
          363  +
          364  +    tinydir_open_sorted(&dir, filenameinzip);
          365  +
          366  +    for (i = 0; i < dir.n_files; i++)
          367  +    {
          368  +        tinydir_file file;
          369  +        tinydir_readfile_n(&dir, &file, i);
          370  +        if(strcmp(file.name,".")==0) continue;
          371  +        if(strcmp(file.name,"..")==0) continue;
          372  +        sprintf(newname,"%s/%s",dir.path,file.name);
          373  +        if (file.is_dir)
          374  +        {
          375  +            addPathToZip(zf,newname,password,opt_exclude_path,opt_compress_level);
          376  +        } else {
          377  +            addFileToZip(zf,newname,password,opt_exclude_path,opt_compress_level);
          378  +        }
          379  +    }
          380  +
          381  +    tinydir_close(&dir);
          382  +}
          383  +
   245    384   
   246    385   int main(argc,argv)
   247    386       int argc;
   248    387       char *argv[];
   249    388   {
   250    389       int i;
   251         -    int opt_overwrite=0;
          390  +    int opt_recursive=0;
          391  +    int opt_overwrite=1;
   252    392       int opt_compress_level=Z_DEFAULT_COMPRESSION;
   253    393       int opt_exclude_path=0;
   254    394       int zipfilenamearg = 0;
   255    395       char filename_try[MAXFILENAME+16];
   256    396       int zipok;
   257    397       int err=0;
   258    398       int size_buf=0;
................................................................................
   281    421                           opt_overwrite = 1;
   282    422                       if ((c=='a') || (c=='A'))
   283    423                           opt_overwrite = 2;
   284    424                       if ((c>='0') && (c<='9'))
   285    425                           opt_compress_level = c-'0';
   286    426                       if ((c=='j') || (c=='J'))
   287    427                           opt_exclude_path = 1;
   288         -
          428  +                    if ((c=='r') || (c=='R'))
          429  +                        opt_recursive = 1;
   289    430                       if (((c=='p') || (c=='P')) && (i+1<argc))
   290    431                       {
   291    432                           password=argv[i+1];
   292    433                           i++;
   293    434                       }
   294    435                   }
   295    436               }
................................................................................
   388    529   
   389    530           for (i=zipfilenamearg+1;(i<argc) && (err==ZIP_OK);i++)
   390    531           {
   391    532               if (!((((*(argv[i]))=='-') || ((*(argv[i]))=='/')) &&
   392    533                     ((argv[i][1]=='o') || (argv[i][1]=='O') ||
   393    534                      (argv[i][1]=='a') || (argv[i][1]=='A') ||
   394    535                      (argv[i][1]=='p') || (argv[i][1]=='P') ||
          536  +                   (argv[i][1]=='r') || (argv[i][1]=='R') ||
   395    537                      ((argv[i][1]>='0') || (argv[i][1]<='9'))) &&
   396    538                     (strlen(argv[i]) == 2)))
   397    539               {
   398         -                FILE * fin;
   399         -                int size_read;
   400         -                const char* filenameinzip = argv[i];
   401         -                const char *savefilenameinzip;
   402         -                zip_fileinfo zi;
   403         -                unsigned long crcFile=0;
   404         -                int zip64 = 0;
   405         -
   406         -                zi.tmz_date.tm_sec = zi.tmz_date.tm_min = zi.tmz_date.tm_hour =
   407         -                zi.tmz_date.tm_mday = zi.tmz_date.tm_mon = zi.tmz_date.tm_year = 0;
   408         -                zi.dosDate = 0;
   409         -                zi.internal_fa = 0;
   410         -                zi.external_fa = 0;
   411         -                filetime(filenameinzip,&zi.tmz_date,&zi.dosDate);
   412         -
   413         -/*
   414         -                err = zipOpenNewFileInZip(zf,filenameinzip,&zi,
   415         -                                 NULL,0,NULL,0,NULL / * comment * /,
   416         -                                 (opt_compress_level != 0) ? Z_DEFLATED : 0,
   417         -                                 opt_compress_level);
   418         -*/
   419         -                if ((password != NULL) && (err==ZIP_OK))
   420         -                    err = getFileCrc(filenameinzip,buf,size_buf,&crcFile);
   421         -
   422         -                zip64 = isLargeFile(filenameinzip);
   423         -
   424         -                                                         /* The path name saved, should not include a leading slash. */
   425         -               /*if it did, windows/xp and dynazip couldn't read the zip file. */
   426         -                 savefilenameinzip = filenameinzip;
   427         -                 while( savefilenameinzip[0] == '\\' || savefilenameinzip[0] == '/' )
   428         -                 {
   429         -                     savefilenameinzip++;
   430         -                 }
   431         -
   432         -                 /*should the zip file contain any path at all?*/
   433         -                 if( opt_exclude_path )
   434         -                 {
   435         -                     const char *tmpptr;
   436         -                     const char *lastslash = 0;
   437         -                     for( tmpptr = savefilenameinzip; *tmpptr; tmpptr++)
   438         -                     {
   439         -                         if( *tmpptr == '\\' || *tmpptr == '/')
   440         -                         {
   441         -                             lastslash = tmpptr;
   442         -                         }
   443         -                     }
   444         -                     if( lastslash != NULL )
   445         -                     {
   446         -                         savefilenameinzip = lastslash+1; // base filename follows last slash.
   447         -                     }
   448         -                 }
   449         -
   450         -                 /**/
   451         -                err = zipOpenNewFileInZip3_64(zf,savefilenameinzip,&zi,
   452         -                                 NULL,0,NULL,0,NULL /* comment*/,
   453         -                                 (opt_compress_level != 0) ? Z_DEFLATED : 0,
   454         -                                 opt_compress_level,0,
   455         -                                 /* -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY, */
   456         -                                 -MAX_WBITS, DEF_MEM_LEVEL, Z_DEFAULT_STRATEGY,
   457         -                                 password,crcFile, zip64);
   458         -
   459         -                if (err != ZIP_OK)
   460         -                    printf("error in opening %s in zipfile\n",filenameinzip);
   461         -                else
   462         -                {
   463         -                    fin = FOPEN_FUNC(filenameinzip,"rb");
   464         -                    if (fin==NULL)
   465         -                    {
   466         -                        err=ZIP_ERRNO;
   467         -                        printf("error in opening %s for reading\n",filenameinzip);
   468         -                    }
   469         -                }
   470         -
   471         -                if (err == ZIP_OK)
   472         -                    do
   473         -                    {
   474         -                        err = ZIP_OK;
   475         -                        size_read = (int)fread(buf,1,size_buf,fin);
   476         -                        if (size_read < size_buf)
   477         -                            if (feof(fin)==0)
   478         -                        {
   479         -                            printf("error in reading %s\n",filenameinzip);
   480         -                            err = ZIP_ERRNO;
   481         -                        }
   482         -
   483         -                        if (size_read>0)
   484         -                        {
   485         -                            err = zipWriteInFileInZip (zf,buf,size_read);
   486         -                            if (err<0)
   487         -                            {
   488         -                                printf("error in writing %s in the zipfile\n",
   489         -                                                 filenameinzip);
   490         -                            }
   491         -
   492         -                        }
   493         -                    } while ((err == ZIP_OK) && (size_read>0));
   494         -
   495         -                if (fin)
   496         -                    fclose(fin);
   497         -
   498         -                if (err<0)
   499         -                    err=ZIP_ERRNO;
   500         -                else
   501         -                {
   502         -                    err = zipCloseFileInZip(zf);
   503         -                    if (err!=ZIP_OK)
   504         -                        printf("error in closing %s in the zipfile\n",
   505         -                                    filenameinzip);
          540  +                if(opt_recursive) {
          541  +                    addPathToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level);
          542  +                } else {
          543  +                    addFileToZip(zf,argv[i],password,opt_exclude_path,opt_compress_level);
   506    544                   }
   507    545               }
   508    546           }
   509    547           errclose = zipClose(zf,NULL);
   510    548           if (errclose != ZIP_OK)
   511    549               printf("error in closing %s\n",filename_try);
   512    550       }

Added compat/zlib/contrib/minizip/tinydir.h.

            1  +/*
            2  +Copyright (c) 2013-2017, tinydir authors:
            3  +- Cong Xu
            4  +- Lautis Sun
            5  +- Baudouin Feildel
            6  +- Andargor <[email protected]>
            7  +All rights reserved.
            8  +
            9  +Redistribution and use in source and binary forms, with or without
           10  +modification, are permitted provided that the following conditions are met:
           11  +
           12  +1. Redistributions of source code must retain the above copyright notice, this
           13  +   list of conditions and the following disclaimer.
           14  +2. Redistributions in binary form must reproduce the above copyright notice,
           15  +   this list of conditions and the following disclaimer in the documentation
           16  +   and/or other materials provided with the distribution.
           17  +
           18  +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
           19  +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
           20  +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
           21  +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
           22  +ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
           23  +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
           24  +LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
           25  +ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
           26  +(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
           27  +SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
           28  +*/
           29  +#ifndef TINYDIR_H
           30  +#define TINYDIR_H
           31  +
           32  +#ifdef __cplusplus
           33  +extern "C" {
           34  +#endif
           35  +
           36  +#if ((defined _UNICODE) && !(defined UNICODE))
           37  +#define UNICODE
           38  +#endif
           39  +
           40  +#if ((defined UNICODE) && !(defined _UNICODE))
           41  +#define _UNICODE
           42  +#endif
           43  +
           44  +#include <errno.h>
           45  +#include <stdlib.h>
           46  +#include <string.h>
           47  +#ifdef _MSC_VER
           48  +# define WIN32_LEAN_AND_MEAN
           49  +# include <windows.h>
           50  +# include <tchar.h>
           51  +# pragma warning(push)
           52  +# pragma warning (disable : 4996)
           53  +#else
           54  +# include <dirent.h>
           55  +# include <libgen.h>
           56  +# include <sys/stat.h>
           57  +# include <stddef.h>
           58  +#endif
           59  +#ifdef __MINGW32__
           60  +# include <tchar.h>
           61  +#endif
           62  +
           63  +
           64  +/* types */
           65  +
           66  +/* Windows UNICODE wide character support */
           67  +#if defined _MSC_VER || defined __MINGW32__
           68  +# define _tinydir_char_t TCHAR
           69  +# define TINYDIR_STRING(s) _TEXT(s)
           70  +# define _tinydir_strlen _tcslen
           71  +# define _tinydir_strcpy _tcscpy
           72  +# define _tinydir_strcat _tcscat
           73  +# define _tinydir_strcmp _tcscmp
           74  +# define _tinydir_strrchr _tcsrchr
           75  +# define _tinydir_strncmp _tcsncmp
           76  +#else
           77  +# define _tinydir_char_t char
           78  +# define TINYDIR_STRING(s) s
           79  +# define _tinydir_strlen strlen
           80  +# define _tinydir_strcpy strcpy
           81  +# define _tinydir_strcat strcat
           82  +# define _tinydir_strcmp strcmp
           83  +# define _tinydir_strrchr strrchr
           84  +# define _tinydir_strncmp strncmp
           85  +#endif
           86  +
           87  +#if (defined _MSC_VER || defined __MINGW32__)
           88  +# include <windows.h>
           89  +# define _TINYDIR_PATH_MAX MAX_PATH
           90  +#elif defined  __linux__
           91  +# include <limits.h>
           92  +# define _TINYDIR_PATH_MAX PATH_MAX
           93  +#elif defined(__unix__) || (defined(__APPLE__) && defined(__MACH__))
           94  +# include <sys/param.h>
           95  +# if defined(BSD)
           96  +#  include <limits.h>
           97  +#  define _TINYDIR_PATH_MAX PATH_MAX
           98  +# endif
           99  +#endif
          100  +
          101  +#ifndef _TINYDIR_PATH_MAX
          102  +#define _TINYDIR_PATH_MAX 4096
          103  +#endif
          104  +
          105  +#ifdef _MSC_VER
          106  +/* extra chars for the "\\*" mask */
          107  +# define _TINYDIR_PATH_EXTRA 2
          108  +#else
          109  +# define _TINYDIR_PATH_EXTRA 0
          110  +#endif
          111  +
          112  +#define _TINYDIR_FILENAME_MAX 256
          113  +
          114  +#if (defined _MSC_VER || defined __MINGW32__)
          115  +#define _TINYDIR_DRIVE_MAX 3
          116  +#endif
          117  +
          118  +#ifdef _MSC_VER
          119  +# define _TINYDIR_FUNC static __inline
          120  +#elif !defined __STDC_VERSION__ || __STDC_VERSION__ < 199901L
          121  +# define _TINYDIR_FUNC static __inline__
          122  +#else
          123  +# define _TINYDIR_FUNC static inline
          124  +#endif
          125  +
          126  +/* readdir_r usage; define TINYDIR_USE_READDIR_R to use it (if supported) */
          127  +#ifdef TINYDIR_USE_READDIR_R
          128  +
          129  +/* readdir_r is a POSIX-only function, and may not be available under various
          130  + * environments/settings, e.g. MinGW. Use readdir fallback */
          131  +#if _POSIX_C_SOURCE >= 1 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE ||\
          132  +	_POSIX_SOURCE
          133  +# define _TINYDIR_HAS_READDIR_R
          134  +#endif
          135  +#if _POSIX_C_SOURCE >= 200112L
          136  +# define _TINYDIR_HAS_FPATHCONF
          137  +# include <unistd.h>
          138  +#endif
          139  +#if _BSD_SOURCE || _SVID_SOURCE || \
          140  +	(_POSIX_C_SOURCE >= 200809L || _XOPEN_SOURCE >= 700)
          141  +# define _TINYDIR_HAS_DIRFD
          142  +# include <sys/types.h>
          143  +#endif
          144  +#if defined _TINYDIR_HAS_FPATHCONF && defined _TINYDIR_HAS_DIRFD &&\
          145  +	defined _PC_NAME_MAX
          146  +# define _TINYDIR_USE_FPATHCONF
          147  +#endif
          148  +#if defined __MINGW32__ || !defined _TINYDIR_HAS_READDIR_R ||\
          149  +	!(defined _TINYDIR_USE_FPATHCONF || defined NAME_MAX)
          150  +# define _TINYDIR_USE_READDIR
          151  +#endif
          152  +
          153  +/* Use readdir by default */
          154  +#else
          155  +# define _TINYDIR_USE_READDIR
          156  +#endif
          157  +
          158  +/* MINGW32 has two versions of dirent, ASCII and UNICODE*/
          159  +#ifndef _MSC_VER
          160  +#if (defined __MINGW32__) && (defined _UNICODE)
          161  +#define _TINYDIR_DIR _WDIR
          162  +#define _tinydir_dirent _wdirent
          163  +#define _tinydir_opendir _wopendir
          164  +#define _tinydir_readdir _wreaddir
          165  +#define _tinydir_closedir _wclosedir
          166  +#else
          167  +#define _TINYDIR_DIR DIR
          168  +#define _tinydir_dirent dirent
          169  +#define _tinydir_opendir opendir
          170  +#define _tinydir_readdir readdir
          171  +#define _tinydir_closedir closedir
          172  +#endif
          173  +#endif
          174  +
          175  +/* Allow user to use a custom allocator by defining _TINYDIR_MALLOC and _TINYDIR_FREE. */
          176  +#if    defined(_TINYDIR_MALLOC) &&  defined(_TINYDIR_FREE)
          177  +#elif !defined(_TINYDIR_MALLOC) && !defined(_TINYDIR_FREE)
          178  +#else
          179  +#error "Either define both alloc and free or none of them!"
          180  +#endif
          181  +
          182  +#if !defined(_TINYDIR_MALLOC)
          183  +	#define _TINYDIR_MALLOC(_size) malloc(_size)
          184  +	#define _TINYDIR_FREE(_ptr)    free(_ptr)
          185  +#endif /* !defined(_TINYDIR_MALLOC) */
          186  +
          187  +typedef struct tinydir_file
          188  +{
          189  +	_tinydir_char_t path[_TINYDIR_PATH_MAX];
          190  +	_tinydir_char_t name[_TINYDIR_FILENAME_MAX];
          191  +	_tinydir_char_t *extension;
          192  +	int is_dir;
          193  +	int is_reg;
          194  +
          195  +#ifndef _MSC_VER
          196  +#ifdef __MINGW32__
          197  +	struct _stat _s;
          198  +#else
          199  +	struct stat _s;
          200  +#endif
          201  +#endif
          202  +} tinydir_file;
          203  +
          204  +typedef struct tinydir_dir
          205  +{
          206  +	_tinydir_char_t path[_TINYDIR_PATH_MAX];
          207  +	int has_next;
          208  +	size_t n_files;
          209  +
          210  +	tinydir_file *_files;
          211  +#ifdef _MSC_VER
          212  +	HANDLE _h;
          213  +	WIN32_FIND_DATA _f;
          214  +#else
          215  +	_TINYDIR_DIR *_d;
          216  +	struct _tinydir_dirent *_e;
          217  +#ifndef _TINYDIR_USE_READDIR
          218  +	struct _tinydir_dirent *_ep;
          219  +#endif
          220  +#endif
          221  +} tinydir_dir;
          222  +
          223  +
          224  +/* declarations */
          225  +
          226  +_TINYDIR_FUNC
          227  +int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path);
          228  +_TINYDIR_FUNC
          229  +int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path);
          230  +_TINYDIR_FUNC
          231  +void tinydir_close(tinydir_dir *dir);
          232  +
          233  +_TINYDIR_FUNC
          234  +int tinydir_next(tinydir_dir *dir);
          235  +_TINYDIR_FUNC
          236  +int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file);
          237  +_TINYDIR_FUNC
          238  +int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i);
          239  +_TINYDIR_FUNC
          240  +int tinydir_open_subdir_n(tinydir_dir *dir, size_t i);
          241  +
          242  +_TINYDIR_FUNC
          243  +int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path);
          244  +_TINYDIR_FUNC
          245  +void _tinydir_get_ext(tinydir_file *file);
          246  +_TINYDIR_FUNC
          247  +int _tinydir_file_cmp(const void *a, const void *b);
          248  +#ifndef _MSC_VER
          249  +#ifndef _TINYDIR_USE_READDIR
          250  +_TINYDIR_FUNC
          251  +size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp);
          252  +#endif
          253  +#endif
          254  +
          255  +
          256  +/* definitions*/
          257  +
          258  +_TINYDIR_FUNC
          259  +int tinydir_open(tinydir_dir *dir, const _tinydir_char_t *path)
          260  +{
          261  +#ifndef _MSC_VER
          262  +#ifndef _TINYDIR_USE_READDIR
          263  +	int error;
          264  +	int size;	/* using int size */
          265  +#endif
          266  +#else
          267  +	_tinydir_char_t path_buf[_TINYDIR_PATH_MAX];
          268  +#endif
          269  +	_tinydir_char_t *pathp;
          270  +
          271  +	if (dir == NULL || path == NULL || _tinydir_strlen(path) == 0)
          272  +	{
          273  +		errno = EINVAL;
          274  +		return -1;
          275  +	}
          276  +	if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX)
          277  +	{
          278  +		errno = ENAMETOOLONG;
          279  +		return -1;
          280  +	}
          281  +
          282  +	/* initialise dir */
          283  +	dir->_files = NULL;
          284  +#ifdef _MSC_VER
          285  +	dir->_h = INVALID_HANDLE_VALUE;
          286  +#else
          287  +	dir->_d = NULL;
          288  +#ifndef _TINYDIR_USE_READDIR
          289  +	dir->_ep = NULL;
          290  +#endif
          291  +#endif
          292  +	tinydir_close(dir);
          293  +
          294  +	_tinydir_strcpy(dir->path, path);
          295  +	/* Remove trailing slashes */
          296  +	pathp = &dir->path[_tinydir_strlen(dir->path) - 1];
          297  +	while (pathp != dir->path && (*pathp == TINYDIR_STRING('\\') || *pathp == TINYDIR_STRING('/')))
          298  +	{
          299  +		*pathp = TINYDIR_STRING('\0');
          300  +		pathp++;
          301  +	}
          302  +#ifdef _MSC_VER
          303  +	_tinydir_strcpy(path_buf, dir->path);
          304  +	_tinydir_strcat(path_buf, TINYDIR_STRING("\\*"));
          305  +#if (defined WINAPI_FAMILY) && (WINAPI_FAMILY != WINAPI_FAMILY_DESKTOP_APP)
          306  +	dir->_h = FindFirstFileEx(path_buf, FindExInfoStandard, &dir->_f, FindExSearchNameMatch, NULL, 0);
          307  +#else
          308  +	dir->_h = FindFirstFile(path_buf, &dir->_f);
          309  +#endif
          310  +	if (dir->_h == INVALID_HANDLE_VALUE)
          311  +	{
          312  +		errno = ENOENT;
          313  +#else
          314  +	dir->_d = _tinydir_opendir(path);
          315  +	if (dir->_d == NULL)
          316  +	{
          317  +#endif
          318  +		goto bail;
          319  +	}
          320  +
          321  +	/* read first file */
          322  +	dir->has_next = 1;
          323  +#ifndef _MSC_VER
          324  +#ifdef _TINYDIR_USE_READDIR
          325  +	dir->_e = _tinydir_readdir(dir->_d);
          326  +#else
          327  +	/* allocate dirent buffer for readdir_r */
          328  +	size = _tinydir_dirent_buf_size(dir->_d); /* conversion to int */
          329  +	if (size == -1) return -1;
          330  +	dir->_ep = (struct _tinydir_dirent*)_TINYDIR_MALLOC(size);
          331  +	if (dir->_ep == NULL) return -1;
          332  +
          333  +	error = readdir_r(dir->_d, dir->_ep, &dir->_e);
          334  +	if (error != 0) return -1;
          335  +#endif
          336  +	if (dir->_e == NULL)
          337  +	{
          338  +		dir->has_next = 0;
          339  +	}
          340  +#endif
          341  +
          342  +	return 0;
          343  +
          344  +bail:
          345  +	tinydir_close(dir);
          346  +	return -1;
          347  +}
          348  +
          349  +_TINYDIR_FUNC
          350  +int tinydir_open_sorted(tinydir_dir *dir, const _tinydir_char_t *path)
          351  +{
          352  +	/* Count the number of files first, to pre-allocate the files array */
          353  +	size_t n_files = 0;
          354  +	if (tinydir_open(dir, path) == -1)
          355  +	{
          356  +		return -1;
          357  +	}
          358  +	while (dir->has_next)
          359  +	{
          360  +		n_files++;
          361  +		if (tinydir_next(dir) == -1)
          362  +		{
          363  +			goto bail;
          364  +		}
          365  +	}
          366  +	tinydir_close(dir);
          367  +
          368  +	if (tinydir_open(dir, path) == -1)
          369  +	{
          370  +		return -1;
          371  +	}
          372  +
          373  +	dir->n_files = 0;
          374  +	dir->_files = (tinydir_file *)_TINYDIR_MALLOC(sizeof *dir->_files * n_files);
          375  +	if (dir->_files == NULL)
          376  +	{
          377  +		goto bail;
          378  +	}
          379  +	while (dir->has_next)
          380  +	{
          381  +		tinydir_file *p_file;
          382  +		dir->n_files++;
          383  +
          384  +		p_file = &dir->_files[dir->n_files - 1];
          385  +		if (tinydir_readfile(dir, p_file) == -1)
          386  +		{
          387  +			goto bail;
          388  +		}
          389  +
          390  +		if (tinydir_next(dir) == -1)
          391  +		{
          392  +			goto bail;
          393  +		}
          394  +
          395  +		/* Just in case the number of files has changed between the first and
          396  +		second reads, terminate without writing into unallocated memory */
          397  +		if (dir->n_files == n_files)
          398  +		{
          399  +			break;
          400  +		}
          401  +	}
          402  +
          403  +	qsort(dir->_files, dir->n_files, sizeof(tinydir_file), _tinydir_file_cmp);
          404  +
          405  +	return 0;
          406  +
          407  +bail:
          408  +	tinydir_close(dir);
          409  +	return -1;
          410  +}
          411  +
          412  +_TINYDIR_FUNC
          413  +void tinydir_close(tinydir_dir *dir)
          414  +{
          415  +	if (dir == NULL)
          416  +	{
          417  +		return;
          418  +	}
          419  +
          420  +	memset(dir->path, 0, sizeof(dir->path));
          421  +	dir->has_next = 0;
          422  +	dir->n_files = 0;
          423  +	_TINYDIR_FREE(dir->_files);
          424  +	dir->_files = NULL;
          425  +#ifdef _MSC_VER
          426  +	if (dir->_h != INVALID_HANDLE_VALUE)
          427  +	{
          428  +		FindClose(dir->_h);
          429  +	}
          430  +	dir->_h = INVALID_HANDLE_VALUE;
          431  +#else
          432  +	if (dir->_d)
          433  +	{
          434  +		_tinydir_closedir(dir->_d);
          435  +	}
          436  +	dir->_d = NULL;
          437  +	dir->_e = NULL;
          438  +#ifndef _TINYDIR_USE_READDIR
          439  +	_TINYDIR_FREE(dir->_ep);
          440  +	dir->_ep = NULL;
          441  +#endif
          442  +#endif
          443  +}
          444  +
          445  +_TINYDIR_FUNC
          446  +int tinydir_next(tinydir_dir *dir)
          447  +{
          448  +	if (dir == NULL)
          449  +	{
          450  +		errno = EINVAL;
          451  +		return -1;
          452  +	}
          453  +	if (!dir->has_next)
          454  +	{
          455  +		errno = ENOENT;
          456  +		return -1;
          457  +	}
          458  +
          459  +#ifdef _MSC_VER
          460  +	if (FindNextFile(dir->_h, &dir->_f) == 0)
          461  +#else
          462  +#ifdef _TINYDIR_USE_READDIR
          463  +	dir->_e = _tinydir_readdir(dir->_d);
          464  +#else
          465  +	if (dir->_ep == NULL)
          466  +	{
          467  +		return -1;
          468  +	}
          469  +	if (readdir_r(dir->_d, dir->_ep, &dir->_e) != 0)
          470  +	{
          471  +		return -1;
          472  +	}
          473  +#endif
          474  +	if (dir->_e == NULL)
          475  +#endif
          476  +	{
          477  +		dir->has_next = 0;
          478  +#ifdef _MSC_VER
          479  +		if (GetLastError() != ERROR_SUCCESS &&
          480  +			GetLastError() != ERROR_NO_MORE_FILES)
          481  +		{
          482  +			tinydir_close(dir);
          483  +			errno = EIO;
          484  +			return -1;
          485  +		}
          486  +#endif
          487  +	}
          488  +
          489  +	return 0;
          490  +}
          491  +
          492  +_TINYDIR_FUNC
          493  +int tinydir_readfile(const tinydir_dir *dir, tinydir_file *file)
          494  +{
          495  +	if (dir == NULL || file == NULL)
          496  +	{
          497  +		errno = EINVAL;
          498  +		return -1;
          499  +	}
          500  +#ifdef _MSC_VER
          501  +	if (dir->_h == INVALID_HANDLE_VALUE)
          502  +#else
          503  +	if (dir->_e == NULL)
          504  +#endif
          505  +	{
          506  +		errno = ENOENT;
          507  +		return -1;
          508  +	}
          509  +	if (_tinydir_strlen(dir->path) +
          510  +		_tinydir_strlen(
          511  +#ifdef _MSC_VER
          512  +			dir->_f.cFileName
          513  +#else
          514  +			dir->_e->d_name
          515  +#endif
          516  +		) + 1 + _TINYDIR_PATH_EXTRA >=
          517  +		_TINYDIR_PATH_MAX)
          518  +	{
          519  +		/* the path for the file will be too long */
          520  +		errno = ENAMETOOLONG;
          521  +		return -1;
          522  +	}
          523  +	if (_tinydir_strlen(
          524  +#ifdef _MSC_VER
          525  +			dir->_f.cFileName
          526  +#else
          527  +			dir->_e->d_name
          528  +#endif
          529  +		) >= _TINYDIR_FILENAME_MAX)
          530  +	{
          531  +		errno = ENAMETOOLONG;
          532  +		return -1;
          533  +	}
          534  +
          535  +	_tinydir_strcpy(file->path, dir->path);
          536  +	_tinydir_strcat(file->path, TINYDIR_STRING("/"));
          537  +	_tinydir_strcpy(file->name,
          538  +#ifdef _MSC_VER
          539  +		dir->_f.cFileName
          540  +#else
          541  +		dir->_e->d_name
          542  +#endif
          543  +	);
          544  +	_tinydir_strcat(file->path, file->name);
          545  +#ifndef _MSC_VER
          546  +#ifdef __MINGW32__
          547  +	if (_tstat(
          548  +#else
          549  +	if (stat(
          550  +#endif
          551  +		file->path, &file->_s) == -1)
          552  +	{
          553  +		return -1;
          554  +	}
          555  +#endif
          556  +	_tinydir_get_ext(file);
          557  +
          558  +	file->is_dir =
          559  +#ifdef _MSC_VER
          560  +		!!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY);
          561  +#else
          562  +		S_ISDIR(file->_s.st_mode);
          563  +#endif
          564  +	file->is_reg =
          565  +#ifdef _MSC_VER
          566  +		!!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NORMAL) ||
          567  +		(
          568  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DEVICE) &&
          569  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY) &&
          570  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_ENCRYPTED) &&
          571  +#ifdef FILE_ATTRIBUTE_INTEGRITY_STREAM
          572  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_INTEGRITY_STREAM) &&
          573  +#endif
          574  +#ifdef FILE_ATTRIBUTE_NO_SCRUB_DATA
          575  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_NO_SCRUB_DATA) &&
          576  +#endif
          577  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_OFFLINE) &&
          578  +			!(dir->_f.dwFileAttributes & FILE_ATTRIBUTE_TEMPORARY));
          579  +#else
          580  +		S_ISREG(file->_s.st_mode);
          581  +#endif
          582  +
          583  +	return 0;
          584  +}
          585  +
          586  +_TINYDIR_FUNC
          587  +int tinydir_readfile_n(const tinydir_dir *dir, tinydir_file *file, size_t i)
          588  +{
          589  +	if (dir == NULL || file == NULL)
          590  +	{
          591  +		errno = EINVAL;
          592  +		return -1;
          593  +	}
          594  +	if (i >= dir->n_files)
          595  +	{
          596  +		errno = ENOENT;
          597  +		return -1;
          598  +	}
          599  +
          600  +	memcpy(file, &dir->_files[i], sizeof(tinydir_file));
          601  +	_tinydir_get_ext(file);
          602  +
          603  +	return 0;
          604  +}
          605  +
          606  +_TINYDIR_FUNC
          607  +int tinydir_open_subdir_n(tinydir_dir *dir, size_t i)
          608  +{
          609  +	_tinydir_char_t path[_TINYDIR_PATH_MAX];
          610  +	if (dir == NULL)
          611  +	{
          612  +		errno = EINVAL;
          613  +		return -1;
          614  +	}
          615  +	if (i >= dir->n_files || !dir->_files[i].is_dir)
          616  +	{
          617  +		errno = ENOENT;
          618  +		return -1;
          619  +	}
          620  +
          621  +	_tinydir_strcpy(path, dir->_files[i].path);
          622  +	tinydir_close(dir);
          623  +	if (tinydir_open_sorted(dir, path) == -1)
          624  +	{
          625  +		return -1;
          626  +	}
          627  +
          628  +	return 0;
          629  +}
          630  +
          631  +/* Open a single file given its path */
          632  +_TINYDIR_FUNC
          633  +int tinydir_file_open(tinydir_file *file, const _tinydir_char_t *path)
          634  +{
          635  +	tinydir_dir dir;
          636  +	int result = 0;
          637  +	int found = 0;
          638  +	_tinydir_char_t dir_name_buf[_TINYDIR_PATH_MAX];
          639  +	_tinydir_char_t file_name_buf[_TINYDIR_FILENAME_MAX];
          640  +	_tinydir_char_t *dir_name;
          641  +	_tinydir_char_t *base_name;
          642  +#if (defined _MSC_VER || defined __MINGW32__)
          643  +	_tinydir_char_t drive_buf[_TINYDIR_PATH_MAX];
          644  +	_tinydir_char_t ext_buf[_TINYDIR_FILENAME_MAX];
          645  +#endif
          646  +
          647  +	if (file == NULL || path == NULL || _tinydir_strlen(path) == 0)
          648  +	{
          649  +		errno = EINVAL;
          650  +		return -1;
          651  +	}
          652  +	if (_tinydir_strlen(path) + _TINYDIR_PATH_EXTRA >= _TINYDIR_PATH_MAX)
          653  +	{
          654  +		errno = ENAMETOOLONG;
          655  +		return -1;
          656  +	}
          657  +
          658  +	/* Get the parent path */
          659  +#if (defined _MSC_VER || defined __MINGW32__)
          660  +#if ((defined _MSC_VER) && (_MSC_VER >= 1400))
          661  +		_tsplitpath_s(
          662  +			path,
          663  +			drive_buf, _TINYDIR_DRIVE_MAX,
          664  +			dir_name_buf, _TINYDIR_FILENAME_MAX,
          665  +			file_name_buf, _TINYDIR_FILENAME_MAX,
          666  +			ext_buf, _TINYDIR_FILENAME_MAX);
          667  +#else
          668  +		_tsplitpath(
          669  +			path,
          670  +			drive_buf,
          671  +			dir_name_buf,
          672  +			file_name_buf,
          673  +			ext_buf);
          674  +#endif
          675  +
          676  +/* _splitpath_s not work fine with only filename and widechar support */
          677  +#ifdef _UNICODE
          678  +		if (drive_buf[0] == L'\xFEFE')
          679  +			drive_buf[0] = '\0';
          680  +		if (dir_name_buf[0] == L'\xFEFE')
          681  +			dir_name_buf[0] = '\0';
          682  +#endif
          683  +
          684  +	if (errno)
          685  +	{
          686  +		errno = EINVAL;
          687  +		return -1;
          688  +	}
          689  +	/* Emulate the behavior of dirname by returning "." for dir name if it's
          690  +	empty */
          691  +	if (drive_buf[0] == '\0' && dir_name_buf[0] == '\0')
          692  +	{
          693  +		_tinydir_strcpy(dir_name_buf, TINYDIR_STRING("."));
          694  +	}
          695  +	/* Concatenate the drive letter and dir name to form full dir name */
          696  +	_tinydir_strcat(drive_buf, dir_name_buf);
          697  +	dir_name = drive_buf;
          698  +	/* Concatenate the file name and extension to form base name */
          699  +	_tinydir_strcat(file_name_buf, ext_buf);
          700  +	base_name = file_name_buf;
          701  +#else
          702  +	_tinydir_strcpy(dir_name_buf, path);
          703  +	dir_name = dirname(dir_name_buf);
          704  +	_tinydir_strcpy(file_name_buf, path);
          705  +	base_name =basename(file_name_buf);
          706  +#endif
          707  +
          708  +	/* Open the parent directory */
          709  +	if (tinydir_open(&dir, dir_name) == -1)
          710  +	{
          711  +		return -1;
          712  +	}
          713  +
          714  +	/* Read through the parent directory and look for the file */
          715  +	while (dir.has_next)
          716  +	{
          717  +		if (tinydir_readfile(&dir, file) == -1)
          718  +		{
          719  +			result = -1;
          720  +			goto bail;
          721  +		}
          722  +		if (_tinydir_strcmp(file->name, base_name) == 0)
          723  +		{
          724  +			/* File found */
          725  +			found = 1;
          726  +			break;
          727  +		}
          728  +		tinydir_next(&dir);
          729  +	}
          730  +	if (!found)
          731  +	{
          732  +		result = -1;
          733  +		errno = ENOENT;
          734  +	}
          735  +
          736  +bail:
          737  +	tinydir_close(&dir);
          738  +	return result;
          739  +}
          740  +
          741  +_TINYDIR_FUNC
          742  +void _tinydir_get_ext(tinydir_file *file)
          743  +{
          744  +	_tinydir_char_t *period = _tinydir_strrchr(file->name, TINYDIR_STRING('.'));
          745  +	if (period == NULL)
          746  +	{
          747  +		file->extension = &(file->name[_tinydir_strlen(file->name)]);
          748  +	}
          749  +	else
          750  +	{
          751  +		file->extension = period + 1;
          752  +	}
          753  +}
          754  +
          755  +_TINYDIR_FUNC
          756  +int _tinydir_file_cmp(const void *a, const void *b)
          757  +{
          758  +	const tinydir_file *fa = (const tinydir_file *)a;
          759  +	const tinydir_file *fb = (const tinydir_file *)b;
          760  +	if (fa->is_dir != fb->is_dir)
          761  +	{
          762  +		return -(fa->is_dir - fb->is_dir);
          763  +	}
          764  +	return _tinydir_strncmp(fa->name, fb->name, _TINYDIR_FILENAME_MAX);
          765  +}
          766  +
          767  +#ifndef _MSC_VER
          768  +#ifndef _TINYDIR_USE_READDIR
          769  +/*
          770  +The following authored by Ben Hutchings <[email protected]>
          771  +from https://womble.decadent.org.uk/readdir_r-advisory.html
          772  +*/
          773  +/* Calculate the required buffer size (in bytes) for directory      *
          774  +* entries read from the given directory handle.  Return -1 if this  *
          775  +* this cannot be done.                                              *
          776  +*                                                                   *
          777  +* This code does not trust values of NAME_MAX that are less than    *
          778  +* 255, since some systems (including at least HP-UX) incorrectly    *
          779  +* define it to be a smaller value.                                  */
          780  +_TINYDIR_FUNC
          781  +size_t _tinydir_dirent_buf_size(_TINYDIR_DIR *dirp)
          782  +{
          783  +	long name_max;
          784  +	size_t name_end;
          785  +	/* parameter may be unused */
          786  +	(void)dirp;
          787  +
          788  +#if defined _TINYDIR_USE_FPATHCONF
          789  +	name_max = fpathconf(dirfd(dirp), _PC_NAME_MAX);
          790  +	if (name_max == -1)
          791  +#if defined(NAME_MAX)
          792  +		name_max = (NAME_MAX > 255) ? NAME_MAX : 255;
          793  +#else
          794  +		return (size_t)(-1);
          795  +#endif
          796  +#elif defined(NAME_MAX)
          797  + 	name_max = (NAME_MAX > 255) ? NAME_MAX : 255;
          798  +#else
          799  +#error "buffer size for readdir_r cannot be determined"
          800  +#endif
          801  +	name_end = (size_t)offsetof(struct _tinydir_dirent, d_name) + name_max + 1;
          802  +	return (name_end > sizeof(struct _tinydir_dirent) ?
          803  +		name_end : sizeof(struct _tinydir_dirent));
          804  +}
          805  +#endif
          806  +#endif
          807  +
          808  +#ifdef __cplusplus
          809  +}
          810  +#endif
          811  +
          812  +# if defined (_MSC_VER)
          813  +# pragma warning(pop)
          814  +# endif
          815  +
          816  +#endif

compat/zlib/win32/zdll.lib became a regular file.

cannot compute difference between binary files

Changes to doc/AddErrInfo.3.

    54     54   this points to the first byte of an array of \fIlength\fR bytes
    55     55   containing a string to append to the \fB\-errorinfo\fR return option.
    56     56   This byte array may contain embedded null bytes
    57     57   unless \fIlength\fR is negative.
    58     58   .AP Tcl_Obj *objPtr in
    59     59   A message to be appended to the \fB\-errorinfo\fR return option
    60     60   in the form of a Tcl_Obj value.
    61         -.AP int length in
           61  +.AP size_t length in
    62     62   The number of bytes to copy from \fImessage\fR when
    63     63   appending to the \fB\-errorinfo\fR return option.
    64         -If negative, all bytes up to the first null byte are used.
           64  +If TCL_AUTO_LENGTH, all bytes up to the first null byte are used.
    65     65   .AP Tcl_Obj *errorObjPtr in
    66     66   The \fB\-errorcode\fR return option will be set to this value.
    67     67   .AP char *element in
    68     68   String to record as one element of the \fB\-errorcode\fR return option.
    69     69   Last \fIelement\fR argument must be NULL.
    70     70   .AP va_list argList in
    71     71   An argument list which must have been initialized using

Changes to doc/Alloc.3.

     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7      7   .TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
     8      8   .so man.macros
     9      9   .BS
    10     10   .SH NAME
    11         -Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
           11  +Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- allocate or free heap memory
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16     16   char *
    17     17   \fBTcl_Alloc\fR(\fIsize\fR)
    18     18   .sp
    19     19   void
    20     20   \fBTcl_Free\fR(\fIptr\fR)
    21     21   .sp
    22         -char *
           22  +void *
    23     23   \fBTcl_Realloc\fR(\fIptr, size\fR)
    24     24   .sp
    25         -char *
           25  +void *
    26     26   \fBTcl_AttemptAlloc\fR(\fIsize\fR)
    27     27   .sp
    28         -char *
           28  +void *
    29     29   \fBTcl_AttemptRealloc\fR(\fIptr, size\fR)
    30         -.sp
    31         -char *
    32         -\fBckalloc\fR(\fIsize\fR)
    33         -.sp
    34         -void
    35         -\fBckfree\fR(\fIptr\fR)
    36         -.sp
    37         -char *
    38         -\fBckrealloc\fR(\fIptr, size\fR)
    39         -.sp
    40         -char *
    41         -\fBattemptckalloc\fR(\fIsize\fR)
    42         -.sp
    43         -char *
    44         -\fBattemptckrealloc\fR(\fIptr, size\fR)
    45     30   .SH ARGUMENTS
    46     31   .AS char *size
    47     32   .AP "unsigned int" size in
    48     33   Size in bytes of the memory block to allocate.
    49     34   .AP char *ptr in
    50     35   Pointer to memory block to free or realloc.
    51     36   .BE
................................................................................
    75     60   function to \fBTcl_Alloc\fR and \fBTcl_Realloc\fR, except that
    76     61   \fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl
    77     62   interpreter to \fBpanic\fR if the memory allocation fails.  If the
    78     63   allocation fails, these functions will return NULL.  Note that on some
    79     64   platforms, but not all, attempting to allocate a zero-sized block of
    80     65   memory will also cause these functions to return NULL.
    81     66   .PP
    82         -The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
    83         -\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
    84         -as macros.  Normally, they are synonyms for the corresponding
    85         -procedures documented on this page.  When Tcl and all modules
    86         -calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
    87         -these macros are redefined to be special debugging versions
    88         -of these procedures.  To support Tcl's memory debugging within a
    89         -module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
           67  +When a module or Tcl itself is compiled with \fBTCL_MEM_DEBUG\fR defined,
           68  +the procedures \fBTcl_Alloc\fR, \fBTcl_Free\fR, \fBTcl_Realloc\fR,
           69  +\fBTcl_AttemptAlloc\fR, and \fBTcl_AttempRealloc\fR are implemented
           70  +as macros, redefined to be special debugging versions of these procedures.
    90     71   
    91     72   .SH KEYWORDS
    92     73   alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG

Changes to doc/AssocData.3.

     9      9   .BS
    10     10   .SH NAME
    11     11   Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage associations of string keys and user specified data with Tcl interpreters
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16         -ClientData
           16  +void *
    17     17   \fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
    18     18   .sp
    19     19   \fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
    20     20   .sp
    21     21   \fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
    22     22   .SH ARGUMENTS
    23     23   .AS Tcl_InterpDeleteProc **delProcPtr
................................................................................
    27     27   Key for association with which to store data or from which to delete or
    28     28   retrieve data.  Typically the module prefix for a package.
    29     29   .AP Tcl_InterpDeleteProc *delProc in
    30     30   Procedure to call when \fIinterp\fR is deleted.
    31     31   .AP Tcl_InterpDeleteProc **delProcPtr in
    32     32   Pointer to location in which to store address of current deletion procedure
    33     33   for association.  Ignored if NULL.
    34         -.AP ClientData clientData in
           34  +.AP void *clientData in
    35     35   Arbitrary one-word value associated with the given key in this
    36     36   interpreter.  This data is owned by the caller.
    37     37   .BE
    38     38   
    39     39   .SH DESCRIPTION
    40     40   .PP
    41     41   These procedures allow extensions to associate their own data with
................................................................................
    60     60   If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
    61     61   procedure to invoke if the interpreter is deleted before the association
    62     62   is deleted.  \fIDeleteProc\fR should have arguments and result that match
    63     63   the type \fBTcl_InterpDeleteProc\fR:
    64     64   .PP
    65     65   .CS
    66     66   typedef void \fBTcl_InterpDeleteProc\fR(
    67         -        ClientData \fIclientData\fR,
           67  +        void *\fIclientData\fR,
    68     68           Tcl_Interp *\fIinterp\fR);
    69     69   .CE
    70     70   .PP
    71     71   When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
    72     72   arguments will be the same as the corresponding arguments passed to
    73     73   \fBTcl_SetAssocData\fR.
    74     74   The deletion procedure will \fInot\fR be invoked if the association

Changes to doc/Async.3.

    26     26   .sp
    27     27   int
    28     28   \fBTcl_AsyncReady\fR()
    29     29   .SH ARGUMENTS
    30     30   .AS Tcl_AsyncHandler clientData
    31     31   .AP Tcl_AsyncProc *proc in
    32     32   Procedure to invoke to handle an asynchronous event.
    33         -.AP ClientData clientData in
           33  +.AP void *clientData in
    34     34   One-word value to pass to \fIproc\fR.
    35     35   .AP Tcl_AsyncHandler async in
    36     36   Token for asynchronous event handler.
    37     37   .AP Tcl_Interp *interp in
    38     38   Tcl interpreter in which command was being evaluated when handler was
    39     39   invoked, or NULL if handler was invoked when there was no interpreter
    40     40   active.
................................................................................
    80     80   the world is in a safe state, and \fIproc\fR can then carry out
    81     81   the actions associated with the asynchronous event.
    82     82   \fIProc\fR should have arguments and result that match the
    83     83   type \fBTcl_AsyncProc\fR:
    84     84   .PP
    85     85   .CS
    86     86   typedef int \fBTcl_AsyncProc\fR(
    87         -        ClientData \fIclientData\fR,
           87  +        void *\fIclientData\fR,
    88     88           Tcl_Interp *\fIinterp\fR,
    89     89           int \fIcode\fR);
    90     90   .CE
    91     91   .PP
    92     92   The \fIclientData\fR will be the same as the \fIclientData\fR
    93     93   argument passed to \fBTcl_AsyncCreate\fR when the handler was
    94     94   created.

Changes to doc/ByteArrObj.3.

    25     25   unsigned char *
    26     26   \fBTcl_SetByteArrayLength\fR(\fIobjPtr, length\fR)
    27     27   .SH ARGUMENTS
    28     28   .AS "const unsigned char" *lengthPtr in/out
    29     29   .AP "const unsigned char" *bytes in
    30     30   The array of bytes used to initialize or set a byte-array value. May be NULL
    31     31   even if \fIlength\fR is non-zero.
    32         -.AP int length in
    33         -The length of the array of bytes.  It must be >= 0.
           32  +.AP size_t length in
           33  +The length of the array of bytes.
    34     34   .AP Tcl_Obj *objPtr in/out
    35     35   For \fBTcl_SetByteArrayObj\fR, this points to the value to be converted to
    36     36   byte-array type.  For \fBTcl_GetByteArrayFromObj\fR and
    37     37   \fBTcl_SetByteArrayLength\fR, this points to the value from which to get
    38     38   the byte-array value; if \fIobjPtr\fR does not already point to a byte-array
    39     39   value, it will be converted to one.
    40     40   .AP int *lengthPtr out

Changes to doc/CallDel.3.

    19     19   \fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
    20     20   .SH ARGUMENTS
    21     21   .AS Tcl_InterpDeleteProc clientData
    22     22   .AP Tcl_Interp *interp in
    23     23   Interpreter with which to associated callback.
    24     24   .AP Tcl_InterpDeleteProc *proc in
    25     25   Procedure to call when \fIinterp\fR is deleted.
    26         -.AP ClientData clientData in
           26  +.AP void *clientData in
    27     27   Arbitrary one-word value to pass to \fIproc\fR.
    28     28   .BE
    29     29   .SH DESCRIPTION
    30     30   .PP
    31     31   \fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
    32     32   \fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future
    33     33   time.  \fIProc\fR will be invoked just before the interpreter
................................................................................
    34     34   is deleted, but the interpreter will still be valid at the
    35     35   time of the call.
    36     36   \fIProc\fR should have arguments and result that match the
    37     37   type \fBTcl_InterpDeleteProc\fR:
    38     38   .PP
    39     39   .CS
    40     40   typedef void \fBTcl_InterpDeleteProc\fR(
    41         -        ClientData \fIclientData\fR,
           41  +        void *\fIclientData\fR,
    42     42           Tcl_Interp *\fIinterp\fR);
    43     43   .CE
    44     44   .PP
    45     45   The \fIclientData\fR and \fIinterp\fR parameters are
    46     46   copies of the \fIclientData\fR and \fIinterp\fR arguments given
    47     47   to \fBTcl_CallWhenDeleted\fR.
    48     48   Typically, \fIclientData\fR points to an application-specific

Changes to doc/Cancel.3.

    26     26   not NULL, this object will have its reference count decremented before
    27     27   \fBTcl_CancelEval\fR returns.
    28     28   .AP int flags in
    29     29   ORed combination of flag bits that specify additional options.
    30     30   For \fBTcl_CancelEval\fR, only \fBTCL_CANCEL_UNWIND\fR is currently
    31     31   supported.  For \fBTcl_Canceled\fR, only \fBTCL_LEAVE_ERR_MSG\fR and
    32     32   \fBTCL_CANCEL_UNWIND\fR are currently supported.
    33         -.AP ClientData clientData in
           33  +.AP void *clientData in
    34     34   Currently reserved for future use.
    35     35   It should be set to NULL.
    36     36   .BE
    37     37   .SH DESCRIPTION
    38     38   .PP
    39     39   \fBTcl_CancelEval\fR cancels or unwinds the script in progress soon after
    40     40   the next invocation of asynchronous handlers, causing \fBTCL_ERROR\fR to be

Changes to doc/ChnlStack.3.

    28     28   .sp
    29     29   .SH ARGUMENTS
    30     30   .AS Tcl_ChannelType clientData
    31     31   .AP Tcl_Interp *interp in
    32     32   Interpreter for error reporting.
    33     33   .AP "const Tcl_ChannelType" *typePtr in
    34     34   The new channel I/O procedures to use for \fIchannel\fR.
    35         -.AP ClientData clientData in
           35  +.AP void *clientData in
    36     36   Arbitrary one-word value to pass to channel I/O procedures.
    37     37   .AP int mask in
    38     38   Conditions under which \fIchannel\fR will be used: OR-ed combination of
    39     39   \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR.
    40     40   This can be a subset of the operations currently allowed on \fIchannel\fR.
    41     41   .AP Tcl_Channel channel in
    42     42   An existing Tcl channel such as returned by \fBTcl_CreateChannel\fR.

Changes to doc/Class.3.

    37     37   .sp
    38     38   Tcl_Object
    39     39   \fBTcl_CopyObjectInstance\fR(\fIinterp, object, name, nsName\fR)
    40     40   .sp
    41     41   int
    42     42   \fBTcl_ObjectDeleted\fR(\fIobject\fR)
    43     43   .sp
    44         -ClientData
           44  +void *
    45     45   \fBTcl_ObjectGetMetadata\fR(\fIobject, metaTypePtr\fR)
    46     46   .sp
    47     47   \fBTcl_ObjectSetMetadata\fR(\fIobject, metaTypePtr, metadata\fR)
    48     48   .sp
    49         -ClientData
           49  +void *
    50     50   \fBTcl_ClassGetMetadata\fR(\fIclass, metaTypePtr\fR)
    51     51   .sp
    52     52   \fBTcl_ClassSetMetadata\fR(\fIclass, metaTypePtr, metadata\fR)
    53     53   .sp
    54     54   Tcl_ObjectMapMethodNameProc
    55     55   \fBTcl_ObjectGetMethodNameMapper\fR(\fIobject\fR)
    56     56   .sp
    57     57   \fBTcl_ObjectSetMethodNameMapper\fR(\fIobject\fR, \fImethodNameMapper\fR)
    58     58   .SH ARGUMENTS
    59         -.AS ClientData metadata in/out
           59  +.AS void *metadata in/out
    60     60   .AP Tcl_Interp *interp in/out
    61     61   Interpreter providing the context for looking up or creating an object, and
    62     62   into whose result error messages will be written on failure.
    63     63   .AP Tcl_Obj *objPtr in
    64     64   The name of the object to look up.
    65     65   .AP Tcl_Object object in
    66     66   Reference to the object to operate upon.
................................................................................
    79     79   The arguments to the command to create the instance of the class.
    80     80   .AP int skip in
    81     81   The number of arguments at the start of the argument array, \fIobjv\fR, that
    82     82   are not arguments to any constructors.
    83     83   .AP Tcl_ObjectMetadataType *metaTypePtr in
    84     84   The type of \fImetadata\fR being set with \fBTcl_ClassSetMetadata\fR or
    85     85   retrieved with \fBTcl_ClassGetMetadata\fR.
    86         -.AP ClientData metadata in
           86  +.AP void *metadata in
    87     87   An item of metadata to attach to the class, or NULL to remove the metadata
    88     88   associated with a particular \fImetaTypePtr\fR.
    89     89   .AP "Tcl_ObjectMapMethodNameProc" "methodNameMapper" in
    90     90   A pointer to a function to call to adjust the mapping of objects and method
    91     91   names to implementations, or NULL when no such mapping is required.
    92     92   .BE
    93     93   .SH DESCRIPTION
................................................................................
   167    167   .SS "TCL_OBJECTMETADATADELETEPROC FUNCTION SIGNATURE"
   168    168   .PP
   169    169   Functions matching this signature are used to delete metadata associated with
   170    170   a class or object.
   171    171   .PP
   172    172   .CS
   173    173   typedef void \fBTcl_ObjectMetadataDeleteProc\fR(
   174         -        ClientData \fImetadata\fR);
          174  +        void *\fImetadata\fR);
   175    175   .CE
   176    176   .PP
   177    177   The \fImetadata\fR argument gives the address of the metadata to be
   178    178   deleted.
   179    179   .SS "TCL_CLONEPROC FUNCTION SIGNATURE"
   180    180   .PP
   181    181   Functions matching this signature are used to create copies of metadata
   182    182   associated with a class or object.
   183    183   .PP
   184    184   .CS
   185    185   typedef int \fBTcl_CloneProc\fR(
   186    186           Tcl_Interp *\fIinterp\fR,
   187         -        ClientData \fIsrcMetadata\fR,
   188         -        ClientData *\fIdstMetadataPtr\fR);
          187  +        void *\fIsrcMetadata\fR,
          188  +        void **\fIdstMetadataPtr\fR);
   189    189   .CE
   190    190   .PP
   191    191   The \fIinterp\fR argument gives a place to write an error message when the
   192    192   attempt to clone the object is to fail, in which case the clone procedure must
   193    193   also return TCL_ERROR; it should return TCL_OK otherwise.
   194    194   The \fIsrcMetadata\fR argument gives the address of the metadata to be cloned,
   195    195   and the cloned metadata should be written into the variable pointed to by

Changes to doc/CrtChannel.3.

    13     13   .SH SYNOPSIS
    14     14   .nf
    15     15   \fB#include <tcl.h>\fR
    16     16   .sp
    17     17   Tcl_Channel
    18     18   \fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
    19     19   .sp
    20         -ClientData
           20  +void *
    21     21   \fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
    22     22   .sp
    23     23   const Tcl_ChannelType *
    24     24   \fBTcl_GetChannelType\fR(\fIchannel\fR)
    25     25   .sp
    26     26   const char *
    27     27   \fBTcl_GetChannelName\fR(\fIchannel\fR)
................................................................................
   124    124   can be called to perform I/O and other functions on the channel.
   125    125   .AP "const char" *channelName in
   126    126   The name of this channel, such as \fBfile3\fR; must not be in use
   127    127   by any other channel. Can be NULL, in which case the channel is
   128    128   created without a name. If the created channel is assigned to one
   129    129   of the standard channels (\fBstdin\fR, \fBstdout\fR or \fBstderr\fR),
   130    130   the assigned channel name will be the name of the standard channel.
   131         -.AP ClientData instanceData in
          131  +.AP void *instanceData in
   132    132   Arbitrary one-word value to be associated with this channel.  This
   133    133   value is passed to procedures in \fItypePtr\fR when they are invoked.
   134    134   .AP int mask in
   135    135   OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
   136    136   whether a channel is readable and writable.
   137    137   .AP Tcl_Channel channel in
   138    138   The channel to operate on.
   139    139   .AP int direction in
   140    140   \fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
   141    141   means the output handle is wanted.
   142         -.AP ClientData *handlePtr out
          142  +.AP void **handlePtr out
   143    143   Points to the location where the desired OS-specific handle should be
   144    144   stored.
   145    145   .AP int size in
   146    146   The size, in bytes, of buffers to allocate in this channel.
   147    147   .AP int mask in
   148    148   An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
   149    149   and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
................................................................................
   395    395   .PP
   396    396   The \fIblockModeProc\fR field contains the address of a function called by
   397    397   the generic layer to set blocking and nonblocking mode on the device.
   398    398   \fIBlockModeProc\fR should match the following prototype:
   399    399   .PP
   400    400   .CS
   401    401   typedef int \fBTcl_DriverBlockModeProc\fR(
   402         -        ClientData \fIinstanceData\fR,
          402  +        void *\fIinstanceData\fR,
   403    403           int \fImode\fR);
   404    404   .CE
   405    405   .PP
   406    406   The \fIinstanceData\fR is the same as the value passed to
   407    407   \fBTcl_CreateChannel\fR when this channel was created.  The \fImode\fR
   408    408   argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to
   409    409   set the device into blocking or nonblocking mode. The function should
................................................................................
   430    430   .PP
   431    431   The \fIcloseProc\fR field contains the address of a function called by the
   432    432   generic layer to clean up driver-related information when the channel is
   433    433   closed. \fICloseProc\fR must match the following prototype:
   434    434   .PP
   435    435   .CS
   436    436   typedef int \fBTcl_DriverCloseProc\fR(
   437         -        ClientData \fIinstanceData\fR,
          437  +        void *\fIinstanceData\fR,
   438    438           Tcl_Interp *\fIinterp\fR);
   439    439   .CE
   440    440   .PP
   441    441   The \fIinstanceData\fR argument is the same as the value provided to
   442    442   \fBTcl_CreateChannel\fR when the channel was created. The function should
   443    443   release any storage maintained by the channel driver for this channel, and
   444    444   close the input and output devices encapsulated by this channel. All queued
................................................................................
   452    452   Alternatively, channels that support closing the read and write sides
   453    453   independently may set \fIcloseProc\fR to \fBTCL_CLOSE2PROC\fR and set
   454    454   \fIclose2Proc\fR to the address of a function that matches the
   455    455   following prototype:
   456    456   .PP
   457    457   .CS
   458    458   typedef int \fBTcl_DriverClose2Proc\fR(
   459         -        ClientData \fIinstanceData\fR,
          459  +        void *\fIinstanceData\fR,
   460    460           Tcl_Interp *\fIinterp\fR,
   461    461           int \fIflags\fR);
   462    462   .CE
   463    463   .PP
   464    464   The \fIclose2Proc\fR will be called with \fIflags\fR set to an OR'ed
   465    465   combination of \fBTCL_CLOSE_READ\fR or \fBTCL_CLOSE_WRITE\fR to
   466    466   indicate that the driver should close the read and/or write side of
................................................................................
   483    483   .PP
   484    484   The \fIinputProc\fR field contains the address of a function called by the
   485    485   generic layer to read data from the file or device and store it in an
   486    486   internal buffer. \fIInputProc\fR must match the following prototype:
   487    487   .PP
   488    488   .CS
   489    489   typedef int \fBTcl_DriverInputProc\fR(
   490         -        ClientData \fIinstanceData\fR,
          490  +        void *\fIinstanceData\fR,
   491    491           char *\fIbuf\fR,
   492    492           int \fIbufSize\fR,
   493    493           int *\fIerrorCodePtr\fR);
   494    494   .CE
   495    495   .PP
   496    496   \fIInstanceData\fR is the same as the value passed to
   497    497   \fBTcl_CreateChannel\fR when the channel was created.  The \fIbuf\fR
................................................................................
   527    527   .PP
   528    528   The \fIoutputProc\fR field contains the address of a function called by the
   529    529   generic layer to transfer data from an internal buffer to the output device.
   530    530   \fIOutputProc\fR must match the following prototype:
   531    531   .PP
   532    532   .CS
   533    533   typedef int \fBTcl_DriverOutputProc\fR(
   534         -        ClientData \fIinstanceData\fR,
          534  +        void *\fIinstanceData\fR,
   535    535           const char *\fIbuf\fR,
   536    536           int \fItoWrite\fR,
   537    537           int *\fIerrorCodePtr\fR);
   538    538   .CE
   539    539   .PP
   540    540   \fIInstanceData\fR is the same as the value passed to
   541    541   \fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
................................................................................
   566    566   The \fIseekProc\fR field contains the address of a function called by the
   567    567   generic layer to move the access point at which subsequent input or output
   568    568   operations will be applied. \fISeekProc\fR must match the following
   569    569   prototype:
   570    570   .PP
   571    571   .CS
   572    572   typedef int \fBTcl_DriverSeekProc\fR(
   573         -        ClientData \fIinstanceData\fR,
          573  +        void *\fIinstanceData\fR,
   574    574           long \fIoffset\fR,
   575    575           int \fIseekMode\fR,
   576    576           int *\fIerrorCodePtr\fR);
   577    577   .CE
   578    578   .PP
   579    579   The \fIinstanceData\fR argument is the same as the value given to
   580    580   \fBTcl_CreateChannel\fR when this channel was created.  \fIOffset\fR and
................................................................................
   596    596   within files larger than 2GB.  The \fIwideSeekProc\fR will be called
   597    597   in preference to the \fIseekProc\fR, but both must be defined if the
   598    598   \fIwideSeekProc\fR is defined.  \fIWideSeekProc\fR must match the
   599    599   following prototype:
   600    600   .PP
   601    601   .CS
   602    602   typedef Tcl_WideInt \fBTcl_DriverWideSeekProc\fR(
   603         -        ClientData \fIinstanceData\fR,
          603  +        void *\fIinstanceData\fR,
   604    604           Tcl_WideInt \fIoffset\fR,
   605    605           int \fIseekMode\fR,
   606    606           int *\fIerrorCodePtr\fR);
   607    607   .CE
   608    608   .PP
   609    609   The arguments and return values mean the same thing as with
   610    610   \fIseekProc\fR above, except that the type of offsets and the return
................................................................................
   618    618   .PP
   619    619   The \fIsetOptionProc\fR field contains the address of a function called by
   620    620   the generic layer to set a channel type specific option on a channel.
   621    621   \fIsetOptionProc\fR must match the following prototype:
   622    622   .PP
   623    623   .CS
   624    624   typedef int \fBTcl_DriverSetOptionProc\fR(
   625         -        ClientData \fIinstanceData\fR,
          625  +        void *\fIinstanceData\fR,
   626    626           Tcl_Interp *\fIinterp\fR,
   627    627           const char *\fIoptionName\fR,
   628    628           const char *\fInewValue\fR);
   629    629   .CE
   630    630   .PP
   631    631   \fIoptionName\fR is the name of an option to set, and \fInewValue\fR is
   632    632   the new value for that option, as a string. The \fIinstanceData\fR is the
................................................................................
   659    659   .PP
   660    660   The \fIgetOptionProc\fR field contains the address of a function called by
   661    661   the generic layer to get the value of a channel type specific option on a
   662    662   channel. \fIgetOptionProc\fR must match the following prototype:
   663    663   .PP
   664    664   .CS
   665    665   typedef int \fBTcl_DriverGetOptionProc\fR(
   666         -        ClientData \fIinstanceData\fR,
          666  +        void *\fIinstanceData\fR,
   667    667           Tcl_Interp *\fIinterp\fR,
   668    668           const char *\fIoptionName\fR,
   669    669           Tcl_DString *\fIoptionValue\fR);
   670    670   .CE
   671    671   .PP
   672    672   \fIOptionName\fR is the name of an option supported by this type of
   673    673   channel. If the option name is not NULL, the function stores its current
................................................................................
   697    697   The \fIwatchProc\fR field contains the address of a function called
   698    698   by the generic layer to initialize the event notification mechanism to
   699    699   notice events of interest on this channel.
   700    700   \fIWatchProc\fR should match the following prototype:
   701    701   .PP
   702    702   .CS
   703    703   typedef void \fBTcl_DriverWatchProc\fR(
   704         -        ClientData \fIinstanceData\fR,
          704  +        void *\fIinstanceData\fR,
   705    705           int \fImask\fR);
   706    706   .CE
   707    707   .PP
   708    708   The \fIinstanceData\fR is the same as the value passed to
   709    709   \fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
   710    710   argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
   711    711   and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
................................................................................
   728    728   .PP
   729    729   The \fIgetHandleProc\fR field contains the address of a function called by
   730    730   the generic layer to retrieve a device-specific handle from the channel.
   731    731   \fIGetHandleProc\fR should match the following prototype:
   732    732   .PP
   733    733   .CS
   734    734   typedef int \fBTcl_DriverGetHandleProc\fR(
   735         -        ClientData \fIinstanceData\fR,
          735  +        void *\fIinstanceData\fR,
   736    736           int \fIdirection\fR,
   737         -        ClientData *\fIhandlePtr\fR);
          737  +        void **\fIhandlePtr\fR);
   738    738   .CE
   739    739   .PP
   740    740   \fIInstanceData\fR is the same as the value passed to
   741    741   \fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
   742    742   argument is either \fBTCL_READABLE\fR to retrieve the handle used
   743    743   for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
   744    744   output.
................................................................................
   757    757   .PP
   758    758   The \fIflushProc\fR field is currently reserved for future use.
   759    759   It should be set to NULL.
   760    760   \fIFlushProc\fR should match the following prototype:
   761    761   .PP
   762    762   .CS
   763    763   typedef int \fBTcl_DriverFlushProc\fR(
   764         -        ClientData \fIinstanceData\fR);
          764  +        void *\fIinstanceData\fR);
   765    765   .CE
   766    766   .PP
   767    767   This value can be retrieved with \fBTcl_ChannelFlushProc\fR, which returns
   768    768   a pointer to the function.
   769    769   .SS HANDLERPROC
   770    770   .PP
   771    771   The \fIhandlerProc\fR field contains the address of a function called by
................................................................................
   772    772   the generic layer to notify the channel that an event occurred.  It should
   773    773   be defined for stacked channel drivers that wish to be notified of events
   774    774   that occur on the underlying (stacked) channel.
   775    775   \fIHandlerProc\fR should match the following prototype:
   776    776   .PP
   777    777   .CS
   778    778   typedef int \fBTcl_DriverHandlerProc\fR(
   779         -        ClientData \fIinstanceData\fR,
          779  +        void *\fIinstanceData\fR,
   780    780           int \fIinterestMask\fR);
   781    781   .CE
   782    782   .PP
   783    783   \fIInstanceData\fR is the same as the value passed to \fBTcl_CreateChannel\fR
   784    784   when this channel was created.  The \fIinterestMask\fR is an OR-ed
   785    785   combination of \fBTCL_READABLE\fR or \fBTCL_WRITABLE\fR; it indicates what
   786    786   type of event occurred on this channel.
................................................................................
   801    801   The action \fITCL_CHANNEL_THREAD_INSERT\fR is used to notify the
   802    802   driver that it should update or initialize any thread-specific data it
   803    803   might be maintaining using the calling thread as the associate. See
   804    804   \fBTcl_CutChannel\fR and \fBTcl_SpliceChannel\fR for more detail.
   805    805   .PP
   806    806   .CS
   807    807   typedef void \fBTcl_DriverThreadActionProc\fR(
   808         -        ClientData \fIinstanceData\fR,
          808  +        void *\fIinstanceData\fR,
   809    809           int \fIaction\fR);
   810    810   .CE
   811    811   .PP
   812    812   \fIInstanceData\fR is the same as the value passed to
   813    813   \fBTcl_CreateChannel\fR when this channel was created.
   814    814   .PP
   815    815   These values can be retrieved with \fBTcl_ChannelThreadActionProc\fR,
................................................................................
   818    818   .PP
   819    819   The \fItruncateProc\fR field contains the address of the function
   820    820   called by the generic layer when a channel is truncated to some
   821    821   length. It can be NULL.
   822    822   .PP
   823    823   .CS
   824    824   typedef int \fBTcl_DriverTruncateProc\fR(
   825         -        ClientData \fIinstanceData\fR,
          825  +        void *\fIinstanceData\fR,
   826    826           Tcl_WideInt \fIlength\fR);
   827    827   .CE
   828    828   .PP
   829    829   \fIInstanceData\fR is the same as the value passed to
   830    830   \fBTcl_CreateChannel\fR when this channel was created, and
   831    831   \fIlength\fR is the new length of the underlying file, which should
   832    832   not be negative. The result should be 0 on success or an errno code

Changes to doc/CrtChnlHdlr.3.

    28     28   .AP int mask in
    29     29   Conditions under which \fIproc\fR should be called: OR-ed combination of
    30     30   \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify
    31     31   a zero value to temporarily disable an existing handler.
    32     32   .AP Tcl_FileProc *proc in
    33     33   Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
    34     34   the conditions specified by \fImask\fR.
    35         -.AP ClientData clientData in
           35  +.AP void *clientData in
    36     36   Arbitrary one-word value to pass to \fIproc\fR.
    37     37   .BE
    38     38   .SH DESCRIPTION
    39     39   .PP
    40     40   \fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the
    41     41   future whenever input or output becomes possible on the channel identified
    42     42   by \fIchannel\fR, or whenever an exceptional condition exists for
................................................................................
    44     44   invoked are specified by the \fImask\fR argument.
    45     45   See the manual entry for \fBfileevent\fR for a precise description of
    46     46   what it means for a channel to be readable or writable.
    47     47   \fIProc\fR must conform to the following prototype:
    48     48   .PP
    49     49   .CS
    50     50   typedef void \fBTcl_ChannelProc\fR(
    51         -        ClientData \fIclientData\fR,
           51  +        void *\fIclientData\fR,
    52     52           int \fImask\fR);
    53     53   .CE
    54     54   .PP
    55     55   The \fIclientData\fR argument is the same as the value passed to
    56     56   \fBTcl_CreateChannelHandler\fR when the handler was created. Typically,
    57     57   \fIclientData\fR points to a data structure containing application-specific
    58     58   information about the channel. \fIMask\fR is an integer mask indicating

Changes to doc/CrtCloseHdlr.3.

    22     22   .sp
    23     23   .SH ARGUMENTS
    24     24   .AS Tcl_CloseProc clientData
    25     25   .AP Tcl_Channel channel in
    26     26   The channel for which to create or delete a close callback.
    27     27   .AP Tcl_CloseProc *proc in
    28     28   The procedure to call as the callback.
    29         -.AP ClientData clientData in
           29  +.AP void *clientData in
    30     30   Arbitrary one-word value to pass to \fIproc\fR.
    31     31   .BE
    32     32   .SH DESCRIPTION
    33     33   .PP
    34     34   \fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when
    35     35   \fIchannel\fR is closed with \fBTcl_Close\fR or
    36     36   \fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command.
    37     37   \fIProc\fR should match the following prototype:
    38     38   .PP
    39     39   .CS
    40     40   typedef void \fBTcl_CloseProc\fR(
    41         -        ClientData \fIclientData\fR);
           41  +        void *\fIclientData\fR);
    42     42   .CE
    43     43   .PP
    44     44   The \fIclientData\fR is the same as the value provided in the call to
    45     45   \fBTcl_CreateCloseHandler\fR.
    46     46   .PP
    47     47   \fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR.
    48     48   The \fIproc\fR and \fIclientData\fR identify which close callback to

Changes to doc/CrtCommand.3.

    21     21   .AP Tcl_Interp *interp in
    22     22   Interpreter in which to create new command.
    23     23   .AP "const char" *cmdName in
    24     24   Name of command.
    25     25   .AP Tcl_CmdProc *proc in
    26     26   Implementation of new command:  \fIproc\fR will be called whenever
    27     27   \fIcmdName\fR is invoked as a command.
    28         -.AP ClientData clientData in
           28  +.AP voie *clientData in
    29     29   Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
    30     30   .AP Tcl_CmdDeleteProc *deleteProc in
    31     31   Procedure to call before \fIcmdName\fR is deleted from the interpreter;
    32     32   allows for command-specific cleanup.  If NULL, then no procedure is
    33     33   called before the command is deleted.
    34     34   .BE
    35     35   .SH DESCRIPTION
................................................................................
    71     71   the process of being deleted, then it does not create a new command
    72     72   and it returns NULL.
    73     73   \fIProc\fR should have arguments and result that match the type
    74     74   \fBTcl_CmdProc\fR:
    75     75   .PP
    76     76   .CS
    77     77   typedef int \fBTcl_CmdProc\fR(
    78         -        ClientData \fIclientData\fR,
           78  +        void *\fIclientData\fR,
    79     79           Tcl_Interp *\fIinterp\fR,
    80     80           int \fIargc\fR,
    81     81           const char *\fIargv\fR[]);
    82     82   .CE
    83     83   .PP
    84     84   When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
    85     85   parameters will be copies of the \fIclientData\fR and \fIinterp\fR
................................................................................
   127    127   \fIDeleteProc\fR is invoked before the command is deleted, and gives the
   128    128   application an opportunity to release any structures associated
   129    129   with the command.  \fIDeleteProc\fR should have arguments and
   130    130   result that match the type \fBTcl_CmdDeleteProc\fR:
   131    131   .PP
   132    132   .CS
   133    133   typedef void \fBTcl_CmdDeleteProc\fR(
   134         -        ClientData \fIclientData\fR);
          134  +        void *\fIclientData\fR);
   135    135   .CE
   136    136   .PP
   137    137   The \fIclientData\fR argument will be the same as the \fIclientData\fR
   138    138   argument passed to \fBTcl_CreateCommand\fR.
   139    139   .SH "SEE ALSO"
   140    140   Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo,
   141    141   Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
   142    142   .SH KEYWORDS
   143    143   bind, command, create, delete, interpreter, namespace

Changes to doc/CrtFileHdlr.3.

    25     25   Conditions under which \fIproc\fR should be called:
    26     26   OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
    27     27   and \fBTCL_EXCEPTION\fR.  May be set to 0 to temporarily disable
    28     28   a handler.
    29     29   .AP Tcl_FileProc *proc in
    30     30   Procedure to invoke whenever the file or device indicated
    31     31   by \fIfile\fR meets the conditions specified by \fImask\fR.
    32         -.AP ClientData clientData in
           32  +.AP void *clientData in
    33     33   Arbitrary one-word value to pass to \fIproc\fR.
    34     34   .BE
    35     35   .SH DESCRIPTION
    36     36   .PP
    37     37   \fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
    38     38   invoked in the future whenever I/O becomes possible on a file
    39     39   or an exceptional condition exists for the file.  The file
................................................................................
    47     47   as \fBvwait\fR.
    48     48   .PP
    49     49   \fIProc\fR should have arguments and result that match the
    50     50   type \fBTcl_FileProc\fR:
    51     51   .PP
    52     52   .CS
    53     53   typedef void \fBTcl_FileProc\fR(
    54         -        ClientData \fIclientData\fR,
           54  +        void *\fIclientData\fR,
    55     55           int \fImask\fR);
    56     56   .CE
    57     57   .PP
    58     58   The \fIclientData\fR parameter to \fIproc\fR is a copy
    59     59   of the \fIclientData\fR
    60     60   argument given to \fBTcl_CreateFileHandler\fR when the callback
    61     61   was created.  Typically, \fIclientData\fR points to a data

Changes to doc/CrtObjCmd.3.

     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7      7   .TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
     8      8   .so man.macros
     9      9   .BS
    10     10   .SH NAME
    11         -Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj \- implement new commands in C
           11  +Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_GetCommandInfoFromToken, Tcl_SetCommandInfo, Tcl_SetCommandInfoFromToken, Tcl_GetCommandName, Tcl_GetCommandFullName, Tcl_GetCommandFromObj, Tcl_RegisterCommandTypeName, Tcl_GetCommandTypeName \- implement new commands in C
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16     16   Tcl_Command
    17     17   \fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
    18     18   .sp
................................................................................
    38     38   \fBTcl_GetCommandName\fR(\fIinterp, token\fR)
    39     39   .sp
    40     40   void
    41     41   \fBTcl_GetCommandFullName\fR(\fIinterp, token, objPtr\fR)
    42     42   .sp
    43     43   Tcl_Command
    44     44   \fBTcl_GetCommandFromObj\fR(\fIinterp, objPtr\fR)
           45  +.sp
           46  +.VS "info cmdtype feature"
           47  +void
           48  +\fBTcl_RegisterCommandTypeName\fR(\fIproc, typeName\fR)
           49  +.sp
           50  +const char *
           51  +\fBTcl_GetCommandTypeName\fR(\fItoken\fR)
           52  +.VE "info cmdtype feature"
    45     53   .SH ARGUMENTS
    46     54   .AS Tcl_CmdDeleteProc *deleteProc in/out
    47     55   .AP Tcl_Interp *interp in
    48     56   Interpreter in which to create a new command or that contains a command.
    49     57   .AP char *cmdName in
    50     58   Name of command.
    51     59   .AP Tcl_ObjCmdProc *proc in
    52     60   Implementation of the new command: \fIproc\fR will be called whenever
    53     61   \fIcmdName\fR is invoked as a command.
    54         -.AP ClientData clientData in
           62  +.AP void *clientData in
    55     63   Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
    56     64   .AP Tcl_CmdDeleteProc *deleteProc in
    57     65   Procedure to call before \fIcmdName\fR is deleted from the interpreter;
    58     66   allows for command-specific cleanup. If NULL, then no procedure is
    59     67   called before the command is deleted.
    60     68   .AP Tcl_Command token in
    61     69   Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
    62     70   The command must not have been deleted.
    63     71   .AP Tcl_CmdInfo *infoPtr in/out
    64     72   Pointer to structure containing various information about a
    65     73   Tcl command.
    66     74   .AP Tcl_Obj *objPtr in
    67     75   Value containing the name of a Tcl command.
           76  +.AP "const char" *typeName in
           77  +Indicates the name of the type of command implementation associated
           78  +with a particular \fIproc\fR, or NULL to break the association.
    68     79   .BE
    69     80   .SH DESCRIPTION
    70     81   .PP
    71     82   \fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
    72     83   and associates it with procedure \fIproc\fR
    73     84   such that whenever \fIname\fR is
    74     85   invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObjEx\fR)
................................................................................
    87     98   the process of being deleted, then it does not create a new command
    88     99   and it returns NULL.
    89    100   \fIproc\fR should have arguments and result that match the type
    90    101   \fBTcl_ObjCmdProc\fR:
    91    102   .PP
    92    103   .CS
    93    104   typedef int \fBTcl_ObjCmdProc\fR(
    94         -        ClientData \fIclientData\fR,
          105  +        void *\fIclientData\fR,
    95    106           Tcl_Interp *\fIinterp\fR,
    96    107           int \fIobjc\fR,
    97    108           Tcl_Obj *const \fIobjv\fR[]);
    98    109   .CE
    99    110   .PP
   100    111   When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
   101    112   will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
................................................................................
   160    171   \fIDeleteProc\fR is invoked before the command is deleted, and gives the
   161    172   application an opportunity to release any structures associated
   162    173   with the command.  \fIDeleteProc\fR should have arguments and
   163    174   result that match the type \fBTcl_CmdDeleteProc\fR:
   164    175   .PP
   165    176   .CS
   166    177   typedef void \fBTcl_CmdDeleteProc\fR(
   167         -        ClientData \fIclientData\fR);
          178  +        void *\fIclientData\fR);
   168    179   .CE
   169    180   .PP
   170    181   The \fIclientData\fR argument will be the same as the \fIclientData\fR
   171    182   argument passed to \fBTcl_CreateObjCommand\fR.
   172    183   .PP
   173    184   \fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
   174    185   Once the call completes, attempts to invoke \fIcmdName\fR in
................................................................................
   202    213   pointed to by \fIinfoPtr\fR and returns 1.
   203    214   A \fBTcl_CmdInfo\fR structure has the following fields:
   204    215   .PP
   205    216   .CS
   206    217   typedef struct Tcl_CmdInfo {
   207    218       int \fIisNativeObjectProc\fR;
   208    219       Tcl_ObjCmdProc *\fIobjProc\fR;
   209         -    ClientData \fIobjClientData\fR;
          220  +    void *\fIobjClientData\fR;
   210    221       Tcl_CmdProc *\fIproc\fR;
   211         -    ClientData \fIclientData\fR;
          222  +    void *\fIclientData\fR;
   212    223       Tcl_CmdDeleteProc *\fIdeleteProc\fR;
   213         -    ClientData \fIdeleteData\fR;
          224  +    void *\fIdeleteData\fR;
   214    225       Tcl_Namespace *\fInamespacePtr\fR;
   215    226   } \fBTcl_CmdInfo\fR;
   216    227   .CE
   217    228   .PP
   218    229   The \fIisNativeObjectProc\fR field has the value 1
   219    230   if \fBTcl_CreateObjCommand\fR was called to register the command;
   220    231   it is 0 if only \fBTcl_CreateCommand\fR was called.
................................................................................
   232    243   that implements the command.
   233    244   If \fBTcl_CreateCommand\fR was called for this command,
   234    245   this is the procedure passed to it;
   235    246   otherwise, this is a compatibility procedure
   236    247   registered by \fBTcl_CreateObjCommand\fR
   237    248   that simply calls the command's
   238    249   value-based procedure after converting its string arguments to Tcl values.
   239         -The field \fIdeleteData\fR is the ClientData value
          250  +The field \fIdeleteData\fR is the clientData value
   240    251   to pass to \fIdeleteProc\fR;  it is normally the same as
   241    252   \fIclientData\fR but may be set independently using the
   242    253   \fBTcl_SetCommandInfo\fR procedure.
   243    254   The field \fInamespacePtr\fR holds a pointer to the
   244    255   Tcl_Namespace that contains the command.
   245    256   .PP
   246    257   \fBTcl_GetCommandInfoFromToken\fR is identical to
   247    258   \fBTcl_GetCommandInfo\fR except that it uses a command token returned
   248    259   from \fBTcl_CreateObjCommand\fR in place of the command name.  If the
   249    260   \fItoken\fR parameter is NULL, it returns 0; otherwise, it returns 1
   250    261   and fills in the structure designated by \fIinfoPtr\fR.
   251    262   .PP
   252    263   \fBTcl_SetCommandInfo\fR is used to modify the procedures and
   253         -ClientData values associated with a command.
          264  +clientData values associated with a command.
   254    265   Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
   255    266   \fIcmdName\fR may include \fB::\fR namespace qualifiers
   256    267   to identify a command in a particular namespace.
   257    268   If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
   258    269   Otherwise, it copies the information from \fI*infoPtr\fR to
   259    270   Tcl's internal structure for the command and returns 1.
   260    271   .PP
................................................................................
   262    273   \fBTcl_SetCommandInfo\fR except that it takes a command token as
   263    274   returned by \fBTcl_CreateObjCommand\fR instead of the command name.
   264    275   If the \fItoken\fR parameter is NULL, it returns 0.  Otherwise, it
   265    276   copies the information from \fI*infoPtr\fR to Tcl's internal structure
   266    277   for the command and returns 1.
   267    278   .PP
   268    279   Note that \fBTcl_SetCommandInfo\fR and
   269         -\fBTcl_SetCommandInfoFromToken\fR both allow the ClientData for a
          280  +\fBTcl_SetCommandInfoFromToken\fR both allow the clientData for a
   270    281   command's deletion procedure to be given a different value than the
   271         -ClientData for its command procedure.
          282  +clientData for its command procedure.
   272    283   .PP
   273    284   Note that neither \fBTcl_SetCommandInfo\fR nor
   274    285   \fBTcl_SetCommandInfoFromToken\fR will change a command's namespace.
   275    286   Use \fBTcl_Eval\fR to call the \fBrename\fR command to do that.
   276    287   .PP
   277    288   \fBTcl_GetCommandName\fR provides a mechanism for tracking commands
   278    289   that have been renamed.
................................................................................
   292    303   The name, including all namespace prefixes,
   293    304   is appended to the value specified by \fIobjPtr\fR.
   294    305   .PP
   295    306   \fBTcl_GetCommandFromObj\fR returns a token for the command
   296    307   specified by the name in a \fBTcl_Obj\fR.
   297    308   The command name is resolved relative to the current namespace.
   298    309   Returns NULL if the command is not found.
          310  +.PP
          311  +.VS "info cmdtype feature"
          312  +\fBTcl_RegisterCommandTypeName\fR is used to associate a name (the
          313  +\fItypeName\fR argument) with a particular implementation function so that it
          314  +can then be looked up with \fBTcl_GetCommandTypeName\fR, which in turn is
          315  +called with a command token that information is wanted for and which returns
          316  +the name of the type that was registered for the implementation function used
          317  +for that command. (The lookup functionality is surfaced virtually directly in Tcl via
          318  +\fBinfo cmdtype\fR.) If there is no function registered for a particular
          319  +function, the result will be the string literal
          320  +.QW \fBnative\fR .
          321  +The registration of a name can be undone by registering a mapping to NULL
          322  +instead. The result from \fBTcl_GetCommandTypeName\fR will be exactly that
          323  +string which was registered, and not a copy; use of a compile-time constant
          324  +string is \fIstrongly recommended\fR.
          325  +.VE "info cmdtype feature"
   299    326   .SH "SEE ALSO"
   300    327   Tcl_CreateCommand(3), Tcl_ResetResult(3), Tcl_SetObjResult(3)
   301    328   .SH KEYWORDS
   302    329   bind, command, create, delete, namespace, value

Changes to doc/CrtTimerHdlr.3.

    20     20   \fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
    21     21   .SH ARGUMENTS
    22     22   .AS Tcl_TimerToken milliseconds
    23     23   .AP int milliseconds  in
    24     24   How many milliseconds to wait before invoking \fIproc\fR.
    25     25   .AP Tcl_TimerProc *proc in
    26     26   Procedure to invoke after \fImilliseconds\fR have elapsed.
    27         -.AP ClientData clientData in
           27  +.AP void *clientData in
    28     28   Arbitrary one-word value to pass to \fIproc\fR.
    29     29   .AP Tcl_TimerToken token in
    30     30   Token for previously created timer handler (the return value
    31     31   from some previous call to \fBTcl_CreateTimerHandler\fR).
    32     32   .BE
    33     33   .SH DESCRIPTION
    34     34   .PP
................................................................................
    47     47   \fIproc\fR, then the call to \fIproc\fR will be delayed.
    48     48   .PP
    49     49   \fIProc\fR should have arguments and return value that match
    50     50   the type \fBTcl_TimerProc\fR:
    51     51   .PP
    52     52   .CS
    53     53   typedef void \fBTcl_TimerProc\fR(
    54         -        ClientData \fIclientData\fR);
           54  +        void *\fIclientData\fR);
    55     55   .CE
    56     56   .PP
    57     57   The \fIclientData\fR parameter to \fIproc\fR is a
    58     58   copy of the \fIclientData\fR argument given to
    59     59   \fBTcl_CreateTimerHandler\fR when the callback
    60     60   was created.  Typically, \fIclientData\fR points to a data
    61     61   structure containing application-specific information about

Changes to doc/CrtTrace.3.

    37     37   Flags governing the trace execution.  See below for details.
    38     38   .AP Tcl_CmdObjTraceProc *objProc in
    39     39   Procedure to call for each command that is executed.  See below for
    40     40   details of the calling sequence.
    41     41   .AP Tcl_CmdTraceProc *proc in
    42     42   Procedure to call for each command that is executed.  See below for
    43     43   details on the calling sequence.
    44         -.AP ClientData clientData in
           44  +.AP void *clientData in
    45     45   Arbitrary one-word value to pass to \fIobjProc\fR or \fIproc\fR.
    46     46   .AP Tcl_CmdObjTraceDeleteProc *deleteProc in
    47     47   Procedure to call when the trace is deleted.  See below for details of
    48     48   the calling sequence.  A NULL pointer is permissible and results in no
    49     49   callback when the trace is deleted.
    50     50   .AP Tcl_Trace trace in
    51     51   Token for trace to be removed (return value from previous call
................................................................................
    62     62   interpreter.
    63     63   .PP
    64     64   \fIobjProc\fR should have arguments and result that match the type,
    65     65   \fBTcl_CmdObjTraceProc\fR:
    66     66   .PP
    67     67   .CS
    68     68   typedef int \fBTcl_CmdObjTraceProc\fR(
    69         -        \fBClientData\fR \fIclientData\fR,
           69  +        \fBvoid *\fR \fIclientData\fR,
    70     70           \fBTcl_Interp\fR* \fIinterp\fR,
    71     71           int \fIlevel\fR,
    72     72           const char *\fIcommand\fR,
    73     73           \fBTcl_Command\fR \fIcommandToken\fR,
    74     74           int \fIobjc\fR,
    75     75           \fBTcl_Obj\fR *const \fIobjv\fR[]);
    76     76   .CE
    77     77   .PP
    78     78   The \fIclientData\fR and \fIinterp\fR parameters are copies of the
    79     79   corresponding arguments given to \fBTcl_CreateTrace\fR.
    80         -\fIClientData\fR typically points to an application-specific data
           80  +\fIclientData\fR typically points to an application-specific data
    81     81   structure that describes what to do when \fIobjProc\fR is invoked.  The
    82     82   \fIlevel\fR parameter gives the nesting level of the command (1 for
    83     83   top-level commands passed to \fBTcl_Eval\fR by the application, 2 for
    84     84   the next-level commands passed to \fBTcl_Eval\fR as part of parsing or
    85     85   interpreting level-1 commands, and so on). The \fIcommand\fR parameter
    86     86   points to a string containing the text of the command, before any
    87     87   argument substitution.  The \fIcommandToken\fR parameter is a Tcl
................................................................................
   140    140   When \fBTcl_DeleteTrace\fR is called, the interpreter invokes the
   141    141   \fIdeleteProc\fR that was passed as a parameter to
   142    142   \fBTcl_CreateObjTrace\fR.  The \fIdeleteProc\fR must match the type,
   143    143   \fBTcl_CmdObjTraceDeleteProc\fR:
   144    144   .PP
   145    145   .CS
   146    146   typedef void \fBTcl_CmdObjTraceDeleteProc\fR(
   147         -        \fBClientData\fR \fIclientData\fR);
          147  +        \fBvoid *\fR \fIclientData\fR);
   148    148   .CE
   149    149   .PP
   150    150   The \fIclientData\fR parameter will be the same as the
   151    151   \fIclientData\fR parameter that was originally passed to
   152    152   \fBTcl_CreateObjTrace\fR.
   153    153   .PP
   154    154   \fBTcl_CreateTrace\fR is an alternative interface for command tracing,
................................................................................
   156    156   compatibility with code that was developed for older versions of the
   157    157   Tcl interpreter.  It is similar to \fBTcl_CreateObjTrace\fR, except
   158    158   that its \fIproc\fR parameter should have arguments and result that
   159    159   match the type \fBTcl_CmdTraceProc\fR:
   160    160   .PP
   161    161   .CS
   162    162   typedef void \fBTcl_CmdTraceProc\fR(
   163         -        ClientData \fIclientData\fR,
          163  +        void *\fIclientData\fR,
   164    164           Tcl_Interp *\fIinterp\fR,
   165    165           int \fIlevel\fR,
   166    166           char *\fIcommand\fR,
   167    167           Tcl_CmdProc *\fIcmdProc\fR,
   168         -        ClientData \fIcmdClientData\fR,
          168  +        void *\fIcmdClientData\fR,
   169    169           int \fIargc\fR,
   170    170           const char *\fIargv\fR[]);
   171    171   .CE
   172    172   .PP
   173    173   The parameters to the \fIproc\fR callback are similar to those of the
   174    174   \fIobjProc\fR callback above. The \fIcommandToken\fR is
   175    175   replaced with \fIcmdProc\fR, a pointer to the (string-based) command

Changes to doc/DString.3.

    22     22   char *
    23     23   \fBTcl_DStringAppendElement\fR(\fIdsPtr, element\fR)
    24     24   .sp
    25     25   \fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
    26     26   .sp
    27     27   \fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
    28     28   .sp
    29         -int
           29  +size_t
    30     30   \fBTcl_DStringLength\fR(\fIdsPtr\fR)
    31     31   .sp
    32     32   char *
    33     33   \fBTcl_DStringValue\fR(\fIdsPtr\fR)
    34     34   .sp
    35     35   \fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
    36     36   .sp
................................................................................
    43     43   .AS Tcl_DString newLength in/out
    44     44   .AP Tcl_DString *dsPtr in/out
    45     45   Pointer to structure that is used to manage a dynamic string.
    46     46   .AP "const char" *bytes in
    47     47   Pointer to characters to append to dynamic string.
    48     48   .AP "const char" *element in
    49     49   Pointer to characters to append as list element to dynamic string.
    50         -.AP int length in
    51         -Number of bytes from \fIbytes\fR to add to dynamic string.  If -1,
           50  +.AP size_t length in
           51  +Number of bytes from \fIbytes\fR to add to dynamic string.  If TCL_AUTO_LENGTH,
    52     52   add all characters up to null terminating character.
    53         -.AP int newLength in
           53  +.AP size_t newLength in
    54     54   New length for dynamic string, not including null terminating
    55     55   character.
    56     56   .AP Tcl_Interp *interp in/out
    57     57   Interpreter whose result is to be set from or moved to the
    58     58   dynamic string.
    59     59   .BE
    60     60   

Changes to doc/DoWhenIdle.3.

    17     17   \fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
    18     18   .sp
    19     19   \fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
    20     20   .SH ARGUMENTS
    21     21   .AS Tcl_IdleProc clientData
    22     22   .AP Tcl_IdleProc *proc in
    23     23   Procedure to invoke.
    24         -.AP ClientData clientData in
           24  +.AP coid *clientData in
    25     25   Arbitrary one-word value to pass to \fIproc\fR.
    26     26   .BE
    27     27   .SH DESCRIPTION
    28     28   .PP
    29     29   \fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
    30     30   when the application becomes idle.  The application is
    31     31   considered to be idle when \fBTcl_DoOneEvent\fR has been
................................................................................
    39     39   use \fBTcl_DoOneEvent\fR to dispatch events.
    40     40   .PP
    41     41   \fIProc\fR should have arguments and result that match the
    42     42   type \fBTcl_IdleProc\fR:
    43     43   .PP
    44     44   .CS
    45     45   typedef void \fBTcl_IdleProc\fR(
    46         -        ClientData \fIclientData\fR);
           46  +        void *\fIclientData\fR);
    47     47   .CE
    48     48   .PP
    49     49   The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
    50     50   argument given to \fBTcl_DoWhenIdle\fR.  Typically, \fIclientData\fR
    51     51   points to a data structure containing application-specific information about
    52     52   what \fIproc\fR should do.
    53     53   .PP

Changes to doc/DumpActiveMemory.3.

    39     39   They are only functional when Tcl has been compiled with
    40     40   \fBTCL_MEM_DEBUG\fR defined at compile-time.  When \fBTCL_MEM_DEBUG\fR
    41     41   is not defined, these functions are all no-ops.
    42     42   .PP
    43     43   \fBTcl_DumpActiveMemory\fR will output a list of all currently
    44     44   allocated memory to the specified file.  The information output for
    45     45   each allocated block of memory is:  starting and ending addresses
    46         -(excluding guard zone), size, source file where \fBckalloc\fR was
           46  +(excluding guard zone), size, source file where \fBTcl_Alloc\fR was
    47     47   called to allocate the block and line number in that file.  It is
    48     48   especially useful to call \fBTcl_DumpActiveMemory\fR after the Tcl
    49     49   interpreter has been deleted.
    50     50   .PP
    51     51   \fBTcl_InitMemory\fR adds the Tcl \fBmemory\fR command to the
    52     52   interpreter given by \fIinterp\fR.  \fBTcl_InitMemory\fR is called
    53     53   by \fBTcl_Main\fR.
    54     54   .PP
    55     55   \fBTcl_ValidateAllMemory\fR forces a validation of the guard zones of
    56     56   all currently allocated blocks of memory.  Normally validation of a
    57     57   block occurs when its freed, unless full validation is enabled, in
    58         -which case validation of all blocks occurs when \fBckalloc\fR and
    59         -\fBckfree\fR are called.  This function forces the validation to occur
           58  +which case validation of all blocks occurs when \fBTcl_Alloc\fR and
           59  +\fBTcl_Free\fR are called.  This function forces the validation to occur
    60     60   at any point.
    61     61   
    62     62   .SH "SEE ALSO"
    63     63   TCL_MEM_DEBUG, memory
    64     64   
    65     65   .SH KEYWORDS
    66     66   memory, debug
    67     67   
    68     68   

Changes to doc/Encoding.3.

    79     79   .AP "const char" *src in
    80     80   For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
    81     81   specified encoding that are to be converted to UTF-8.  For the
    82     82   \fBTcl_UtfToExternal\fR and \fBTcl_WinUtfToTChar\fR functions, an array of
    83     83   UTF-8 characters to be converted to the specified encoding.
    84     84   .AP "const TCHAR" *tsrc in
    85     85   An array of Windows TCHAR characters to convert to UTF-8.
    86         -.AP int srcLen in
           86  +.AP size_t srcLen in
    87     87   Length of \fIsrc\fR or \fItsrc\fR in bytes.  If the length is negative, the
    88     88   encoding-specific length of the string is used.
    89     89   .AP Tcl_DString *dstPtr out
    90     90   Pointer to an uninitialized or free \fBTcl_DString\fR in which the converted
    91     91   result will be stored.
    92     92   .AP int flags in
    93     93   Various flag bits OR-ed together.
................................................................................
   304    304   .PP
   305    305   .CS
   306    306   typedef struct Tcl_EncodingType {
   307    307       const char *\fIencodingName\fR;
   308    308       Tcl_EncodingConvertProc *\fItoUtfProc\fR;
   309    309       Tcl_EncodingConvertProc *\fIfromUtfProc\fR;
   310    310       Tcl_EncodingFreeProc *\fIfreeProc\fR;
   311         -    ClientData \fIclientData\fR;
          311  +    void *\fIclientData\fR;
   312    312       int \fInullSize\fR;
   313    313   } \fBTcl_EncodingType\fR;
   314    314   .CE
   315    315   .PP
   316    316   The \fIencodingName\fR provides a string name for the encoding, by
   317    317   which it can be referred in other procedures such as
   318    318   \fBTcl_GetEncoding\fR.  The \fItoUtfProc\fR refers to a callback
................................................................................
   335    335   CNS11643) are not accepted.
   336    336   .PP
   337    337   The callback procedures \fItoUtfProc\fR and \fIfromUtfProc\fR should match the
   338    338   type \fBTcl_EncodingConvertProc\fR:
   339    339   .PP
   340    340   .CS
   341    341   typedef int \fBTcl_EncodingConvertProc\fR(
   342         -        ClientData \fIclientData\fR,
          342  +        void *\fIclientData\fR,
   343    343           const char *\fIsrc\fR,
   344    344           int \fIsrcLen\fR,
   345    345           int \fIflags\fR,
   346    346           Tcl_EncodingState *\fIstatePtr\fR,
   347    347           char *\fIdst\fR,
   348    348           int \fIdstLen\fR,
   349    349           int *\fIsrcReadPtr\fR,
................................................................................
   367    367   procedure will be a non-NULL location.
   368    368   .PP
   369    369   The callback procedure \fIfreeProc\fR, if non-NULL, should match the type
   370    370   \fBTcl_EncodingFreeProc\fR:
   371    371   .PP
   372    372   .CS
   373    373   typedef void \fBTcl_EncodingFreeProc\fR(
   374         -        ClientData \fIclientData\fR);
          374  +        void *\fIclientData\fR);
   375    375   .CE
   376    376   .PP
   377    377   This \fIfreeProc\fR function is called when the encoding is deleted.  The
   378    378   \fIclientData\fR parameter is the same as the \fIclientData\fR field
   379    379   specified to \fBTcl_CreateEncoding\fR when the encoding was created.
   380    380   .PP
   381    381   \fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR

Changes to doc/Exit.3.

    38     38   Exact meaning may
    39     39   be platform-specific.  0 usually means a normal exit, any nonzero value
    40     40   usually means that an error occurred.
    41     41   .AP Tcl_ExitProc *proc in
    42     42   Procedure to invoke before exiting application, or (for
    43     43   \fBTcl_SetExitProc\fR) NULL to uninstall the current application exit
    44     44   procedure.
    45         -.AP ClientData clientData in
           45  +.AP void *clientData in
    46     46   Arbitrary one-word value to pass to \fIproc\fR.
    47     47   .BE
    48     48   
    49     49   .SH DESCRIPTION
    50     50   .PP
    51     51   The procedures described here provide a graceful mechanism to end the
    52     52   execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
................................................................................
    60     60   Note that if other code invokes \fBexit\fR system procedure directly, or
    61     61   otherwise causes the application to terminate without calling
    62     62   \fBTcl_Exit\fR, the exit handlers will not be run.
    63     63   \fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
    64     64   returns control to its caller.
    65     65   If an application exit handler has been installed (see
    66     66   \fBTcl_SetExitProc\fR), that handler is invoked with an argument
    67         -consisting of the exit status (cast to ClientData); the application
           67  +consisting of the exit status (cast to void *); the application
    68     68   exit handler should not return control to Tcl.
    69     69   .PP
    70     70   \fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
    71     71   exit from the current process.
    72     72   It is useful for cleaning up when a process is finished using \fBTcl\fR but
    73     73   wishes to continue executing, and when \fBTcl\fR is used in a dynamically
    74     74   loaded extension that is about to be unloaded.
................................................................................
    89     89   by \fBTcl_FinalizeThread\fR and \fBTcl_ExitThread\fR.
    90     90   This provides a hook for cleanup operations such as flushing buffers
    91     91   and freeing global memory.
    92     92   \fIProc\fR should match the type \fBTcl_ExitProc\fR:
    93     93   .PP
    94     94   .CS
    95     95   typedef void \fBTcl_ExitProc\fR(
    96         -        ClientData \fIclientData\fR);
           96  +        void *\fIclientData\fR);
    97     97   .CE
    98     98   .PP
    99     99   The \fIclientData\fR parameter to \fIproc\fR is a
   100    100   copy of the \fIclientData\fR argument given to
   101    101   \fBTcl_CreateExitHandler\fR or \fBTcl_CreateThreadExitHandler\fR when
   102    102   the callback
   103    103   was created.  Typically, \fIclientData\fR points to a data
................................................................................
   129    129   \fBTcl_SetExitProc\fR installs an application exit handler, returning
   130    130   the previously-installed application exit handler or NULL if no
   131    131   application handler was installed.  If an application exit handler is
   132    132   installed, that exit handler takes over complete responsibility for
   133    133   finalization of Tcl's subsystems via \fBTcl_Finalize\fR at an
   134    134   appropriate time.  The argument passed to \fIproc\fR when it is
   135    135   invoked will be the exit status code (as passed to \fBTcl_Exit\fR)
   136         -cast to a ClientData value.
          136  +cast to a void *value.
          137  +.PP
          138  +\fBTcl_SetExitProc\fR can not be used in stub-enabled extensions.
   137    139   .SH "SEE ALSO"
   138    140   exit(n)
   139    141   .SH KEYWORDS
   140    142   abort, callback, cleanup, dynamic loading, end application, exit, unloading, thread

Changes to doc/FileSystem.3.

    16     16   .sp
    17     17   int
    18     18   \fBTcl_FSRegister\fR(\fIclientData, fsPtr\fR)
    19     19   .sp
    20     20   int
    21     21   \fBTcl_FSUnregister\fR(\fIfsPtr\fR)
    22     22   .sp
    23         -ClientData
           23  +void *
    24     24   \fBTcl_FSData\fR(\fIfsPtr\fR)
    25     25   .sp
    26     26   void
    27     27   \fBTcl_FSMountsChanged\fR(\fIfsPtr\fR)
    28     28   .sp
    29     29   const Tcl_Filesystem *
    30     30   \fBTcl_FSGetFileSystemForPath\fR(\fIpathPtr\fR)
................................................................................
   121    121   .sp
   122    122   Tcl_Obj *
   123    123   \fBTcl_FSJoinToPath\fR(\fIbasePtr, objc, objv\fR)
   124    124   .sp
   125    125   int
   126    126   \fBTcl_FSConvertToPathType\fR(\fIinterp, pathPtr\fR)
   127    127   .sp
   128         -ClientData
          128  +void *
   129    129   \fBTcl_FSGetInternalRep\fR(\fIpathPtr, fsPtr\fR)
   130    130   .sp
   131    131   Tcl_Obj *
   132    132   \fBTcl_FSGetTranslatedPath\fR(\fIinterp, pathPtr\fR)
   133    133   .sp
   134    134   const char *
   135    135   \fBTcl_FSGetTranslatedStringPath\fR(\fIinterp, pathPtr\fR)
................................................................................
   208    208   Only files or directories matching this pattern will be returned.
   209    209   .AP Tcl_GlobTypeData *types in
   210    210   Only files or directories matching the type descriptions contained in
   211    211   this structure will be returned. This parameter may be NULL.
   212    212   .AP Tcl_Interp *interp in
   213    213   Interpreter to use either for results, evaluation, or reporting error
   214    214   messages.
   215         -.AP ClientData clientData in
          215  +.AP void *clientData in
   216    216   The native description of the path value to create.
   217    217   .AP Tcl_Obj *firstPtr in
   218    218   The first of two path values to compare. The value may be converted
   219    219   to \fBpath\fR type.
   220    220   .AP Tcl_Obj *secondPtr in
   221    221   The second of two path values to compare. The value may be converted
   222    222   to \fBpath\fR type.
................................................................................
   245    245   Name of a procedure to look up in the file's symbol table
   246    246   .AP "const char" *sym2 in
   247    247   Name of a procedure to look up in the file's symbol table
   248    248   .AP Tcl_PackageInitProc **proc1Ptr out
   249    249   Filled with the init function for this code.
   250    250   .AP Tcl_PackageInitProc **proc2Ptr out
   251    251   Filled with the safe-init function for this code.
   252         -.AP ClientData *clientDataPtr out
          252  +.AP void **clientDataPtr out
   253    253   Filled with the clientData value to pass to this code's unload
   254    254   function when it is called.
   255    255   .AP Tcl_LoadHandle *loadHandlePtr out
   256    256   Filled with an abstract token representing the loaded file.
   257    257   .AP Tcl_FSUnloadFileProc **unloadProcPtr out
   258    258   Filled with the function to use to unload this piece of code.
   259    259   .AP Tcl_LoadHandle loadHandle in
................................................................................
   720    720   freed. This function is of little practical use, and
   721    721   \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
   722    722   better functions to use for most purposes.
   723    723   .PP
   724    724   \fBTcl_FSGetTranslatedStringPath\fR does the same as
   725    725   \fBTcl_FSGetTranslatedPath\fR, but returns a character string or NULL.
   726    726   The string returned is dynamically allocated and owned by the caller,
   727         -which must store it or call \fBckfree\fR to ensure it is freed. Again,
          727  +which must store it or call \fBTcl_Free\fR to ensure it is freed. Again,
   728    728   \fBTcl_FSGetNormalizedPath\fR or \fBTcl_FSGetNativePath\fR are usually
   729    729   better functions to use for most purposes.
   730    730   .PP
   731    731   \fBTcl_FSNewNativePath\fR performs something like the reverse of the
   732    732   usual obj->path->nativerep conversions. If some code retrieves a path
   733    733   in native form (from, e.g.\ \fBreadlink\fR or a native dialog), and that path
   734    734   is to be used at the Tcl level, then calling this function is an
................................................................................
   787    787   absolute.
   788    788   .PP
   789    789   It returns one of \fBTCL_PATH_ABSOLUTE\fR, \fBTCL_PATH_RELATIVE\fR, or
   790    790   \fBTCL_PATH_VOLUME_RELATIVE\fR
   791    791   .SS "PORTABLE STAT RESULT API"
   792    792   .PP
   793    793   \fBTcl_AllocStatBuf\fR allocates a \fITcl_StatBuf\fR on the system heap (which
   794         -may be deallocated by being passed to \fBckfree\fR). This allows extensions to
          794  +may be deallocated by being passed to \fBTcl_Free\fR). This allows extensions to
   795    795   invoke \fBTcl_FSStat\fR and \fBTcl_FSLstat\fR without being dependent on the
   796    796   size of the buffer. That in turn depends on the flags used to build Tcl.
   797    797   .PP
   798    798   .VS 8.6
   799    799   The portable fields of a \fITcl_StatBuf\fR may be read using the following
   800    800   functions, each of which returns the value of the corresponding field listed
   801    801   in the table below. Note that on some platforms there may be other fields in
................................................................................
   837    837   not check if the same filesystem is registered multiple times (and in
   838    838   general that is not a good thing to do). \fBTCL_OK\fR will be returned.
   839    839   .PP
   840    840   \fBTcl_FSUnregister\fR removes the given filesystem structure from
   841    841   the list of known filesystems, if it is known, and returns \fBTCL_OK\fR. If
   842    842   the filesystem is not currently registered, \fBTCL_ERROR\fR is returned.
   843    843   .PP
   844         -\fBTcl_FSData\fR will return the ClientData associated with the given
          844  +\fBTcl_FSData\fR will return the clientData associated with the given
   845    845   filesystem, if that filesystem is registered. Otherwise it will
   846    846   return NULL.
   847    847   .PP
   848    848   \fBTcl_FSMountsChanged\fR is used to inform the Tcl's core that
   849    849   the set of mount points for the given (already registered) filesystem
   850    850   have changed, and that cached file representations may therefore no
   851    851   longer be correct.
................................................................................
  1014   1014   cache the fact that this path belongs to this filesystem. Such caches
  1015   1015   are invalidated when filesystem structures are added or removed from
  1016   1016   Tcl's internal list of known filesystems.
  1017   1017   .PP
  1018   1018   .CS
  1019   1019   typedef int \fBTcl_FSPathInFilesystemProc\fR(
  1020   1020           Tcl_Obj *\fIpathPtr\fR,
  1021         -        ClientData *\fIclientDataPtr\fR);
         1021  +        void **\fIclientDataPtr\fR);
  1022   1022   .CE
  1023   1023   .SS DUPINTERNALREPPROC
  1024   1024   .PP
  1025   1025   This function makes a copy of a path's internal representation, and is
  1026   1026   called when Tcl needs to duplicate a path value. If NULL, Tcl will
  1027   1027   simply not copy the internal representation, which may then need to be
  1028   1028   regenerated later.
  1029   1029   .PP
  1030   1030   .CS
  1031         -typedef ClientData \fBTcl_FSDupInternalRepProc\fR(
  1032         -        ClientData \fIclientData\fR);
         1031  +typedef void *\fBTcl_FSDupInternalRepProc\fR(
         1032  +        void *\fIclientData\fR);
  1033   1033   .CE
  1034   1034   .SS FREEINTERNALREPPROC
  1035   1035   Free the internal representation. This must be implemented if internal
  1036   1036   representations need freeing (i.e.\ if some memory is allocated when an
  1037   1037   internal representation is generated), but may otherwise be NULL.
  1038   1038   .PP
  1039   1039   .CS
  1040   1040   typedef void \fBTcl_FSFreeInternalRepProc\fR(
  1041         -        ClientData \fIclientData\fR);
         1041  +        void *\fIclientData\fR);
  1042   1042   .CE
  1043   1043   .SS INTERNALTONORMALIZEDPROC
  1044   1044   .PP
  1045   1045   Function to convert internal representation to a normalized path. Only
  1046   1046   required if the filesystem creates pure path values with no string/path
  1047   1047   representation. The return value is a Tcl value whose string
  1048   1048   representation is the normalized path.
  1049   1049   .PP
  1050   1050   .CS
  1051   1051   typedef Tcl_Obj *\fBTcl_FSInternalToNormalizedProc\fR(
  1052         -        ClientData \fIclientData\fR);
         1052  +        void *\fIclientData\fR);
  1053   1053   .CE
  1054   1054   .SS CREATEINTERNALREPPROC
  1055   1055   .PP
  1056   1056   Function to take a path value, and calculate an internal
  1057   1057   representation for it, and store that native representation in the
  1058   1058   value. May be NULL if paths have no internal representation, or if
  1059   1059   the \fITcl_FSPathInFilesystemProc\fR for this filesystem always
  1060   1060   immediately creates an internal representation for paths it accepts.
  1061   1061   .PP
  1062   1062   .CS
  1063         -typedef ClientData \fBTcl_FSCreateInternalRepProc\fR(
         1063  +typedef void *\fBTcl_FSCreateInternalRepProc\fR(
  1064   1064           Tcl_Obj *\fIpathPtr\fR);
  1065   1065   .CE
  1066   1066   .SS NORMALIZEPATHPROC
  1067   1067   .PP
  1068   1068   Function to normalize a path. Should be implemented for all
  1069   1069   filesystems which can have multiple string representations for the same
  1070   1070   path value. In Tcl, every

Changes to doc/FindExec.3.

    54     54   .PP
    55     55   \fBTcl_GetNameOfExecutable\fR simply returns a pointer to the
    56     56   internal full path name of the executable file as computed by
    57     57   \fBTcl_FindExecutable\fR.  This procedure call is the C API
    58     58   equivalent to the \fBinfo nameofexecutable\fR command.  NULL
    59     59   is returned if the internal full path name has not been
    60     60   computed or unknown.
    61         -
           61  +.PP
           62  +\fBTcl_FindExecutable\fR can not be used in stub-enabled extensions.
    62     63   .SH KEYWORDS
    63     64   binary, executable file

Changes to doc/GetOpnFl.3.

    24     24   String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
    25     25   .AP int write in
    26     26   Non-zero means the file will be used for writing, zero means it will
    27     27   be used for reading.
    28     28   .AP int checkUsage in
    29     29   If non-zero, then an error will be generated if the file was not opened
    30     30   for the access indicated by \fIwrite\fR.
    31         -.AP ClientData *filePtr out
           31  +.AP void **filePtr out
    32     32   Points to word in which to store pointer to FILE structure for
    33     33   the file given by \fIchanID\fR.
    34     34   .BE
    35     35   
    36     36   .SH DESCRIPTION
    37     37   .PP
    38     38   \fBTcl_GetOpenFile\fR takes as argument a file identifier of the form

Changes to doc/GetTime.3.

    23     23   .AP Tcl_Time *timePtr out
    24     24   Points to memory in which to store the date and time information.
    25     25   .AP Tcl_GetTimeProc getProc in
    26     26   Pointer to handler function replacing \fBTcl_GetTime\fR's access to the OS.
    27     27   .AP Tcl_ScaleTimeProc scaleProc in
    28     28   Pointer to handler function for the conversion of time delays in the
    29     29   virtual domain to real-time.
    30         -.AP ClientData clientData in
           30  +.AP void *clientData in
    31     31   Value passed through to the two handler functions.
    32     32   .AP Tcl_GetTimeProc *getProcPtr out
    33     33   Pointer to place the currently registered get handler function into.
    34     34   .AP Tcl_ScaleTimeProc *scaleProcPtr out
    35     35   Pointer to place the currently registered scale handler function into.
    36         -.AP ClientData *clientDataPtr out
           36  +.AP void **clientDataPtr out
    37     37   Pointer to place the currently registered pass-through value into.
    38     38   .BE
    39     39   .SH DESCRIPTION
    40     40   .PP
    41     41   The \fBTcl_GetTime\fR function retrieves the current time as a
    42     42   \fITcl_Time\fR structure in memory the caller provides.  This
    43     43   structure has the following definition:
................................................................................
    79     79   any argument which is NULL is ignored and not set.
    80     80   .PP
    81     81   The signatures of the handler functions are as follows:
    82     82   .PP
    83     83   .CS
    84     84   typedef void \fBTcl_GetTimeProc\fR(
    85     85           Tcl_Time *\fItimebuf\fR,
    86         -        ClientData \fIclientData\fR);
           86  +        void *\fIclientData\fR);
    87     87   typedef void \fBTcl_ScaleTimeProc\fR(
    88     88           Tcl_Time *\fItimebuf\fR,
    89         -        ClientData \fIclientData\fR);
           89  +        void *\fIclientData\fR);
    90     90   .CE
    91     91   .PP
    92     92   The \fItimebuf\fR fields contain the time to manipulate, and the
    93     93   \fIclientData\fR fields contain a pointer supplied at the time the handler
    94     94   functions were registered.
    95     95   .PP
    96     96   Any handler pair specified has to return data which is consistent between

Changes to doc/Hash.3.

    26     26   \fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR)
    27     27   .sp
    28     28   \fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR)
    29     29   .sp
    30     30   Tcl_HashEntry *
    31     31   \fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
    32     32   .sp
    33         -ClientData
           33  +void *
    34     34   \fBTcl_GetHashValue\fR(\fIentryPtr\fR)
    35     35   .sp
    36     36   \fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
    37     37   .sp
    38     38   void *
    39     39   \fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR)
    40     40   .sp
................................................................................
    62     62   Key to use for probe into table.  Exact form depends on
    63     63   \fIkeyType\fR used to create table.
    64     64   .AP int *newPtr out
    65     65   The word at \fI*newPtr\fR is set to 1 if a new entry was created
    66     66   and 0 if there was already an entry for \fIkey\fR.
    67     67   .AP Tcl_HashEntry *entryPtr in
    68     68   Pointer to hash table entry.
    69         -.AP ClientData value in
    70         -New value to assign to hash table entry.  Need not have type
    71         -ClientData, but must fit in same space as ClientData.
           69  +.AP void *value in
           70  +New value to assign to hash table entry.
    72     71   .AP Tcl_HashSearch *searchPtr in
    73     72   Pointer to record to use to keep track of progress in enumerating
    74     73   all the entries in a hash table.
    75     74   .BE
    76     75   .SH DESCRIPTION
    77     76   .PP
    78     77   A hash table consists of zero or more entries, each consisting of a
................................................................................
   182    181   .PP
   183    182   \fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
   184    183   except that it does not create a new entry if the key doesn't exist;
   185    184   instead, it returns NULL as result.
   186    185   .PP
   187    186   \fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
   188    187   read and write an entry's value, respectively.
   189         -Values are stored and retrieved as type
   190         -.QW ClientData ,
   191         -which is
   192         -large enough to hold a pointer value.  On almost all machines this is
   193         -large enough to hold an integer value too.
   194    188   .PP
   195    189   \fBTcl_GetHashKey\fR returns the key for a given hash table entry,
   196    190   either as a pointer to a string, a one-word
   197    191   .PQ "char *"
   198    192   key, or
   199    193   as a pointer to the first word of an array of integers, depending
   200    194   on the \fIkeyType\fR used to create a hash table.
................................................................................
   225    219   \fBTcl_FirstHashEntry\fR or \fBTcl_NextHashEntry\fR.
   226    220   .PP
   227    221   \fBTcl_HashStats\fR returns a dynamically-allocated string with
   228    222   overall information about a hash table, such as the number of
   229    223   entries it contains, the number of buckets in its hash array,
   230    224   and the utilization of the buckets.
   231    225   It is the caller's responsibility to free the result string
   232         -by passing it to \fBckfree\fR.
          226  +by passing it to \fBTcl_Free\fR.
   233    227   .PP
   234    228   The header file \fBtcl.h\fR defines the actual data structures
   235    229   used to implement hash tables.
   236    230   This is necessary so that clients can allocate Tcl_HashTable
   237    231   structures and so that macros can be used to read and write
   238    232   the values of entries.
   239    233   However, users of the hashing routines should never refer directly

Changes to doc/IntObj.3.

     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7      7   .TH Tcl_IntObj 3 8.5 Tcl "Tcl Library Procedures"
     8      8   .so man.macros
     9      9   .BS
    10     10   .SH NAME
    11         -Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
           11  +Tcl_NewIntObj, Tcl_NewLongObj, Tcl_NewWideIntObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_SetWideIntObj, Tcl_GetIntFromObj, Tcl_GetIntForIndex, Tcl_GetLongFromObj, Tcl_GetWideIntFromObj, Tcl_NewBignumObj, Tcl_SetBignumObj, Tcl_GetBignumFromObj, Tcl_TakeBignumFromObj \- manipulate Tcl values as integers
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16     16   Tcl_Obj *
    17     17   \fBTcl_NewIntObj\fR(\fIintValue\fR)
    18     18   .sp
................................................................................
    27     27   \fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
    28     28   .sp
    29     29   \fBTcl_SetWideIntObj\fR(\fIobjPtr, wideValue\fR)
    30     30   .sp
    31     31   int
    32     32   \fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
    33     33   .sp
           34  +int
           35  +\fBTcl_GetIntForIndex\fR(\fIinterp, objPtr, endValue, intPtr\fR)
           36  +.sp
    34     37   int
    35     38   \fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
    36     39   .sp
    37     40   int
    38     41   \fBTcl_GetWideIntFromObj\fR(\fIinterp, objPtr, widePtr\fR)
    39     42   .sp
    40     43   .sp
................................................................................
    51     54   int
    52     55   \fBTcl_TakeBignumFromObj\fR(\fIinterp, objPtr, bigValue\fR)
    53     56   .sp
    54     57   int
    55     58   \fBTcl_InitBignumFromDouble\fR(\fIinterp, doubleValue, bigValue\fR)
    56     59   .SH ARGUMENTS
    57     60   .AS Tcl_WideInt doubleValue in/out
           61  +.AP int endValue in
           62  +\fBTcl_GetIntForIndex\fR will return this when the input value is "end".
    58     63   .AP int intValue in
    59     64   Integer value used to initialize or set a Tcl value.
    60     65   .AP long longValue in
    61     66   Long integer value used to initialize or set a Tcl value.
    62     67   .AP Tcl_WideInt wideValue in
    63     68   Wide integer value used to initialize or set a Tcl value.
    64     69   .AP Tcl_Obj *objPtr in/out
................................................................................
   110    115   and \fBTcl_SetBignumObj\fR routines each set the value of an existing
   111    116   Tcl value pointed to by \fIobjPtr\fR to the integral value provided
   112    117   by the other argument.  The \fIobjPtr\fR argument must point to an
   113    118   unshared Tcl value.  Any attempt to set the value of a shared Tcl value
   114    119   violates Tcl's copy-on-write policy.  Any existing string representation
   115    120   or internal representation in the unshared Tcl value will be freed
   116    121   as a consequence of setting the new value.
          122  +.PP
          123  +The \fBTcl_GetIntForIndex\fR routine attempts to retrieve an index
          124  +value from the Tcl value \fIobjPtr\fR.  If the attempt succeeds,
          125  +then \fBTCL_OK\fR is returned, and the value is written to the
          126  +storage provided by the caller.  The attempt might fail if
          127  +\fIobjPtr\fR does not hold an index value.  If the attempt fails,
          128  +then \fBTCL_ERROR\fR is returned, and if \fIinterp\fR is non-NULL,
          129  +an error message is left in \fIinterp\fR.  The \fBTcl_ObjType\fR
          130  +of \fIobjPtr\fR may be changed to make subsequent calls to the
          131  +same routine more efficient.
   117    132   .PP
   118    133   The \fBTcl_GetIntFromObj\fR, \fBTcl_GetLongFromObj\fR,
   119    134   \fBTcl_GetWideIntFromObj\fR, \fBTcl_GetBignumFromObj\fR, and
   120    135   \fBTcl_TakeBignumFromObj\fR routines attempt to retrieve an integral
   121    136   value of the appropriate type from the Tcl value \fIobjPtr\fR.  If the
   122    137   attempt succeeds, then \fBTCL_OK\fR is returned, and the value is
   123    138   written to the storage provided by the caller.  The attempt might

Changes to doc/Limit.3.

    79     79   Function to call when a particular limit is exceeded.  If the
    80     80   \fIhandlerProc\fR removes or raises the limit during its processing,
    81     81   the limited interpreter will be permitted to continue to process after
    82     82   the handler returns.  Many handlers may be attached to the same
    83     83   interpreter limit; their order of execution is not defined, and they
    84     84   must be identified by \fIhandlerProc\fR and \fIclientData\fR when they
    85     85   are deleted.
    86         -.AP ClientData clientData in
           86  +.AP void *clientData in
    87     87   Arbitrary pointer-sized word used to pass some context to the
    88     88   \fIhandlerProc\fR function.
    89     89   .AP Tcl_LimitHandlerDeleteProc *deleteProc in
    90     90   Function to call whenever a handler is deleted.  May be NULL if the
    91     91   \fIclientData\fR requires no deletion.
    92     92   .BE
    93     93   .SH DESCRIPTION
................................................................................
   158    158   To add a handler callback to be invoked when a limit is exceeded, call
   159    159   \fBTcl_LimitAddHandler\fR.  The \fIhandlerProc\fR argument describes
   160    160   the function that will actually be called; it should have the
   161    161   following prototype:
   162    162   .PP
   163    163   .CS
   164    164   typedef void \fBTcl_LimitHandlerProc\fR(
   165         -        ClientData \fIclientData\fR,
          165  +        void *\fIclientData\fR,
   166    166           Tcl_Interp *\fIinterp\fR);
   167    167   .CE
   168    168   .PP
   169    169   The \fIclientData\fR argument to the handler will be whatever is
   170    170   passed to the \fIclientData\fR argument to \fBTcl_LimitAddHandler\fR,
   171    171   and the \fIinterp\fR is the interpreter that had its limit exceeded.
   172    172   .PP
................................................................................
   175    175   \fBTCL_STATIC\fR or NULL if no deletion action is necessary, or
   176    176   \fBTCL_DYNAMIC\fR if all that is necessary is to free the structure with
   177    177   \fBTcl_Free\fR.  Otherwise, it should refer to a function with the
   178    178   following prototype:
   179    179   .PP
   180    180   .CS
   181    181   typedef void \fBTcl_LimitHandlerDeleteProc\fR(
   182         -        ClientData \fIclientData\fR);
          182  +        void *\fIclientData\fR);
   183    183   .CE
   184    184   .PP
   185    185   A limit handler may be deleted using \fBTcl_LimitRemoveHandler\fR; the
   186    186   handler removed will be the first one found (out of the handlers added
   187    187   with \fBTcl_LimitAddHandler\fR) with exactly matching \fItype\fR,
   188    188   \fIhandlerProc\fR and \fIclientData\fR arguments.  This function
   189    189   always invokes the \fIdeleteProc\fR on the \fIclientData\fR (unless
   190    190   the \fIdeleteProc\fR was NULL or \fBTCL_STATIC\fR).
   191    191   .SH KEYWORDS
   192    192   interpreter, resource, limit, commands, time, callback

Changes to doc/LinkVar.3.

     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8      8   .TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
     9      9   .so man.macros
    10     10   .BS
    11     11   .SH NAME
    12         -Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
           12  +Tcl_LinkArray, Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
    13     13   .SH SYNOPSIS
    14     14   .nf
    15     15   \fB#include <tcl.h>\fR
    16     16   .sp
    17     17   int
    18     18   \fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
           19  +.sp
           20  +.VS "TIP 312"
           21  +int
           22  +\fBTcl_LinkArray\fR(\fIinterp, varName, addr, type, size\fR)
           23  +.VE "TIP 312"
    19     24   .sp
    20     25   \fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
    21     26   .sp
    22     27   \fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
    23     28   .SH ARGUMENTS
    24         -.AS Tcl_Interp writable
           29  +.AS Tcl_Interp varName in
    25     30   .AP Tcl_Interp *interp in
    26     31   Interpreter that contains \fIvarName\fR.
    27     32   Also used by \fBTcl_LinkVar\fR to return error messages.
    28     33   .AP "const char" *varName in
    29     34   Name of global variable.
    30         -.AP char *addr in
           35  +.AP void *addr in
    31     36   Address of C variable that is to be linked to \fIvarName\fR.
           37  +.sp
           38  +.VS "TIP 312"
           39  +In \fBTcl_LinkArray\fR, may be NULL to tell Tcl to create the storage
           40  +for the array in the variable.
           41  +.VE "TIP 312"
    32     42   .AP int type in
    33         -Type of C variable.  Must be one of \fBTCL_LINK_INT\fR,
           43  +Type of C variable for \fBTcl_LinkVar\fR or type of array element for
           44  +\fBTcl_LinkArray\fR.  Must be one of \fBTCL_LINK_INT\fR,
    34     45   \fBTCL_LINK_UINT\fR, \fBTCL_LINK_CHAR\fR, \fBTCL_LINK_UCHAR\fR,
    35     46   \fBTCL_LINK_SHORT\fR, \fBTCL_LINK_USHORT\fR, \fBTCL_LINK_LONG\fR,
    36     47   \fBTCL_LINK_ULONG\fR, \fBTCL_LINK_WIDE_INT\fR,
    37         -\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR,
    38         -\fBTCL_LINK_DOUBLE\fR, \fBTCL_LINK_BOOLEAN\fR, or
    39         -\fBTCL_LINK_STRING\fR, optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR
    40         -to make Tcl variable read-only.
           48  +\fBTCL_LINK_WIDE_UINT\fR, \fBTCL_LINK_FLOAT\fR, \fBTCL_LINK_DOUBLE\fR,
           49  +\fBTCL_LINK_BOOLEAN\fR, or one of the extra ones listed below.
           50  +.sp
           51  +In \fBTcl_LinkVar\fR, the additional linked type \fBTCL_LINK_STRING\fR may be
           52  +used.
           53  +.sp
           54  +.VS "TIP 312"
           55  +In \fBTcl_LinkArray\fR, the additional linked types \fBTCL_LINK_CHARS\fR and
           56  +\fBTCL_LINK_BYTES\fR may be used.
           57  +.VE "TIP 312"
           58  +.sp
           59  +All the above for both functions may be
           60  +optionally OR'ed with \fBTCL_LINK_READ_ONLY\fR to make the Tcl
           61  +variable read-only.
           62  +.AP size_t size in
           63  +.VS "TIP 312"
           64  +The number of elements in the C array. Must be greater than zero.
           65  +.VE "TIP 312"
    41     66   .BE
    42     67   .SH DESCRIPTION
    43     68   .PP
    44     69   \fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
    45     70   named by \fIvarName\fR in sync with the C variable at the address
    46     71   given by \fIaddr\fR.
    47     72   Whenever the Tcl variable is read the value of the C variable will
    48     73   be returned, and whenever the Tcl variable is written the C
    49     74   variable will be updated to have the same value.
    50     75   \fBTcl_LinkVar\fR normally returns \fBTCL_OK\fR;  if an error occurs
    51     76   while setting up the link (e.g. because \fIvarName\fR is the
    52     77   name of array) then \fBTCL_ERROR\fR is returned and the interpreter's result
    53     78   contains an error message.
           79  +.PP
           80  +.VS "TIP 312"
           81  +\fBTcl_LinkArray\fR is similar, but for arrays of fixed size (given by
           82  +the \fIsize\fR argument). When asked to allocate the backing C array
           83  +storage (via the \fIaddr\fR argument being NULL), it writes the
           84  +address that it allocated to the Tcl interpreter result.
           85  +.VE "TIP 312"
    54     86   .PP
    55     87   The \fItype\fR argument specifies the type of the C variable,
           88  +or the type of the elements of the C array,
    56     89   and must have one of the following values, optionally OR'ed with
    57     90   \fBTCL_LINK_READ_ONLY\fR:
    58     91   .TP
    59     92   \fBTCL_LINK_INT\fR
    60         -The C variable is of type \fBint\fR.
           93  +.
           94  +The C variable, or each element of the C array, is of type \fBint\fR.
    61     95   Any value written into the Tcl variable must have a proper integer
    62     96   form acceptable to \fBTcl_GetIntFromObj\fR;  attempts to write
    63     97   non-integer values into \fIvarName\fR will be rejected with
    64     98   Tcl errors. Incomplete integer representations (like the empty
    65     99   string, '+', '-' or the hex/octal/binary prefix) are accepted
    66    100   as if they are valid too.
    67    101   .TP
    68    102   \fBTCL_LINK_UINT\fR
    69         -The C variable is of type \fBunsigned int\fR.
          103  +.
          104  +The C variable, or each element of the C array, is of type \fBunsigned int\fR.
    70    105   Any value written into the Tcl variable must have a proper unsigned
    71    106   integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
    72    107   platform's defined range for the \fBunsigned int\fR type; attempts to
    73    108   write non-integer values (or values outside the range) into
    74    109   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
    75    110   representations (like the empty string, '+', '-' or the hex/octal/binary
    76    111   prefix) are accepted as if they are valid too.
    77    112   .TP
    78    113   \fBTCL_LINK_CHAR\fR
    79         -The C variable is of type \fBchar\fR.
          114  +.
          115  +The C variable, or each element of the C array, is of type \fBchar\fR.
    80    116   Any value written into the Tcl variable must have a proper integer
    81    117   form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
    82    118   \fBchar\fR datatype; attempts to write non-integer or out-of-range
    83    119   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
    84    120   integer representations (like the empty string, '+', '-' or the
    85    121   hex/octal/binary prefix) are accepted as if they are valid too.
          122  +.RS
          123  +.PP
          124  +.VS "TIP 312"
          125  +If using an array of these, consider using \fBTCL_LINK_CHARS\fR instead.
          126  +.VE "TIP 312"
          127  +.RE
          128  +.TP
          129  +\fBTCL_LINK_CHARS\fR
          130  +.VS "TIP 312"
          131  +The C array is of type \fBchar *\fR and is mapped into Tcl as a string.
          132  +Any value written into the Tcl variable must have the same length as
          133  +the underlying storage. Only supported with \fBTcl_LinkArray\fR.
          134  +.VE "TIP 312"
    86    135   .TP
    87    136   \fBTCL_LINK_UCHAR\fR
    88         -The C variable is of type \fBunsigned char\fR.
          137  +.
          138  +The C variable, or each element of the C array, is of type \fBunsigned char\fR.
    89    139   Any value written into the Tcl variable must have a proper unsigned
    90    140   integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
    91    141   platform's defined range for the \fBunsigned char\fR type; attempts to
    92    142   write non-integer values (or values outside the range) into
    93    143   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
    94    144   representations (like the empty string, '+', '-' or the hex/octal/binary
    95    145   prefix) are accepted as if they are valid too.
          146  +.RS
          147  +.PP
          148  +.VS "TIP 312"
          149  +If using an array of these, consider using \fBTCL_LINK_BYTES\fR instead.
          150  +.VE "TIP 312"
          151  +.RE
          152  +.TP
          153  +\fBTCL_LINK_BYTES\fR
          154  +.VS "TIP 312"
          155  +The C array is of type \fBunsigned char *\fR and is mapped into Tcl
          156  +as a bytearray.
          157  +Any value written into the Tcl variable must have the same length as
          158  +the underlying storage. Only supported with \fBTcl_LinkArray\fR.
          159  +.VE "TIP 312"
    96    160   .TP
    97    161   \fBTCL_LINK_SHORT\fR
    98         -The C variable is of type \fBshort\fR.
          162  +.
          163  +The C variable, or each element of the C array, is of type \fBshort\fR.
    99    164   Any value written into the Tcl variable must have a proper integer
   100    165   form acceptable to \fBTcl_GetIntFromObj\fR and be in the range of the
   101    166   \fBshort\fR datatype; attempts to write non-integer or out-of-range
   102    167   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
   103    168   integer representations (like the empty string, '+', '-' or the
   104    169   hex/octal/binary prefix) are accepted as if they are valid too.
   105    170   .TP
   106    171   \fBTCL_LINK_USHORT\fR
   107         -The C variable is of type \fBunsigned short\fR.
          172  +.
          173  +The C variable, or each element of the C array, is of type \fBunsigned short\fR.
   108    174   Any value written into the Tcl variable must have a proper unsigned
   109    175   integer form acceptable to \fBTcl_GetIntFromObj\fR and in the
   110    176   platform's defined range for the \fBunsigned short\fR type; attempts to
   111    177   write non-integer values (or values outside the range) into
   112    178   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   113    179   representations (like the empty string, '+', '-' or the hex/octal/binary
   114    180   prefix) are accepted as if they are valid too.
   115    181   .TP
   116    182   \fBTCL_LINK_LONG\fR
   117         -The C variable is of type \fBlong\fR.
          183  +.
          184  +The C variable, or each element of the C array, is of type \fBlong\fR.
   118    185   Any value written into the Tcl variable must have a proper integer
   119    186   form acceptable to \fBTcl_GetLongFromObj\fR; attempts to write
   120    187   non-integer or out-of-range
   121    188   values into \fIvarName\fR will be rejected with Tcl errors. Incomplete
   122    189   integer representations (like the empty string, '+', '-' or the
   123    190   hex/octal/binary prefix) are accepted as if they are valid too.
   124    191   .TP
   125    192   \fBTCL_LINK_ULONG\fR
   126         -The C variable is of type \fBunsigned long\fR.
          193  +.
          194  +The C variable, or each element of the C array, is of type \fBunsigned long\fR.
   127    195   Any value written into the Tcl variable must have a proper unsigned
   128    196   integer form acceptable to \fBTcl_GetWideIntFromObj\fR and in the
   129    197   platform's defined range for the \fBunsigned long\fR type; attempts to
   130    198   write non-integer values (or values outside the range) into
   131    199   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   132    200   representations (like the empty string, '+', '-' or the hex/octal/binary
   133    201   prefix) are accepted as if they are valid too.
   134    202   .TP
   135    203   \fBTCL_LINK_DOUBLE\fR
   136         -The C variable is of type \fBdouble\fR.
          204  +.
          205  +The C variable, or each element of the C array, is of type \fBdouble\fR.
   137    206   Any value written into the Tcl variable must have a proper real
   138    207   form acceptable to \fBTcl_GetDoubleFromObj\fR;  attempts to write
   139    208   non-real values into \fIvarName\fR will be rejected with
   140    209   Tcl errors. Incomplete integer or real representations (like the
   141    210   empty string, '.', '+', '-' or the hex/octal/binary prefix) are
   142    211   accepted as if they are valid too.
   143    212   .TP
   144    213   \fBTCL_LINK_FLOAT\fR
   145         -The C variable is of type \fBfloat\fR.
          214  +.
          215  +The C variable, or each element of the C array, is of type \fBfloat\fR.
   146    216   Any value written into the Tcl variable must have a proper real
   147    217   form acceptable to \fBTcl_GetDoubleFromObj\fR and must be within the
   148    218   range acceptable for a \fBfloat\fR; attempts to
   149    219   write non-real values (or values outside the range) into
   150    220   \fIvarName\fR will be rejected with Tcl errors. Incomplete integer
   151    221   or real representations (like the empty string, '.', '+', '-' or
   152    222   the hex/octal/binary prefix) are accepted as if they are valid too.
   153    223   .TP
   154    224   \fBTCL_LINK_WIDE_INT\fR
   155         -The C variable is of type \fBTcl_WideInt\fR (which is an integer type
          225  +.
          226  +The C variable, or each element of the C array, is of type \fBTcl_WideInt\fR
          227  +(which is an integer type
   156    228   at least 64-bits wide on all platforms that can support it.)
   157    229   Any value written into the Tcl variable must have a proper integer
   158    230   form acceptable to \fBTcl_GetWideIntFromObj\fR;  attempts to write
   159    231   non-integer values into \fIvarName\fR will be rejected with
   160    232   Tcl errors. Incomplete integer representations (like the empty
   161    233   string, '+', '-' or the hex/octal/binary prefix) are accepted
   162    234   as if they are valid too.
   163    235   .TP
   164    236   \fBTCL_LINK_WIDE_UINT\fR
   165         -The C variable is of type \fBTcl_WideUInt\fR (which is an unsigned
   166         -integer type at least 64-bits wide on all platforms that can support
   167         -it.)
          237  +.
          238  +The C variable, or each element of the C array, is of type \fBTcl_WideUInt\fR
          239  +(which is an unsigned integer type at least 64-bits wide on all platforms that
          240  +can support it.)
   168    241   Any value written into the Tcl variable must have a proper unsigned
   169    242   integer form acceptable to \fBTcl_GetWideIntFromObj\fR (it will be
   170    243   cast to unsigned);
   171    244   .\" FIXME! Use bignums instead.
   172    245   attempts to write non-integer values into \fIvarName\fR will be
   173    246   rejected with Tcl errors. Incomplete integer representations (like
   174    247   the empty string, '+', '-' or the hex/octal/binary prefix) are accepted
   175    248   as if they are valid too.
   176    249   .TP
   177    250   \fBTCL_LINK_BOOLEAN\fR
   178         -The C variable is of type \fBint\fR.
          251  +.
          252  +The C variable, or each element of the C array, is of type \fBint\fR.
   179    253   If its value is zero then it will read from Tcl as
   180    254   .QW 0 ;
   181    255   otherwise it will read from Tcl as
   182    256   .QW 1 .
   183    257   Whenever \fIvarName\fR is
   184    258   modified, the C variable will be set to a 0 or 1 value.
   185    259   Any value written into the Tcl variable must have a proper boolean
   186    260   form acceptable to \fBTcl_GetBooleanFromObj\fR;  attempts to write
   187    261   non-boolean values into \fIvarName\fR will be rejected with
   188    262   Tcl errors.
   189    263   .TP
   190    264   \fBTCL_LINK_STRING\fR
          265  +.
   191    266   The C variable is of type \fBchar *\fR.
   192    267   If its value is not NULL then it must be a pointer to a string
   193         -allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
          268  +allocated with \fBTcl_Alloc\fR.
   194    269   Whenever the Tcl variable is modified the current C string will be
   195    270   freed and new memory will be allocated to hold a copy of the variable's
   196    271   new value.
   197    272   If the C variable contains a NULL pointer then the Tcl variable
   198    273   will read as
   199    274   .QW NULL .
          275  +This is only supported by \fBTcl_LinkVar\fR.
   200    276   .PP
   201    277   If the \fBTCL_LINK_READ_ONLY\fR flag is present in \fItype\fR then the
   202    278   variable will be read-only from Tcl, so that its value can only be
   203    279   changed by modifying the C variable.
   204    280   Attempts to write the variable from Tcl will be rejected with errors.
   205    281   .PP
   206    282   \fBTcl_UnlinkVar\fR removes the link previously set up for the

Changes to doc/Method.3.

     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7      7   .TH Tcl_Method 3 0.1 TclOO "TclOO Library Functions"
     8      8   .so man.macros
     9      9   .BS
    10     10   '\" Note:  do not modify the .SH NAME line immediately below!
    11     11   .SH NAME
    12         -Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
           12  +Tcl_ClassSetConstructor, Tcl_ClassSetDestructor, Tcl_MethodDeclarerClass, Tcl_MethodDeclarerObject, Tcl_MethodIsPublic, Tcl_MethodIsPrivate, Tcl_MethodIsType, Tcl_MethodName, Tcl_NewInstanceMethod, Tcl_NewMethod, Tcl_ObjectContextInvokeNext, Tcl_ObjectContextIsFiltering, Tcl_ObjectContextMethod, Tcl_ObjectContextObject, Tcl_ObjectContextSkippedArgs \- manipulate methods and method-call contexts
    13     13   .SH SYNOPSIS
    14     14   .nf
    15     15   \fB#include <tclOO.h>\fR
    16     16   .sp
    17     17   Tcl_Method
    18         -\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, isPublic,
    19         -              methodTypePtr, clientData\fR)
           18  +\fBTcl_NewMethod\fR(\fIinterp, class, nameObj, flags, methodTypePtr,
           19  +              clientData\fR)
    20     20   .sp
    21     21   Tcl_Method
    22         -\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, isPublic,
    23         -                      methodTypePtr, clientData\fR)
           22  +\fBTcl_NewInstanceMethod\fR(\fIinterp, object, nameObj, flags, methodTypePtr,
           23  +                      clientData\fR)
    24     24   .sp
    25     25   \fBTcl_ClassSetConstructor\fR(\fIinterp, class, method\fR)
    26     26   .sp
    27     27   \fBTcl_ClassSetDestructor\fR(\fIinterp, class, method\fR)
    28     28   .sp
    29     29   Tcl_Class
    30     30   \fBTcl_MethodDeclarerClass\fR(\fImethod\fR)
................................................................................
    31     31   .sp
    32     32   Tcl_Object
    33     33   \fBTcl_MethodDeclarerObject\fR(\fImethod\fR)
    34     34   .sp
    35     35   Tcl_Obj *
    36     36   \fBTcl_MethodName\fR(\fImethod\fR)
    37     37   .sp
           38  +.VS TIP500
    38     39   int
    39     40   \fBTcl_MethodIsPublic\fR(\fImethod\fR)
           41  +.VE TIP500
           42  +.sp
           43  +int
           44  +\fBTcl_MethodIsPrivate\fR(\fImethod\fR)
    40     45   .sp
    41     46   int
    42     47   \fBTcl_MethodIsType\fR(\fImethod, methodTypePtr, clientDataPtr\fR)
    43     48   .sp
    44     49   int
    45     50   \fBTcl_ObjectContextInvokeNext\fR(\fIinterp, context, objc, objv, skip\fR)
    46     51   .sp
................................................................................
    52     57   .sp
    53     58   Tcl_Object
    54     59   \fBTcl_ObjectContextObject\fR(\fIcontext\fR)
    55     60   .sp
    56     61   int
    57     62   \fBTcl_ObjectContextSkippedArgs\fR(\fIcontext\fR)
    58     63   .SH ARGUMENTS
    59         -.AS ClientData clientData in
           64  +.AS void *clientData in
    60     65   .AP Tcl_Interp *interp in/out
    61     66   The interpreter holding the object or class to create or update a method in.
    62     67   .AP Tcl_Object object in
    63     68   The object to create the method in.
    64     69   .AP Tcl_Class class in
    65     70   The class to create the method in.
    66     71   .AP Tcl_Obj *nameObj in
    67     72   The name of the method to create. Should not be NULL unless creating
    68     73   constructors or destructors.
    69         -.AP int isPublic in
    70         -A flag saying what the visibility of the method is. The only supported public
    71         -values of this flag are 0 for a non-exported method, and 1 for an exported
    72         -method.
           74  +.AP int flags in
           75  +A flag saying (currently) what the visibility of the method is. The supported
           76  +public values of this flag are \fBTCL_OO_METHOD_PUBLIC\fR (which is fixed at 1
           77  +for backward compatibility) for an exported method,
           78  +\fBTCL_OO_METHOD_UNEXPORTED\fR (which is fixed at 0 for backward
           79  +compatibility) for a non-exported method,
           80  +.VS TIP500
           81  +and \fBTCL_OO_METHOD_PRIVATE\fR for a private method.
           82  +.VE TIP500
    73     83   .AP Tcl_MethodType *methodTypePtr in
    74     84   A description of the type of the method to create, or the type of method to
    75     85   compare against.
    76         -.AP ClientData clientData in
           86  +.AP void *clientData in
    77     87   A piece of data that is passed to the implementation of the method without
    78     88   interpretation.
    79         -.AP ClientData *clientDataPtr out
           89  +.AP void **clientDataPtr out
    80     90   A pointer to a variable in which to write the \fIclientData\fR value supplied
    81     91   when the method was created. If NULL, the \fIclientData\fR value will not be
    82     92   retrieved.
    83     93   .AP Tcl_Method method in
    84     94   A reference to a method to query.
    85     95   .AP Tcl_ObjectContext context in
    86     96   A reference to a method-call context. Note that client code \fImust not\fR
................................................................................
   101    111   that class.
   102    112   .PP
   103    113   Given a method, the entity that declared it can be found using
   104    114   \fBTcl_MethodDeclarerClass\fR which returns the class that the method is
   105    115   attached to (or NULL if the method is not attached to any class) and
   106    116   \fBTcl_MethodDeclarerObject\fR which returns the object that the method is
   107    117   attached to (or NULL if the method is not attached to an object). The name of
   108         -the method can be retrieved with \fBTcl_MethodName\fR and whether the method
   109         -is exported is retrieved with \fBTcl_MethodIsPublic\fR. The type of the method
          118  +the method can be retrieved with \fBTcl_MethodName\fR, whether the method
          119  +is exported is retrieved with \fBTcl_MethodIsPublic\fR,
          120  +.VS TIP500
          121  +and whether the method is private is retrieved with \fBTcl_MethodIsPrivate\fR.
          122  +.VE TIP500
          123  +The type of the method
   110    124   can also be introspected upon to a limited degree; the function
   111    125   \fBTcl_MethodIsType\fR returns whether a method is of a particular type,
   112    126   assigning the per-method \fIclientData\fR to the variable pointed to by
   113    127   \fIclientDataPtr\fR if (that is non-NULL) if the type is matched.
   114    128   .SS "METHOD CREATION"
   115    129   .PP
   116    130   Methods are created by \fBTcl_NewMethod\fR and \fBTcl_NewInstanceMethod\fR,
   117    131   which
   118    132   create a method attached to a class or an object respectively. In both cases,
   119    133   the \fInameObj\fR argument gives the name of the method to create, the
   120         -\fIisPublic\fR argument states whether the method should be exported
   121         -initially, the \fImethodTypePtr\fR argument describes the implementation of
          134  +\fIflags\fR argument states whether the method should be exported
          135  +initially
          136  +.VS TIP500
          137  +or be marked as a private method,
          138  +.VE TIP500
          139  +the \fImethodTypePtr\fR argument describes the implementation of
   122    140   the method (see the \fBMETHOD TYPES\fR section below) and the \fIclientData\fR
   123    141   argument gives some implementation-specific data that is passed on to the
   124    142   implementation of the method when it is called.
   125    143   .PP
   126    144   When the \fInameObj\fR argument to \fBTcl_NewMethod\fR is NULL, an
   127    145   unnamed method is created, which is used for constructors and destructors.
   128    146   Constructors should be installed into their class using the
................................................................................
   191    209   that the \fIclientData\fR can just be copied directly.
   192    210   .SS "TCL_METHODCALLPROC FUNCTION SIGNATURE"
   193    211   .PP
   194    212   Functions matching this signature are called when the method is invoked.
   195    213   .PP
   196    214   .CS
   197    215   typedef int \fBTcl_MethodCallProc\fR(
   198         -        ClientData \fIclientData\fR,
          216  +        void *\fIclientData\fR,
   199    217           Tcl_Interp *\fIinterp\fR,
   200    218           Tcl_ObjectContext \fIobjectContext\fR,
   201    219           int \fIobjc\fR,
   202    220           Tcl_Obj *const *\fIobjv\fR);
   203    221   .CE
   204    222   .PP
   205    223   The \fIclientData\fR argument to a Tcl_MethodCallProc is the value that was
................................................................................
   212    230   .SS "TCL_METHODDELETEPROC FUNCTION SIGNATURE"
   213    231   .PP
   214    232   Functions matching this signature are used when a method is deleted, whether
   215    233   through a new method being created or because the object or class is deleted.
   216    234   .PP
   217    235   .CS
   218    236   typedef void \fBTcl_MethodDeleteProc\fR(
   219         -        ClientData \fIclientData\fR);
          237  +        void *\fIclientData\fR);
   220    238   .CE
   221    239   .PP
   222    240   The \fIclientData\fR argument to a Tcl_MethodDeleteProc will be the same as
   223    241   the value passed to the \fIclientData\fR argument to \fBTcl_NewMethod\fR or
   224    242   \fBTcl_NewInstanceMethod\fR when the method was created.
   225    243   .SS "TCL_CLONEPROC FUNCTION SIGNATURE"
   226    244   .PP
   227    245   Functions matching this signature are used to copy a method when the object or
   228    246   class is copied using \fBTcl_CopyObjectInstance\fR (or \fBoo::copy\fR).
   229    247   .PP
   230    248   .CS
   231    249   typedef int \fBTcl_CloneProc\fR(
   232    250           Tcl_Interp *\fIinterp\fR,
   233         -        ClientData \fIoldClientData\fR,
   234         -        ClientData *\fInewClientDataPtr\fR);
          251  +        void *\fIoldClientData\fR,
          252  +        void **\fInewClientDataPtr\fR);
   235    253   .CE
   236    254   .PP
   237    255   The \fIinterp\fR argument gives a place to write an error message when the
   238    256   attempt to clone the object is to fail, in which case the clone procedure must
   239    257   also return TCL_ERROR; it should return TCL_OK otherwise.
   240    258   The \fIoldClientData\fR field to a Tcl_CloneProc gives the value from the
   241    259   method being copied from, and the \fInewClientDataPtr\fR field will point to

Changes to doc/NRE.3.

     1      1   .\"
     2      2   .\" Copyright (c) 2008 by Kevin B. Kenny.
     3         -.\" Copyright (c) 2018 by Nathan Coulter. 
            3  +.\" Copyright (c) 2018 by Nathan Coulter.
     4      4   .\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8      8   .TH NRE 3 8.6 Tcl "Tcl Library Procedures"
     9      9   .so man.macros
    10     10   .BS
................................................................................
    45     45   .AP Tcl_ObjCmdProc *proc in
    46     46   Called in order to evaluate a command.  Is often just a small wrapper that uses
    47     47   \fBTcl_NRCallObjProc\fR to call \fInreProc\fR using a new trampoline.  Behaves
    48     48   in the same way as the \fIproc\fR argument to \fBTcl_CreateObjCommand\fR(3)
    49     49   (\fIq.v.\fR).
    50     50   .AP Tcl_ObjCmdProc *nreProc in
    51     51   Called instead of \fIproc\fR when a trampoline is already in use.
    52         -.AP ClientData clientData in
           52  +.AP void *clientData in
    53     53   Arbitrary one-word value passed to \fIproc\fR, \fInreProc\fR, \fIdeleteProc\fR
    54     54   and \fIobjProc\fR.
    55     55   .AP Tcl_CmdDeleteProc *deleteProc in/out
    56     56   Called before \fIcmdName\fR is deleted from the interpreter, allowing for
    57     57   command-specific cleanup. May be NULL.
    58     58   .AP int objc in
    59     59   Number of items in \fIobjv\fR.
................................................................................
    68     68   Token to use instead of one derived from the first word of \fIobjv\fR in order
    69     69   to evaluate a command.
    70     70   .AP Tcl_Obj *resultPtr out
    71     71   Pointer to an unshared Tcl_Obj where the result of the evaluation is stored if
    72     72   the return code is TCL_OK.
    73     73   .AP Tcl_NRPostProc *postProcPtr in
    74     74   A function to push.
    75         -.AP ClientData data0 in
    76         -.AP ClientData data1 in
    77         -.AP ClientData data2 in
    78         -.AP ClientData data3 in
           75  +.AP void *data0 in
           76  +.AP void *data1 in
           77  +.AP void *data2 in
           78  +.AP void *data3 in
    79     79   \fIdata0\fR through \fIdata3\fR are four one-word values that will be passed
    80     80   to the function designated by \fIpostProcPtr\fR when it is invoked.
    81     81   .BE
    82     82   .SH DESCRIPTION
    83     83   .PP
    84     84   These functions provide an interface to the function stack that an interpreter
    85     85   iterates through to evaluate commands.  The routine behind a command is
................................................................................
   126    126   .PP
   127    127   \fBTcl_NRAddCallback\fR pushes \fIpostProcPtr\fR.  The signature for
   128    128   \fBTcl_NRPostProc\fR is:
   129    129   .PP
   130    130   .CS
   131    131   typedef int
   132    132   \fBTcl_NRPostProc\fR(
   133         -        \fBClientData\fR \fIdata\fR[],
          133  +        \fBvoid *\fR \fIdata\fR[],
   134    134           \fBTcl_Interp\fR *\fIinterp\fR,
   135    135           int \fIresult\fR);
   136    136   .CE
   137    137   .PP
   138    138   \fIdata\fR is a pointer to an array containing \fIdata0\fR through \fIdata3\fR.
   139    139   \fIresult\fR is the value returned by the previous function implementing part
   140    140   the routine.
................................................................................
   142    142   .PP
   143    143   The following command uses \fBTcl_EvalObjEx\fR, which consumes space on the C
   144    144   stack, to evalute a script:
   145    145   .PP
   146    146   .CS
   147    147   int
   148    148   \fITheCmdOldObjProc\fR(
   149         -    ClientData clientData,
          149  +    void *clientData,
   150    150       Tcl_Interp *interp,
   151    151       int objc,
   152    152       Tcl_Obj *const objv[])
   153    153   {
   154    154       int result;
   155    155       Tcl_Obj *objPtr;
   156    156   
................................................................................
   173    173   trampoline instead of consuming space on the C stack.  A new version of
   174    174   \fITheCmdOldObjProc\fR is just a a wrapper that uses \fBTcl_NRCallObjProc\fR to
   175    175   call \fITheCmdNRObjProc\fR:
   176    176   .PP
   177    177   .CS
   178    178   int
   179    179   \fITheCmdOldObjProc\fR(
   180         -    ClientData clientData,
          180  +    void *clientData,
   181    181       Tcl_Interp *interp,
   182    182       int objc,
   183    183       Tcl_Obj *const objv[])
   184    184   {
   185    185       return \fBTcl_NRCallObjProc\fR(interp, \fITheCmdNRObjProc\fR,
   186    186               clientData, objc, objv);
   187    187   }
   188    188   .CE
   189    189   .PP
   190    190   .CS
   191    191   int
   192    192   \fITheCmdNRObjProc\fR
   193         -    ClientData clientData,
          193  +    void *clientData,
   194    194       Tcl_Interp *interp,
   195    195       int objc,
   196    196       Tcl_Obj *const objv[])
   197    197   {
   198    198       Tcl_Obj *objPtr;
   199    199   
   200    200       \fI... preparation ...\fR
................................................................................
   207    207       return \fBTcl_NREvalObj\fR(interp, objPtr, 0);
   208    208   }
   209    209   .CE
   210    210   .PP
   211    211   .CS
   212    212   int
   213    213   \fITheCmdNRPostProc\fR(
   214         -    ClientData data[],
          214  +    void *data[],
   215    215       Tcl_Interp *interp,
   216    216       int result)
   217    217   {
   218    218       /* \fIdata[0] .. data[3]\fR are the four words of data
   219    219        * passed to \fBTcl_NRAddCallback\fR */
   220    220   
   221    221       \fI... postprocessing ...\fR

Changes to doc/Namespace.3.

    53     53   .SH ARGUMENTS
    54     54   .AS Tcl_NamespaceDeleteProc allowOverwrite in/out
    55     55   .AP Tcl_Interp *interp in/out
    56     56   The interpreter in which the namespace exists and where name lookups
    57     57   are performed. Also where error result messages are written.
    58     58   .AP "const char" *name in
    59     59   The name of the namespace or command to be created or accessed.
    60         -.AP ClientData clientData in
           60  +.AP void *clientData in
    61     61   A context pointer by the creator of the namespace.  Not interpreted by
    62     62   Tcl at all.
    63     63   .AP Tcl_NamespaceDeleteProc *deleteProc in
    64     64   A pointer to function to call when the namespace is deleted, or NULL
    65     65   if no such callback is to be performed.
    66     66   .AP Tcl_Namespace *nsPtr in
    67     67   The namespace to be manipulated, or NULL (for other than
................................................................................
   113    113   the global namespace.)
   114    114   .PP
   115    115   \fBTcl_CreateNamespace\fR creates a new namespace.  The
   116    116   \fIdeleteProc\fR will have the following type signature:
   117    117   .PP
   118    118   .CS
   119    119   typedef void \fBTcl_NamespaceDeleteProc\fR(
   120         -        ClientData \fIclientData\fR);
          120  +        void *\fIclientData\fR);
   121    121   .CE
   122    122   .PP
   123    123   \fBTcl_DeleteNamespace\fR deletes a namespace, calling the
   124    124   \fIdeleteProc\fR defined for the namespace (if any).
   125    125   .PP
   126    126   \fBTcl_AppendExportList\fR retrieves the export patterns for a
   127    127   namespace given namespace and appends them (as list items) to

Changes to doc/Notifier.3.

    34     34   .sp
    35     35   Tcl_ThreadId
    36     36   \fBTcl_GetCurrentThread\fR()
    37     37   .sp
    38     38   void
    39     39   \fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
    40     40   .sp
    41         -ClientData
           41  +void *
    42     42   \fBTcl_InitNotifier\fR()
    43     43   .sp
    44     44   void
    45     45   \fBTcl_FinalizeNotifier\fR(\fIclientData\fR)
    46     46   .sp
    47     47   int
    48     48   \fBTcl_WaitForEvent\fR(\fItimePtr\fR)
................................................................................
    74     74   .AS Tcl_EventDeleteProc *notifierProcPtr
    75     75   .AP Tcl_EventSetupProc *setupProc in
    76     76   Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
    77     77   .AP Tcl_EventCheckProc *checkProc in
    78     78   Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
    79     79   events.  Checks to see if any events have occurred and, if so,
    80     80   queues them.
    81         -.AP ClientData clientData in
           81  +.AP void *clientData in
    82     82   Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
    83     83   \fIdeleteProc\fR.
    84     84   .AP "const Tcl_Time" *timePtr in
    85     85   Indicates the maximum amount of time to wait for an event.  This
    86     86   is specified as an interval (how long to wait), not an absolute
    87     87   time (when to wakeup).  If the pointer passed to \fBTcl_WaitForEvent\fR
    88     88   is NULL, it means there is no maximum wait time:  wait forever if
    89     89   necessary.
    90     90   .AP Tcl_Event *evPtr in
    91     91   An event to add to the event queue.  The storage for the event must
    92         -have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
           92  +have been allocated by the caller using \fBTcl_Alloc\fR.
    93     93   .AP Tcl_QueuePosition position in
    94     94   Where to add the new event in the queue:  \fBTCL_QUEUE_TAIL\fR,
    95     95   \fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
    96     96   .AP Tcl_ThreadId threadId in
    97     97   A unique identifier for a thread.
    98     98   .AP Tcl_EventDeleteProc *deleteProc in
    99     99   Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
................................................................................
   226    226   The procedure \fBTcl_CreateEventSource\fR creates a new event source.
   227    227   Its arguments specify the setup procedure and check procedure for
   228    228   the event source.
   229    229   \fISetupProc\fR should match the following prototype:
   230    230   .PP
   231    231   .CS
   232    232   typedef void \fBTcl_EventSetupProc\fR(
   233         -        ClientData \fIclientData\fR,
          233  +        void *\fIclientData\fR,
   234    234           int \fIflags\fR);
   235    235   .CE
   236    236   .PP
   237    237   The \fIclientData\fR argument will be the same as the \fIclientData\fR
   238    238   argument to \fBTcl_CreateEventSource\fR;  it is typically used to
   239    239   point to private information managed by the event source.
   240    240   The \fIflags\fR argument will be the same as the \fIflags\fR
................................................................................
   304    304   The second procedure provided by each event source is its check
   305    305   procedure, indicated by the \fIcheckProc\fR argument to
   306    306   \fBTcl_CreateEventSource\fR.  \fICheckProc\fR must match the
   307    307   following prototype:
   308    308   .PP
   309    309   .CS
   310    310   typedef void \fBTcl_EventCheckProc\fR(
   311         -        ClientData \fIclientData\fR,
          311  +        void *\fIclientData\fR,
   312    312           int \fIflags\fR);
   313    313   .CE
   314    314   .PP
   315    315   The arguments to this procedure are the same as those for \fIsetupProc\fR.
   316    316   \fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
   317    317   for events.  Presumably at least one event source is now prepared to
   318    318   queue an event.  \fBTcl_DoOneEvent\fR calls each of the event sources
................................................................................
   395    395   Another example of deferring events happens in Tk if
   396    396   \fBTk_RestrictEvents\fR has been invoked to defer certain kinds
   397    397   of window events.
   398    398   .PP
   399    399   When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
   400    400   event from the event queue and free its storage.
   401    401   Note that the storage for an event must be allocated by
   402         -the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
          402  +the event source (using \fBTcl_Alloc\fR)
   403    403   before calling \fBTcl_QueueEvent\fR, but it
   404    404   will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
   405    405   .PP
   406    406   Threaded applications work in a
   407    407   similar manner, except that there is a separate event queue for
   408    408   each thread containing a Tcl interpreter.
   409    409   Calling \fBTcl_QueueEvent\fR in a multithreaded application adds
................................................................................
   424    424   for each event in the queue, deleting those for with the procedure
   425    425   returns 1.  Events for which the procedure returns 0 are left in the
   426    426   queue.  \fIProc\fR should match the following prototype:
   427    427   .PP
   428    428   .CS
   429    429   typedef int \fBTcl_EventDeleteProc\fR(
   430    430           Tcl_Event *\fIevPtr\fR,
   431         -        ClientData \fIclientData\fR);
          431  +        void *\fIclientData\fR);
   432    432   .CE
   433    433   .PP
   434    434   The \fIclientData\fR argument will be the same as the \fIclientData\fR
   435    435   argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
   436    436   private information managed by the event source.  The \fIevPtr\fR will
   437    437   point to the next event in the queue.
   438    438   .PP

Changes to doc/Object.3.

   107    107   .SH "THE TCL_OBJ STRUCTURE"
   108    108   .PP
   109    109   Each Tcl value is represented by a \fBTcl_Obj\fR structure
   110    110   which is defined as follows.
   111    111   .PP
   112    112   .CS
   113    113   typedef struct Tcl_Obj {
   114         -    int \fIrefCount\fR;
          114  +    size_t \fIrefCount\fR;
   115    115       char *\fIbytes\fR;
   116         -    int \fIlength\fR;
          116  +    size_t \fIlength\fR;
   117    117       const Tcl_ObjType *\fItypePtr\fR;
   118    118       union {
   119    119           long \fIlongValue\fR;
   120    120           double \fIdoubleValue\fR;
   121    121           void *\fIotherValuePtr\fR;
   122    122           Tcl_WideInt \fIwideValue\fR;
   123    123           struct {

Changes to doc/ObjectType.3.

   182    182   We require the string representation's byte array
   183    183   to have a null after the last byte, at offset \fIlength\fR,
   184    184   and to have no null bytes before that; this allows string representations
   185    185   to be treated as conventional null character-terminated C strings.
   186    186   These restrictions are easily met by using Tcl's internal UTF encoding
   187    187   for the string representation, same as one would do for other
   188    188   Tcl routines accepting string values as arguments.
   189         -Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
   190         -or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
          189  +Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
          190  +Note that \fIupdateStringProc\fRs must allocate
   191    191   enough storage for the string's bytes and the terminating null byte.
   192    192   .PP
   193    193   The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
   194    194   calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE,
   195    195   then allocates and copies the string representation to just enough
   196    196   space to hold it.  A pointer to the allocated space is stored in
   197    197   the \fIbytes\fR member.

Changes to doc/OpenFileChnl.3.

    49     49   .sp
    50     50   int
    51     51   \fBTcl_ReadChars\fR(\fIchannel, readObjPtr, charsToRead, appendFlag\fR)
    52     52   .sp
    53     53   int
    54     54   \fBTcl_Read\fR(\fIchannel, readBuf, bytesToRead\fR)
    55     55   .sp
    56         -int
           56  +size_t
    57     57   \fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
    58     58   .sp
    59         -int
           59  +size_t
    60     60   \fBTcl_Gets\fR(\fIchannel, lineRead\fR)
    61     61   .sp
    62         -int
           62  +size_t
    63     63   \fBTcl_Ungets\fR(\fIchannel, input, inputLen, addAtEnd\fR)
    64     64   .sp
    65         -int
           65  +size_t
    66     66   \fBTcl_WriteObj\fR(\fIchannel, writeObjPtr\fR)
    67     67   .sp
    68         -int
           68  +size_t
    69     69   \fBTcl_WriteChars\fR(\fIchannel, charBuf, bytesToWrite\fR)
    70     70   .sp
    71         -int
           71  +size_t
    72     72   \fBTcl_Write\fR(\fIchannel, byteBuf, bytesToWrite\fR)
    73     73   .sp
    74         -int
           74  +size_t
    75     75   \fBTcl_ReadRaw\fR(\fIchannel, readBuf, bytesToRead\fR)
    76     76   .sp
    77         -int
           77  +size_t
    78     78   \fBTcl_WriteRaw\fR(\fIchannel, byteBuf, bytesToWrite\fR)
    79     79   .sp
    80     80   int
    81     81   \fBTcl_Eof\fR(\fIchannel\fR)
    82     82   .sp
    83     83   int
    84     84   \fBTcl_Flush\fR(\fIchannel\fR)
................................................................................
   130    130   \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for the first child
   131    131   in the pipe is the pipe channel, otherwise it is the same as the standard
   132    132   input of the invoking process; likewise for \fBTCL_STDOUT\fR and
   133    133   \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set, then the pipe can
   134    134   redirect stdio handles to override the stdio handles for which
   135    135   \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.  If it
   136    136   is set, then such redirections cause an error.
   137         -.AP ClientData handle in
          137  +.AP void *handle in
   138    138   Operating system specific handle for I/O to a file. For Unix this is a
   139    139   file descriptor, for Windows it is a HANDLE.
   140    140   .AP int readOrWrite in
   141    141   OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
   142    142   what operations are valid on \fIhandle\fR.
   143    143   .AP "const char" *channelName in
   144    144   The name of the channel.
................................................................................
   150    150   The pattern to match on, passed to Tcl_StringMatch, or NULL.
   151    151   .AP Tcl_Channel channel in
   152    152   A Tcl channel for input or output.  Must have been the return value
   153    153   from a procedure such as \fBTcl_OpenFileChannel\fR.
   154    154   .AP Tcl_Obj *readObjPtr in/out
   155    155   A pointer to a Tcl value in which to store the characters read from the
   156    156   channel.
   157         -.AP int charsToRead in
          157  +.AP size_t charsToRead in
   158    158   The number of characters to read from the channel.  If the channel's encoding
   159    159   is \fBbinary\fR, this is equivalent to the number of bytes to read from the
   160    160   channel.
   161    161   .AP int appendFlag in
   162    162   If non-zero, data read from the channel will be appended to the value.
   163    163   Otherwise, the data will replace the existing contents of the value.
   164    164   .AP char *readBuf out
   165    165   A buffer in which to store the bytes read from the channel.
   166         -.AP int bytesToRead in
          166  +.AP size_t bytesToRead in
   167    167   The number of bytes to read from the channel.  The buffer \fIreadBuf\fR must
   168    168   be large enough to hold this many bytes.
   169    169   .AP Tcl_Obj *lineObjPtr in/out
   170    170   A pointer to a Tcl value in which to store the line read from the
   171    171   channel.  The line read will be appended to the current value of the
   172    172   value.
   173    173   .AP Tcl_DString *lineRead in/out
   174    174   A pointer to a Tcl dynamic string in which to store the line read from the
   175    175   channel.  Must have been initialized by the caller.  The line read will be
   176    176   appended to any data already in the dynamic string.
   177    177   .AP "const char" *input in
   178    178   The input to add to a channel buffer.
   179         -.AP int inputLen in
          179  +.AP size_t inputLen in
   180    180   Length of the input
   181    181   .AP int addAtEnd in
   182    182   Flag indicating whether the input should be added to the end or
   183    183   beginning of the channel buffer.
   184    184   .AP Tcl_Obj *writeObjPtr in
   185    185   A pointer to a Tcl value whose contents will be output to the channel.
   186    186   .AP "const char" *charBuf in
   187    187   A buffer containing the characters to output to the channel.
   188    188   .AP "const char" *byteBuf in
   189    189   A buffer containing the bytes to output to the channel.
   190         -.AP int bytesToWrite in
          190  +.AP size_t bytesToWrite in
   191    191   The number of bytes to consume from \fIcharBuf\fR or \fIbyteBuf\fR and
   192    192   output to the channel.
   193    193   .AP Tcl_WideInt offset in
   194    194   How far to move the access point in the channel at which the next input or
   195    195   output operation will be applied, measured in bytes from the position
   196    196   given by \fIseekMode\fR.  May be either positive or negative.
   197    197   .AP int seekMode in

Changes to doc/OpenTcp.3.

    46     46   for the local end of the connection.  If NULL, a default interface is
    47     47   chosen.
    48     48   .AP int async in
    49     49   If nonzero, the client socket is connected asynchronously to the server.
    50     50   .AP "unsigned int" flags in
    51     51   ORed combination of \fBTCL_TCPSERVER\fR flags that specify additional
    52     52   informations about the socket being created.
    53         -.AP ClientData sock in
           53  +.AP void *sock in
    54     54   Platform-specific handle for client TCP socket.
    55     55   .AP Tcl_TcpAcceptProc *proc in
    56     56   Pointer to a procedure to invoke each time a new connection is
    57     57   accepted via the socket.
    58         -.AP ClientData clientData in
           58  +.AP void *clientData in
    59     59   Arbitrary one-word value to pass to \fIproc\fR.
    60     60   .BE
    61     61   .SH DESCRIPTION
    62     62   .PP
    63     63   These functions are convenience procedures for creating
    64     64   channels that communicate over TCP sockets.
    65     65   The operations on a channel
................................................................................
   123    123   allow connections from any network interface.
   124    124   Each time a client connects to this socket, Tcl creates a channel
   125    125   for the new connection and invokes \fIproc\fR with information about
   126    126   the channel. \fIProc\fR must match the following prototype:
   127    127   .PP
   128    128   .CS
   129    129   typedef void \fBTcl_TcpAcceptProc\fR(
   130         -        ClientData \fIclientData\fR,
          130  +        void *\fIclientData\fR,
   131    131           Tcl_Channel \fIchannel\fR,
   132    132           char *\fIhostName\fR,
   133    133           int \fIport\fR);
   134    134   .CE
   135    135   .PP
   136    136   The \fIclientData\fR argument will be the same as the \fIclientData\fR
   137    137   argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle

Changes to doc/Panic.3.

     3      3   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     4      4   '\"
     5      5   .TH Tcl_Panic 3 8.4 Tcl "Tcl Library Procedures"
     6      6   .so man.macros
     7      7   .BS
     8      8   '\"  Note:  do not modify the .SH NAME line immediately below!
     9      9   .SH NAME
    10         -Tcl_Panic, Tcl_SetPanicProc \- report fatal error and abort
           10  +Tcl_Panic, Tcl_SetPanicProc, Tcl_ConsolePanic \- report fatal error and abort
    11     11   .SH SYNOPSIS
    12     12   .nf
    13     13   \fB#include <tcl.h>\fR
    14     14   .sp
    15     15   void
    16     16   \fBTcl_Panic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
    17     17   .sp
    18     18   void
    19     19   \fBTcl_SetPanicProc\fR(\fIpanicProc\fR)
    20     20   .sp
           21  +void
           22  +\fBTcl_ConsolePanic\fR(\fIformat\fR, \fIarg\fR, \fIarg\fR, \fI...\fR)
           23  +.sp
    21     24   .SH ARGUMENTS
    22     25   .AS Tcl_PanicProc *panicProc
    23     26   .AP "const char*" format in
    24     27   A printf-style format string.
    25     28   .AP "" arg in
    26     29   Arguments matching the format string.
    27     30   .AP va_list argList in
................................................................................
    46     49   In a freshly loaded Tcl library, \fBTcl_Panic\fR prints the formatted
    47     50   error message to the standard error file of the process, and then
    48     51   calls \fBabort\fR to terminate the process.  \fBTcl_Panic\fR does not
    49     52   return. On Windows, when a debugger is running, the formatted error
    50     53   message is sent to the debugger in stead. If the windows executable
    51     54   does not have a stderr channel (e.g. \fBwish.exe\fR), then a
    52     55   system dialog box is used to display the panic message.
           56  +.PP
           57  +If your application doesn't use \fBTcl_Main\fR or \fBTk_Main\fR
           58  +and you want to implicitly use the stderr channel of your
           59  +application's C runtime (in stead of the stderr channel of the
           60  +C runtime used by Tcl), you can call \fBTcl_SetPanicProc\fR
           61  +with \fBTcl_ConsolePanic\fR as its argument. On platforms which
           62  +only have one C runtime (almost all platforms except Windows)
           63  +\fBTcl_ConsolePanic\fR is equivalent to NULL.
    53     64   .PP
    54     65   \fBTcl_SetPanicProc\fR may be used to modify the behavior of
    55     66   \fBTcl_Panic\fR.  The \fIpanicProc\fR argument should match the
    56     67   type \fBTcl_PanicProc\fR:
    57     68   .PP
    58     69   .CS
    59     70   typedef void \fBTcl_PanicProc\fR(
................................................................................
    73     84   application or the platform.
    74     85   .PP
    75     86   Although the primary callers of \fBTcl_Panic\fR are the procedures of
    76     87   the Tcl library, \fBTcl_Panic\fR is a public function and may be called
    77     88   by any extension or application that wishes to abort the process and
    78     89   have a panic message displayed the same way that panic messages from Tcl
    79     90   will be displayed.
           91  +.PP
           92  +This function can not be used in stub-enabled extensions.
    80     93   .SH "SEE ALSO"
    81     94   abort(3), printf(3), exec(n), format(n)
    82     95   .SH KEYWORDS
    83     96   abort, fatal, error

Changes to doc/ParseArgs.3.

    27     27   stored in \fIremObjv\fR.
    28     28   .AP "Tcl_Obj *const" *objv in
    29     29   The array of arguments to be parsed.
    30     30   .AP Tcl_Obj ***remObjv out
    31     31   Pointer to a variable that will hold the array of unprocessed arguments.
    32     32   Should be NULL if no return of unprocessed arguments is required. If
    33     33   \fIobjcPtr\fR is updated to a non-zero value, the array returned through this
    34         -must be deallocated using \fBckfree\fR.
           34  +must be deallocated using \fBTcl_Free\fR.
    35     35   .BE
    36     36   .SH DESCRIPTION
    37     37   .PP
    38     38   The \fBTcl_ParseArgsObjv\fR function provides a system for parsing argument
    39     39   lists of the form
    40     40   .QW "\fB\-someName \fIsomeValue\fR ..." .
    41     41   Such argument lists are commonly found both in the arguments to a program and
................................................................................
    80     80   .CS
    81     81   typedef struct {
    82     82       int \fItype\fR;
    83     83       const char *\fIkeyStr\fR;
    84     84       void *\fIsrcPtr\fR;
    85     85       void *\fIdstPtr\fR;
    86     86       const char *\fIhelpStr\fR;
    87         -    ClientData \fIclientData\fR;
           87  +    void *\fIclientData\fR;
    88     88   } \fBTcl_ArgvInfo\fR;
    89     89   .CE
    90     90   .PP
    91     91   The \fIkeyStr\fR field contains the name of the option; by convention, this
    92     92   will normally begin with a
    93     93   .QW \fB\-\fR
    94     94   character. The \fItype\fR, \fIsrcPtr\fR, \fIdstPtr\fR and \fIclientData\fR
................................................................................
    99     99   As noted above, the \fItype\fR field is used to describe the interpretation of
   100    100   the argument's value. The following values are acceptable values for
   101    101   \fItype\fR:
   102    102   .TP
   103    103   \fBTCL_ARGV_CONSTANT\fR
   104    104   .
   105    105   The argument does not take any following value argument. If this argument is
   106         -present, the int pointed to by the \fIsrcPtr\fR field is copied to the
   107         -\fIdstPtr\fR field. The \fIclientData\fR field is ignored.
          106  +present, the \fIsrcPtr\fR field (casted to \fIint\fR) is copied to the variable
          107  +pointed to by the \fIdstPtr\fR field. The \fIclientData\fR field is ignored.
   108    108   .TP
   109    109   \fBTCL_ARGV_END\fR
   110    110   .
   111    111   This value marks the end of all option descriptors in the table. All other
   112    112   fields are ignored.
   113    113   .TP
   114    114   \fBTCL_ARGV_FLOAT\fR
................................................................................
   123    123   This argument optionally takes a following value argument; it is up to the
   124    124   handler callback function passed in \fIsrcPtr\fR to decide. That function will
   125    125   have the following signature:
   126    126   .RS
   127    127   .PP
   128    128   .CS
   129    129   typedef int (\fBTcl_ArgvFuncProc\fR)(
   130         -        ClientData \fIclientData\fR,
          130  +        void *\fIclientData\fR,
   131    131           Tcl_Obj *\fIobjPtr\fR,
   132    132           void *\fIdstPtr\fR);
   133    133   .CE
   134    134   .PP
   135    135   The result is a boolean value indicating whether to consume the following
   136    136   argument. The \fIclientData\fR is the value from the table entry, the
   137    137   \fIobjPtr\fR is the value that represents the following argument or NULL if
................................................................................
   145    145   function passed in \fIsrcPtr\fR returns how many (or a negative number to
   146    146   signal an error, in which case it should also set the interpreter result). The
   147    147   function will have the following signature:
   148    148   .RS
   149    149   .PP
   150    150   .CS
   151    151   typedef int (\fBTcl_ArgvGenFuncProc\fR)(
   152         -        ClientData \fIclientData\fR,
          152  +        void *\fIclientData\fR,
   153    153           Tcl_Interp *\fIinterp\fR,
   154    154           int \fIobjc\fR,
   155    155           Tcl_Obj *const *\fIobjv\fR,
   156    156           void *\fIdstPtr\fR);
   157    157   .CE
   158    158   .PP
   159    159   The \fIclientData\fR is the value from the table entry, the \fIinterp\fR is

Changes to doc/ParseCmd.3.

   204    204       int \fInumTokens\fR;
   205    205       ...
   206    206   } \fBTcl_Parse\fR;
   207    207   
   208    208   typedef struct Tcl_Token {
   209    209       int \fItype\fR;
   210    210       const char *\fIstart\fR;
   211         -    int \fIsize\fR;
   212         -    int \fInumComponents\fR;
          211  +    size_t \fIsize\fR;
          212  +    size_t \fInumComponents\fR;
   213    213   } \fBTcl_Token\fR;
   214    214   .CE
   215    215   .PP
   216    216   The first five fields of a Tcl_Parse structure
   217    217   are filled in only by \fBTcl_ParseCommand\fR.
   218    218   These fields are not used by the other parsing procedures.
   219    219   .PP

Changes to doc/Preserve.3.

    17     17   \fBTcl_Preserve\fR(\fIclientData\fR)
    18     18   .sp
    19     19   \fBTcl_Release\fR(\fIclientData\fR)
    20     20   .sp
    21     21   \fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
    22     22   .SH ARGUMENTS
    23     23   .AS Tcl_FreeProc clientData
    24         -.AP ClientData clientData in
           24  +.AP void *clientData in
    25     25   Token describing structure to be freed or reallocated.  Usually a pointer
    26     26   to memory for structure.
    27     27   .AP Tcl_FreeProc *freeProc in
    28     28   Procedure to invoke to free \fIclientData\fR.
    29     29   .BE
    30     30   .SH DESCRIPTION
    31     31   .PP
................................................................................
    87     87   same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
    88     88   The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
    89     89   \fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical
    90     90   reasons, but the value is the same.
    91     91   .PP
    92     92   When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR
    93     93   refers to storage allocated and returned by a prior call to
    94         -\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library,
           94  +\fBTcl_Alloc\fR or another function of the Tcl library,
    95     95   then the \fIfreeProc\fR argument should be given the special value of
    96     96   \fBTCL_DYNAMIC\fR.
    97     97   .PP
    98     98   This mechanism can be used to solve the problem described above
    99     99   by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
   100    100   actions that may cause undesired storage re-allocation.  The
   101    101   mechanism is intended only for short-term use (i.e. while procedures

Changes to doc/RegExp.3.

    60     60   by \fBTcl_GetRegExpFromObj\fR or \fBTcl_RegExpCompile\fR.
    61     61   .AP char *start in
    62     62   If \fItext\fR is just a portion of some other string, this argument
    63     63   identifies the beginning of the larger string.
    64     64   If it is not the same as \fItext\fR, then no
    65     65   .QW \fB^\fR
    66     66   matches will be allowed.
    67         -.AP int index in
           67  +.AP size_t index in
    68     68   Specifies which range is desired:  0 means the range of the entire
    69     69   match, 1 or greater means the range that matched a parenthesized
    70     70   sub-expression.
    71     71   .AP "const char" **startPtr out
    72     72   The address of the first character in the range is stored here, or
    73     73   NULL if there is no such range.
    74     74   .AP "const char" **endPtr out
................................................................................
    76     76   is stored here, or NULL if there is no such range.
    77     77   .AP int cflags in
    78     78   OR-ed combination of the compilation flags \fBTCL_REG_ADVANCED\fR,
    79     79   \fBTCL_REG_EXTENDED\fR, \fBTCL_REG_BASIC\fR, \fBTCL_REG_EXPANDED\fR,
    80     80   \fBTCL_REG_QUOTE\fR, \fBTCL_REG_NOCASE\fR, \fBTCL_REG_NEWLINE\fR,
    81     81   \fBTCL_REG_NLSTOP\fR, \fBTCL_REG_NLANCH\fR, \fBTCL_REG_NOSUB\fR, and
    82     82   \fBTCL_REG_CANMATCH\fR. See below for more information.
    83         -.AP int offset in
           83  +.AP size_t offset in
    84     84   The character offset into the text where matching should begin.
    85     85   The value of the offset has no impact on \fB^\fR matches.  This
    86     86   behavior is controlled by \fIeflags\fR.
    87         -.AP int nmatches in
           87  +.AP size_t nmatches in
    88     88   The number of matching subexpressions that should be remembered for
    89     89   later use.  If this value is 0, then no subexpression match
    90         -information will be computed.  If the value is \-1, then
           90  +information will be computed.  If the value is TCL_INDEX_NONE, then
    91     91   all of the matching subexpressions will be remembered.  Any other
    92     92   value will be taken as the maximum number of subexpressions to
    93     93   remember.
    94     94   .AP int eflags in
    95     95   OR-ed combination of the execution flags \fBTCL_REG_NOTBOL\fR and
    96     96   \fBTCL_REG_NOTEOL\fR. See below for more information.
    97     97   .AP Tcl_RegExpInfo *infoPtr out
................................................................................
   333    333   \fBTcl_RegExpGetInfo\fR retrieves information about the last match
   334    334   performed with a given regular expression \fIregexp\fR.  The
   335    335   \fIinfoPtr\fR argument contains a pointer to a structure that is
   336    336   defined as follows:
   337    337   .PP
   338    338   .CS
   339    339   typedef struct Tcl_RegExpInfo {
   340         -    int \fInsubs\fR;
          340  +    size_t \fInsubs\fR;
   341    341       Tcl_RegExpIndices *\fImatches\fR;
   342         -    long \fIextendStart\fR;
          342  +    size_t \fIextendStart\fR;
   343    343   } \fBTcl_RegExpInfo\fR;
   344    344   .CE
   345    345   .PP
   346    346   The \fInsubs\fR field contains a count of the number of parenthesized
   347    347   subexpressions within the regular expression.  If the \fBTCL_REG_NOSUB\fR
   348    348   was used, then this value will be zero.  The \fImatches\fR field
   349    349   points to an array of \fInsubs\fR+1 values that indicate the bounds of each
................................................................................
   351    351   range matched by the entire regular expression, and subsequent elements
   352    352   refer to the parenthesized subexpressions in the order that they
   353    353   appear in the pattern.  Each element is a structure that is defined as
   354    354   follows:
   355    355   .PP
   356    356   .CS
   357    357   typedef struct Tcl_RegExpIndices {
   358         -    long \fIstart\fR;
   359         -    long \fIend\fR;
          358  +    size_t \fIstart\fR;
          359  +    size_t \fIend\fR;
   360    360   } \fBTcl_RegExpIndices\fR;
   361    361   .CE
   362    362   .PP
   363    363   The \fIstart\fR and \fIend\fR values are Unicode character indices
   364    364   relative to the offset location within \fIobjPtr\fR where matching began.
   365    365   The \fIstart\fR index identifies the first character of the matched
   366    366   subexpression.  The \fIend\fR index identifies the first character

Changes to doc/SaveResult.3.

     1      1   '\"
     2      2   '\" Copyright (c) 1997 by Sun Microsystems, Inc.
     3      3   '\" Contributions from Don Porter, NIST, 2004. (not subject to US copyright)
            4  +'\" Copyright (c) 2018 Nathan Coulter.
     4      5   '\"
     5      6   '\" See the file "license.terms" for information on usage and redistribution
     6      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      8   '\"
     8      9   .TH Tcl_SaveResult 3 8.1 Tcl "Tcl Library Procedures"
     9     10   .so man.macros
    10     11   .BS
    11     12   .SH NAME
    12         -Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState, Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- save and restore an interpreter's state
           13  +Tcl_SaveInterpState, Tcl_RestoreInterpState, Tcl_DiscardInterpState,
           14  +Tcl_SaveResult, Tcl_RestoreResult, Tcl_DiscardResult \- Save and restore the
           15  +state of an an interpreter.
    13     16   .SH SYNOPSIS
    14     17   .nf
    15     18   \fB#include <tcl.h>\fR
    16     19   .sp
    17     20   Tcl_InterpState
    18     21   \fBTcl_SaveInterpState\fR(\fIinterp, status\fR)
    19     22   .sp
................................................................................
    26     29   .sp
    27     30   \fBTcl_RestoreResult\fR(\fIinterp, savedPtr\fR)
    28     31   .sp
    29     32   \fBTcl_DiscardResult\fR(\fIsavedPtr\fR)
    30     33   .SH ARGUMENTS
    31     34   .AS Tcl_InterpState savedPtr
    32     35   .AP Tcl_Interp *interp in
    33         -Interpreter for which state should be saved.
           36  +The interpreter for the operation.
    34     37   .AP int status in
    35         -Return code value to save as part of interpreter state.
           38  +The return code for the state.
    36     39   .AP Tcl_InterpState state in
    37         -Saved state token to be restored or discarded.
           40  +A token for saved state.
    38     41   .AP Tcl_SavedResult *savedPtr in
    39         -Pointer to location where interpreter result should be saved or restored.
           42  +A pointer to storage for saved state.
    40     43   .BE
    41     44   .SH DESCRIPTION
    42     45   .PP
    43         -These routines allows a C procedure to take a snapshot of the current
    44         -state of an interpreter so that it can be restored after a call
    45         -to \fBTcl_Eval\fR or some other routine that modifies the interpreter
    46         -state.  There are two triplets of routines meant to work together.
           46  +These routines save the state of an interpreter before a call to a routine such
           47  +as \fBTcl_Eval\fR, and restore the state afterwards.
           48  +.PP
           49  +\fBTcl_SaveInterpState\fR saves the parts of \fIinterp\fR that comprise the
           50  +result of a script, including the resulting value, the return code passed as
           51  +\fIstatus\fR, and any options such as \fB\-errorinfo\fR and \fB\-errorcode\fR.
           52  +It returns a token for the saved state.  The interpreter result is not reset
           53  +and no interpreter state is changed.
           54  +.PP
           55  +\fBTcl_RestoreInterpState\fR restores the state indicated by \fIstate\fR and
           56  +returns the \fIstatus\fR originally passed in the corresponding call to
           57  +\fBTcl_SaveInterpState\fR.
           58  +.PP
           59  +If a saved state is not restored, \fBTcl_DiscardInterpState\fR must be called
           60  +to release it.  A token used to discard or restore state must not be used
           61  +again.
    47     62   .PP
    48         -The first triplet stores the snapshot of interpreter state in
    49         -an opaque token returned by \fBTcl_SaveInterpState\fR.  That token
    50         -value may then be passed back to one of \fBTcl_RestoreInterpState\fR
    51         -or \fBTcl_DiscardInterpState\fR, depending on whether the interp
    52         -state is to be restored.  So long as one of the latter two routines
    53         -is called, Tcl will take care of memory management.
           63  +\fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR, and \fBTcl_DiscardResult\fR are
           64  +deprecated.  Instead use \fBTcl_SaveInterpState\fR,
           65  +\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR, which are more
           66  +capable.
    54     67   .PP
    55         -The second triplet stores the snapshot of only the interpreter
    56         -result (not its complete state) in memory allocated by the caller.
    57         -These routines are passed a pointer to \fBTcl_SavedResult\fR
    58         -that is used to store enough information to restore the interpreter result.
    59         -\fBTcl_SavedResult\fR can be allocated on the stack of the calling
    60         -procedure.  These routines do not save the state of any error
    61         -information in the interpreter (e.g. the \fB\-errorcode\fR or
    62         -\fB\-errorinfo\fR return options, when an error is in progress).
           68  +\fBTcl_SaveResult\fR moves the result of \fIinterp\fR to the location
           69  +\fIstatePtr\fR points to and returns the interpreter result to its initial
           70  +state.  It does not save options such as \fB\-errorcode\fR or
           71  +\fB\-errorinfo\fR.
    63     72   .PP
    64         -Because the routines \fBTcl_SaveInterpState\fR,
    65         -\fBTcl_RestoreInterpState\fR, and \fBTcl_DiscardInterpState\fR perform
    66         -a superset of the functions provided by the other routines,
    67         -any new code should only make use of the more powerful routines.
    68         -The older, weaker routines \fBTcl_SaveResult\fR, \fBTcl_RestoreResult\fR,
    69         -and \fBTcl_DiscardResult\fR continue to exist only for the sake
    70         -of existing programs that may already be using them.
           73  +\fBTcl_RestoreResult\fR clears any existing result or error in \fIinterp\fR and
           74  +moves the result from \fIstatePtr\fR back to \fIinterp\fR.  \fIstatePtr\fR is
           75  +then in an undefined state and must not be used until passed again to
           76  +\fBTcl_SaveResult\fR.
    71     77   .PP
    72         -\fBTcl_SaveInterpState\fR takes a snapshot of those portions of
    73         -interpreter state that make up the full result of script evaluation.
    74         -This include the interpreter result, the return code (passed in
    75         -as the \fIstatus\fR argument, and any return options, including
    76         -\fB\-errorinfo\fR and \fB\-errorcode\fR when an error is in progress.
    77         -This snapshot is returned as an opaque token of type \fBTcl_InterpState\fR.
    78         -The call to \fBTcl_SaveInterpState\fR does not itself change the
    79         -state of the interpreter.  Unlike \fBTcl_SaveResult\fR, it does
    80         -not reset the interpreter.
    81         -.PP
    82         -\fBTcl_RestoreInterpState\fR accepts a \fBTcl_InterpState\fR token
    83         -previously returned by \fBTcl_SaveInterpState\fR and restores the
    84         -state of the interp to the state held in that snapshot.  The return
    85         -value of \fBTcl_RestoreInterpState\fR is the status value originally
    86         -passed to \fBTcl_SaveInterpState\fR when the snapshot token was
    87         -created.
    88         -.PP
    89         -\fBTcl_DiscardInterpState\fR is called to release a \fBTcl_InterpState\fR
    90         -token previously returned by \fBTcl_SaveInterpState\fR when that
    91         -snapshot is not to be restored to an interp.
    92         -.PP
    93         -The \fBTcl_InterpState\fR token returned by \fBTcl_SaveInterpState\fR
    94         -must eventually be passed to either \fBTcl_RestoreInterpState\fR
    95         -or \fBTcl_DiscardInterpState\fR to avoid a memory leak.  Once
    96         -the \fBTcl_InterpState\fR token is passed to one of them, the
    97         -token is no longer valid and should not be used anymore.
    98         -.PP
    99         -\fBTcl_SaveResult\fR moves the string and value results
   100         -of \fIinterp\fR into the location specified by \fIstatePtr\fR.
   101         -\fBTcl_SaveResult\fR clears the result for \fIinterp\fR and
   102         -leaves the result in its normal empty initialized state.
   103         -.PP
   104         -\fBTcl_RestoreResult\fR moves the string and value results from
   105         -\fIstatePtr\fR back into \fIinterp\fR.  Any result or error that was
   106         -already in the interpreter will be cleared.  The \fIstatePtr\fR is left
   107         -in an uninitialized state and cannot be used until another call to
           78  +\fBTcl_DiscardResult\fR releases the state stored at \fBstatePtr\fR, which is
           79  +then in an undefined state and must not be used until passed again to
   108     80   \fBTcl_SaveResult\fR.
   109     81   .PP
   110         -\fBTcl_DiscardResult\fR releases the saved interpreter state
   111         -stored at \fBstatePtr\fR.  The state structure is left in an
   112         -uninitialized state and cannot be used until another call to
   113         -\fBTcl_SaveResult\fR.
   114         -.PP
   115         -Once \fBTcl_SaveResult\fR is called to save the interpreter
   116         -result, either \fBTcl_RestoreResult\fR or
   117         -\fBTcl_DiscardResult\fR must be called to properly clean up the
   118         -memory associated with the saved state.
           82  +If a saved result is not restored, \fBTcl_DiscardResult\fR must be called to
           83  +release it.
   119     84   .SH KEYWORDS
   120     85   result, state, interp

Changes to doc/SplitList.3.

    16     16   .sp
    17     17   int
    18     18   \fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
    19     19   .sp
    20     20   char *
    21     21   \fBTcl_Merge\fR(\fIargc, argv\fR)
    22     22   .sp
    23         -int
           23  +size_t
    24     24   \fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
    25     25   .sp
    26         -int
           26  +size_t
    27     27   \fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
    28     28   .sp
    29         -int
           29  +size_t
    30     30   \fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
    31     31   .sp
    32         -int
           32  +size_t
    33     33   \fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
    34     34   .SH ARGUMENTS
    35     35   .AS "const char *const" ***argvPtr out
    36     36   .AP Tcl_Interp *interp out
    37     37   Interpreter to use for error reporting.  If NULL, then no error message
    38     38   is left.
    39     39   .AP char *list in
................................................................................
    51     51   Array of strings to merge together into a single list.
    52     52   Each string will become a separate element of the list.
    53     53   .AP "const char" *src in
    54     54   String that is to become an element of a list.
    55     55   .AP int *flagsPtr in
    56     56   Pointer to word to fill in with information about \fIsrc\fR.
    57     57   The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
    58         -.AP int length in
           58  +.AP size_t length in
    59     59   Number of bytes in string \fIsrc\fR.
    60     60   .AP char *dst in
    61     61   Place to copy converted list element.  Must contain enough characters
    62     62   to hold converted string.
    63     63   .AP int flags in
    64     64   Information about \fIsrc\fR. Must be value returned by previous
    65     65   call to \fBTcl_ScanElement\fR, possibly OR-ed

Changes to doc/StaticPkg.3.

    60     60   The \fIinterp\fR argument identifies the interpreter in which the package
    61     61   is to be loaded.  The initialization procedure must return \fBTCL_OK\fR or
    62     62   \fBTCL_ERROR\fR to indicate whether or not it completed successfully; in
    63     63   the event of an error it should set the interpreter's result to point to an
    64     64   error message.  The result or error from the initialization procedure will
    65     65   be returned as the result of the \fBload\fR command that caused the
    66     66   initialization procedure to be invoked.
           67  +.PP
           68  +This function can not be used in stub-enabled extensions.
    67     69   .SH KEYWORDS
    68     70   initialization procedure, package, static linking
    69     71   .SH "SEE ALSO"
    70     72   load(n), package(n), Tcl_PkgRequire(3)

Changes to doc/StringObj.3.

    33     33   .sp
    34     34   Tcl_UniChar *
    35     35   \fBTcl_GetUnicodeFromObj\fR(\fIobjPtr, lengthPtr\fR)
    36     36   .sp
    37     37   Tcl_UniChar *
    38     38   \fBTcl_GetUnicode\fR(\fIobjPtr\fR)
    39     39   .sp
    40         -Tcl_UniChar
           40  +int
    41     41   \fBTcl_GetUniChar\fR(\fIobjPtr, index\fR)
    42     42   .sp
    43     43   int
    44     44   \fBTcl_GetCharLength\fR(\fIobjPtr\fR)
    45     45   .sp
    46     46   Tcl_Obj *
    47     47   \fBTcl_GetRange\fR(\fIobjPtr, first, last\fR)
................................................................................
    83     83   \fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
    84     84   .SH ARGUMENTS
    85     85   .AS "const Tcl_UniChar" *appendObjPtr in/out
    86     86   .AP "const char" *bytes in
    87     87   Points to the first byte of an array of UTF-8-encoded bytes
    88     88   used to set or append to a string value.
    89     89   This byte array may contain embedded null characters
    90         -unless \fInumChars\fR is negative.  (Applications needing null bytes
           90  +unless \fInumChars\fR is TCL_AUTO_LENGTH.  (Applications needing null bytes
    91     91   should represent them as the two-byte sequence \fI\e700\e600\fR, use
    92     92   \fBTcl_ExternalToUtf\fR to convert, or \fBTcl_NewByteArrayObj\fR if
    93     93   the string is a collection of uninterpreted bytes.)
    94         -.AP int length in
           94  +.AP size_t length in
    95     95   The number of bytes to copy from \fIbytes\fR when
    96     96   initializing, setting, or appending to a string value.
    97         -If negative, all bytes up to the first null are used.
           97  +If TCL_AUTO_LENGTH, all bytes up to the first null are used.
    98     98   .AP "const Tcl_UniChar" *unicode in
    99     99   Points to the first byte of an array of Unicode characters
   100    100   used to set or append to a string value.
   101    101   This byte array may contain embedded null characters
   102    102   unless \fInumChars\fR is negative.
   103         -.AP int numChars in
          103  +.AP size_t numChars in
   104    104   The number of Unicode characters to copy from \fIunicode\fR when
   105    105   initializing, setting, or appending to a string value.
   106         -If negative, all characters up to the first null character are used.
   107         -.AP int index in
          106  +If TCL_AUTO_LENGTH, all characters up to the first null character are used.
          107  +.AP size_t index in
   108    108   The index of the Unicode character to return.
   109         -.AP int first in
          109  +.AP size_t first in
   110    110   The index of the first Unicode character in the Unicode range to be
   111    111   returned as a new value.
   112         -.AP int last in
          112  +.AP size_t last in
   113    113   The index of the last Unicode character in the Unicode range to be
   114    114   returned as a new value.
   115    115   .AP Tcl_Obj *objPtr in/out
   116    116   Points to a value to manipulate.
   117    117   .AP Tcl_Obj *appendObjPtr in
   118    118   The value to append to \fIobjPtr\fR in \fBTcl_AppendObjToObj\fR.
   119    119   .AP int *lengthPtr out
................................................................................
   120    120   If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
   121    121   the length of a value's string representation.
   122    122   .AP "const char" *string in
   123    123   Null-terminated string value to append to \fIobjPtr\fR.
   124    124   .AP va_list argList in
   125    125   An argument list which must have been initialized using
   126    126   \fBva_start\fR, and cleared using \fBva_end\fR.
   127         -.AP int limit in
          127  +.AP size_t limit in
   128    128   Maximum number of bytes to be appended.
   129    129   .AP "const char" *ellipsis in
   130    130   Suffix to append when the limit leads to string truncation.
   131    131   If NULL is passed then the suffix
   132    132   .QW "..."
   133    133   is used.
   134    134   .AP "const char" *format in
   135    135   Format control string including % conversion specifiers.
   136    136   .AP int objc in
   137    137   The number of elements to format or concatenate.
   138    138   .AP Tcl_Obj *objv[] in
   139    139   The array of values to format or concatenate.
   140         -.AP int newLength in
          140  +.AP size_t newLength in
   141    141   New length for the string value of \fIobjPtr\fR, not including the
   142    142   final null character.
   143    143   .BE
   144    144   .SH DESCRIPTION
   145    145   .PP
   146    146   The procedures described in this manual entry allow Tcl values to
   147    147   be manipulated as string values.  They use the internal representation
................................................................................
   197    197   \fIlengthPtr\fR if it is non-NULL.  The storage referenced by the returned
   198    198   byte pointer is owned by the value manager and should not be modified by
   199    199   the caller.  The procedure \fBTcl_GetUnicode\fR is used in the common case
   200    200   where the caller does not need the length of the unicode string
   201    201   representation.
   202    202   .PP
   203    203   \fBTcl_GetUniChar\fR returns the \fIindex\fR'th character in the
   204         -value's Unicode representation.
          204  +value's Unicode representation. If the index is out of range or
          205  +it references a low surrogate preceded by a high surrogate, it returns -1;
   205    206   .PP
   206    207   \fBTcl_GetRange\fR returns a newly created value comprised of the
   207    208   characters between \fIfirst\fR and \fIlast\fR (inclusive) in the
   208    209   value's Unicode representation.  If the value's Unicode
   209    210   representation is invalid, the Unicode representation is regenerated
   210    211   from the value's string representation.
   211    212   .PP

Changes to doc/TCL_MEM_DEBUG.3.

    30     30   .PP
    31     31   Once memory debugging support has been compiled into Tcl, the C
    32     32   functions \fBTcl_ValidateAllMemory\fR, and \fBTcl_DumpActiveMemory\fR,
    33     33   and the Tcl \fBmemory\fR command can be used to validate and examine
    34     34   memory usage.
    35     35   .SH "GUARD ZONES"
    36     36   .PP
    37         -When memory debugging is enabled, whenever a call to \fBckalloc\fR is
           37  +When memory debugging is enabled, whenever a call to \fBTcl_Alloc\fR is
    38     38   made, slightly more memory than requested is allocated so the memory
    39     39   debugging code can keep track of the allocated memory, and eight-byte
    40     40   .QW "guard zones"
    41     41   are placed in front of and behind the space that will be
    42     42   returned to the caller.  (The sizes of the guard zones are defined by the
    43     43   C #define \fBLOW_GUARD_SIZE\fR and #define \fBHIGH_GUARD_SIZE\fR
    44     44   in the file \fIgeneric/tclCkalloc.c\fR \(em it can
    45     45   be extended if you suspect large overwrite problems, at some cost in
    46     46   performance.)  A known pattern is written into the guard zones and, on
    47         -a call to \fBckfree\fR, the guard zones of the space being freed are
           47  +a call to \fBTcl_Free\fR, the guard zones of the space being freed are
    48     48   checked to see if either zone has been modified in any way.  If one
    49     49   has been, the guard bytes and their new contents are identified, and a
    50     50   .QW "low guard failed"
    51     51   or
    52     52   .QW "high guard failed"
    53     53   message is issued.  The
    54     54   .QW "guard failed"
    55     55   message includes the address of the memory packet and
    56         -the file name and line number of the code that called \fBckfree\fR.
           56  +the file name and line number of the code that called \fBTcl_Free\fR.
    57     57   This allows you to detect the common sorts of one-off problems, where
    58     58   not enough space was allocated to contain the data written, for
    59     59   example.
    60     60   .SH "DEBUGGING DIFFICULT MEMORY CORRUPTION PROBLEMS"
    61     61   .PP
    62     62   Normally, Tcl compiled with memory debugging enabled will make it easy
    63     63   to isolate a corruption problem.  Turning on memory validation with
    64     64   the memory command can help isolate difficult problems.  If you
    65     65   suspect (or know) that corruption is occurring before the Tcl
    66     66   interpreter comes up far enough for you to issue commands, you can set
    67     67   \fBMEM_VALIDATE\fR define, recompile tclCkalloc.c and rebuild Tcl.
    68     68   This will enable memory validation from the first call to
    69         -\fBckalloc\fR, again, at a large performance impact.
           69  +\fBTcl_Alloc\fR, again, at a large performance impact.
    70     70   .PP
    71     71   If you are desperate and validating memory on every call to
    72         -\fBckalloc\fR and \fBckfree\fR is not enough, you can explicitly call
           72  +\fBTcl_Alloc\fR and \fBTcl_Free\fR is not enough, you can explicitly call
    73     73   \fBTcl_ValidateAllMemory\fR directly at any point.  It takes a \fIchar
    74     74   *\fR and an \fIint\fR which are normally the filename and line number
    75     75   of the caller, but they can actually be anything you want.  Remember
    76     76   to remove the calls after you find the problem.
    77     77   .SH "SEE ALSO"
    78         -ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
           78  +Tcl_Alloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
    79     79   .SH KEYWORDS
    80     80   memory, debug

Changes to doc/Tcl.n.

    24     24   (see below) unless quoted.
    25     25   .IP "[2] \fBEvaluation.\fR"
    26     26   A command is evaluated in two steps.
    27     27   First, the Tcl interpreter breaks the command into \fIwords\fR
    28     28   and performs substitutions as described below.
    29     29   These substitutions are performed in the same way for all
    30     30   commands.
    31         -Secondly, the first word is used to locate a command procedure to
    32         -carry out the command, then all of the words of the command are
    33         -passed to the command procedure.
    34         -The command procedure is free to interpret each of its words
           31  +Secondly, the first word is used to locate a routine to
           32  +carry out the command, and the remaining words of the command are
           33  +passed to that routine.
           34  +The routine is free to interpret each of its words
    35     35   in any way it likes, such as an integer, variable name, list,
    36     36   or Tcl script.
    37     37   Different commands interpret their words differently.
    38     38   .IP "[3] \fBWords.\fR"
    39     39   Words of a command are separated by white space (except for
    40     40   newlines, which are command separators).
    41     41   .IP "[4] \fBDouble quotes.\fR"

Changes to doc/TclZlib.3.

    84     84   section \fBGZIP OPTIONS DICTIONARY\fR for details about the contents of this
    85     85   dictionary.
    86     86   .AP "unsigned int" initValue in
    87     87   The initial value for the checksum algorithm.
    88     88   .AP "unsigned char" *bytes in
    89     89   An array of bytes to run the checksum algorithm over, or NULL to get the
    90     90   recommended initial value for the checksum algorithm.
    91         -.AP int length in
           91  +.AP size_t length in
    92     92   The number of bytes in the array.
    93     93   .AP int mode in
    94     94   What mode to operate the stream in. Should be either
    95     95   \fBTCL_ZLIB_STREAM_DEFLATE\fR for a compressing stream or
    96     96   \fBTCL_ZLIB_STREAM_INFLATE\fR for a decompressing stream.
    97     97   .AP Tcl_ZlibStream *zshandlePtr out
    98     98   A pointer to a variable in which to write the abstract token for the stream
................................................................................
   103    103   Whether and how to flush the stream after writing the data to it. Must be one
   104    104   of: \fBTCL_ZLIB_NO_FLUSH\fR if no flushing is to be done, \fBTCL_ZLIB_FLUSH\fR
   105    105   if the currently compressed data must be made available for access using
   106    106   \fBTcl_ZlibStreamGet\fR, \fBTCL_ZLIB_FULLFLUSH\fR if the stream must be put
   107    107   into a state where the decompressor can recover from on corruption, or
   108    108   \fBTCL_ZLIB_FINALIZE\fR to ensure that the stream is finished and that any
   109    109   trailer demanded by the format is written.
   110         -.AP int count in
   111         -The maximum number of bytes to get from the stream, or -1 to get all remaining
   112         -bytes from the stream's buffers.
          110  +.AP size_t count in
          111  +The maximum number of bytes to get from the stream, or TCL_AUTO_LENGTH to get
          112  +all remaining bytes from the stream's buffers.
   113    113   .AP Tcl_Obj *compDict in
   114    114   A byte array value that is the compression dictionary to use with the stream.
   115    115   Note that this is \fInot a Tcl dictionary\fR, and it is recommended that this
   116    116   only ever be used with streams that were created with their \fIformat\fR set
   117    117   to \fBTCL_ZLIB_FORMAT_ZLIB\fR because the other formats have no mechanism to
   118    118   indicate whether a compression dictionary was present other than to fail on
   119    119   decompression.

Changes to doc/Tcl_Main.3.

   185    185   evaluated.  In interactive mode, if an EOF or channel error
   186    186   is encountered on the standard input channel, then \fBTcl_Main\fR
   187    187   itself will evaluate the \fBexit\fR command after the main loop
   188    188   procedure (if any) returns.  In non-interactive mode, after
   189    189   \fBTcl_Main\fR evaluates the startup script, and the main loop
   190    190   procedure (if any) returns, \fBTcl_Main\fR will also evaluate
   191    191   the \fBexit\fR command.
          192  +.PP
          193  +This function can not be used in stub-enabled extensions.
   192    194   .SH "SEE ALSO"
   193    195   tclsh(1), Tcl_GetStdChannel(3), Tcl_StandardChannels(3), Tcl_AppInit(3),
   194    196   exit(n), encoding(n)
   195    197   .SH KEYWORDS
   196    198   application-specific initialization, command-line arguments, main program

Changes to doc/Thread.3.

    41     41   int
    42     42   \fBTcl_JoinThread\fR(\fIid, result\fR)
    43     43   .SH ARGUMENTS
    44     44   .AS Tcl_CreateThreadProc proc out
    45     45   .AP Tcl_Condition *condPtr in
    46     46   A condition variable, which must be associated with a mutex lock.
    47     47   .AP Tcl_Mutex *mutexPtr in
    48         -A mutex lock.
           48  +.VS TIP509
           49  +A recursive mutex lock.
           50  +.VE TIP509
    49     51   .AP "const Tcl_Time" *timePtr in
    50     52   A time limit on the condition wait.  NULL to wait forever.
    51     53   Note that a polling value of 0 seconds does not make much sense.
    52     54   .AP Tcl_ThreadDataKey *keyPtr in
    53     55   This identifies a block of thread local storage.  The key should be
    54     56   static and process-wide, yet each thread will end up associating
    55     57   a different block of storage with this key.
................................................................................
    61     63   The referred storage will contain the id of the newly created thread as
    62     64   returned by the operating system.
    63     65   .AP Tcl_ThreadId id in
    64     66   Id of the thread waited upon.
    65     67   .AP Tcl_ThreadCreateProc *proc in
    66     68   This procedure will act as the \fBmain()\fR of the newly created
    67     69   thread. The specified \fIclientData\fR will be its sole argument.
    68         -.AP ClientData clientData in
           70  +.AP void *clientData in
    69     71   Arbitrary information. Passed as sole argument to the \fIproc\fR.
    70     72   .AP int stackSize in
    71     73   The size of the stack given to the new thread.
    72     74   .AP int flags in
    73     75   Bitmask containing flags allowing the caller to modify behavior of
    74     76   the new thread.
    75     77   .AP int *result out
................................................................................
   136    138   the \fBNotifier\fR manual page for more information on these procedures.
   137    139   .PP
   138    140   A mutex is a lock that is used to serialize all threads through a piece
   139    141   of code by calling \fBTcl_MutexLock\fR and \fBTcl_MutexUnlock\fR.
   140    142   If one thread holds a mutex, any other thread calling \fBTcl_MutexLock\fR will
   141    143   block until \fBTcl_MutexUnlock\fR is called.
   142    144   A mutex can be destroyed after its use by calling \fBTcl_MutexFinalize\fR.
   143         -The result of locking a mutex twice from the same thread is undefined.
   144         -On some platforms it will result in a deadlock.
          145  +.VS TIP509
          146  +Mutexes are reentrant: they can be locked several times from the same
          147  +thread. However there must be exactly one call to
          148  +\fBTcl_MutexUnlock\fR for each call to \fBTcl_MutexLock\fR in order
          149  +for a thread to release a mutex completely.
          150  +.VE TIP509
   145    151   The \fBTcl_MutexLock\fR, \fBTcl_MutexUnlock\fR and \fBTcl_MutexFinalize\fR
   146    152   procedures are defined as empty macros if not compiling with threads enabled.
   147    153   For declaration of mutexes the \fBTCL_DECLARE_MUTEX\fR macro should be used.
   148    154   This macro assures correct mutex handling even when the core is compiled
   149    155   without threads enabled.
   150    156   .PP
   151    157   A condition variable is used as a signaling mechanism:
................................................................................
   198    204   .PP
   199    205   It should then be defined like this example, which just counts up to a given
   200    206   value and then finishes.
   201    207   .PP
   202    208   .CS
   203    209   static \fBTcl_ThreadCreateType\fR
   204    210   MyThreadImplFunc(
   205         -    ClientData clientData)
          211  +    void *clientData)
   206    212   {
   207    213       int i, limit = (int) clientData;
   208    214       for (i=0 ; i<limit ; i++) {
   209    215           /* doing nothing at all here */
   210    216       }
   211    217       \fBTCL_THREAD_CREATE_RETURN\fR;
   212    218   }
................................................................................
   213    219   .CE
   214    220   .PP
   215    221   To create the above thread, make it execute, and wait for it to finish, we
   216    222   would do this:
   217    223   .PP
   218    224   .CS
   219    225   int limit = 1000000000;
   220         -ClientData limitData = (void*)((intptr_t) limit);
          226  +void *limitData = (void*)((intptr_t) limit);
   221    227   Tcl_ThreadId id;    \fI/* holds identity of thread created */\fR
   222    228   int result;
   223    229   
   224    230   if (\fBTcl_CreateThread\fR(&id, MyThreadImplFunc, limitData,
   225    231           \fBTCL_THREAD_STACK_DEFAULT\fR,
   226    232           \fBTCL_THREAD_JOINABLE\fR) != TCL_OK) {
   227    233       \fI/* Thread did not create correctly */\fR

Changes to doc/ToUpper.3.

     9      9   .BS
    10     10   .SH NAME
    11     11   Tcl_UniCharToUpper, Tcl_UniCharToLower, Tcl_UniCharToTitle, Tcl_UtfToUpper, Tcl_UtfToLower, Tcl_UtfToTitle \- routines for manipulating the case of Unicode characters and UTF-8 strings
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16         -Tcl_UniChar
           16  +int
    17     17   \fBTcl_UniCharToUpper\fR(\fIch\fR)
    18     18   .sp
    19         -Tcl_UniChar
           19  +int
    20     20   \fBTcl_UniCharToLower\fR(\fIch\fR)
    21     21   .sp
    22         -Tcl_UniChar
           22  +int
    23     23   \fBTcl_UniCharToTitle\fR(\fIch\fR)
    24     24   .sp
    25     25   int
    26     26   \fBTcl_UtfToUpper\fR(\fIstr\fR)
    27     27   .sp
    28     28   int
    29     29   \fBTcl_UtfToLower\fR(\fIstr\fR)
................................................................................
    74     74   \fBTcl_UtfToLower\fR is the same as \fBTcl_UtfToUpper\fR except it
    75     75   turns each character in the string into its lower-case equivalent.
    76     76   .PP
    77     77   \fBTcl_UtfToTitle\fR is the same as \fBTcl_UtfToUpper\fR except it
    78     78   turns the first character in the string into its title-case equivalent
    79     79   and all following characters into their lower-case equivalents.
    80     80   
    81         -.SH BUGS
    82         -.PP
    83         -At this time, the case conversions are only defined for the ISO8859-1
    84         -characters.  Unicode characters above 0x00ff are not modified by these
    85         -routines.
    86         -
    87     81   .SH KEYWORDS
    88     82   utf, unicode, toupper, tolower, totitle, case

Changes to doc/TraceCmd.3.

     9      9   .BS
    10     10   .SH NAME
    11     11   Tcl_CommandTraceInfo, Tcl_TraceCommand, Tcl_UntraceCommand \- monitor renames and deletes of a command
    12     12   .SH SYNOPSIS
    13     13   .nf
    14     14   \fB#include <tcl.h>\fR
    15     15   .sp
    16         -ClientData
           16  +void *
    17     17   \fBTcl_CommandTraceInfo(\fIinterp, cmdName, flags, proc, prevClientData\fB)\fR
    18     18   .sp
    19     19   int
    20     20   \fBTcl_TraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
    21     21   .sp
    22     22   void
    23     23   \fBTcl_UntraceCommand(\fIinterp, cmdName, flags, proc, clientData\fB)\fR
................................................................................
    28     28   .AP "const char" *cmdName in
    29     29   Name of command.
    30     30   .AP int flags in
    31     31   OR'ed collection of the values \fBTCL_TRACE_RENAME\fR and
    32     32   \fBTCL_TRACE_DELETE\fR.
    33     33   .AP Tcl_CommandTraceProc *proc in
    34     34   Procedure to call when specified operations occur to \fIcmdName\fR.
    35         -.AP ClientData clientData in
           35  +.AP void *clientData in
    36     36   Arbitrary argument to pass to \fIproc\fR.
    37         -.AP ClientData prevClientData in
           37  +.AP void *prevClientData in
    38     38   If non-NULL, gives last value returned by \fBTcl_CommandTraceInfo\fR,
    39     39   so this call will return information about next trace.  If NULL, this
    40     40   call will return information about first trace.
    41     41   .BE
    42     42   .SH DESCRIPTION
    43     43   .PP
    44     44   \fBTcl_TraceCommand\fR allows a C procedure to monitor operations
................................................................................
    61     61   .PP
    62     62   Whenever one of the specified operations occurs to the command,
    63     63   \fIproc\fR will be invoked.  It should have arguments and result that
    64     64   match the type \fBTcl_CommandTraceProc\fR:
    65     65   .PP
    66     66   .CS
    67     67   typedef void \fBTcl_CommandTraceProc\fR(
    68         -        ClientData \fIclientData\fR,
           68  +        void *\fIclientData\fR,
    69     69           Tcl_Interp *\fIinterp\fR,
    70     70           const char *\fIoldName\fR,
    71     71           const char *\fInewName\fR,
    72     72           int \fIflags\fR);
    73     73   .CE
    74     74   .PP
    75     75   The \fIclientData\fR and \fIinterp\fR parameters will have the same
    76     76   values as those passed to \fBTcl_TraceCommand\fR when the trace was
    77         -created.  \fIClientData\fR typically points to an application-specific
           77  +created.  \fIclientData\fR typically points to an application-specific
    78     78   data structure that describes what to do when \fIproc\fR is invoked.
    79     79   \fIOldName\fR gives the name of the command being renamed, and
    80     80   \fInewName\fR gives the name that the command is being renamed to (or
    81     81   NULL when the command is being deleted.)
    82     82   \fIFlags\fR is an OR'ed combination of bits potentially providing
    83     83   several pieces of information.  One of the bits \fBTCL_TRACE_RENAME\fR and
    84     84   \fBTCL_TRACE_DELETE\fR will be set in \fIflags\fR to indicate which

Changes to doc/TraceVar.3.

    20     20   int
    21     21   \fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
    22     22   .sp
    23     23   \fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
    24     24   .sp
    25     25   \fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
    26     26   .sp
    27         -ClientData
           27  +void *
    28     28   \fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
    29     29   .sp
    30         -ClientData
           30  +void *
    31     31   \fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
    32     32   .SH ARGUMENTS
    33         -.AS Tcl_VarTraceProc prevClientData
           33  +.AS void *prevClientData
    34     34   .AP Tcl_Interp *interp in
    35     35   Interpreter containing variable.
    36     36   .AP "const char" *varName in
    37     37   Name of variable.  May refer to a scalar variable, to
    38     38   an array variable with no index, or to an array variable
    39     39   with a parenthesized index.
    40     40   .AP int flags in
................................................................................
    42     42   \fBTCL_TRACE_WRITES\fR, \fBTCL_TRACE_UNSETS\fR, \fBTCL_TRACE_ARRAY\fR,
    43     43   \fBTCL_GLOBAL_ONLY\fR, \fBTCL_NAMESPACE_ONLY\fR,
    44     44   \fBTCL_TRACE_RESULT_DYNAMIC\fR and \fBTCL_TRACE_RESULT_OBJECT\fR.
    45     45   Not all flags are used by all
    46     46   procedures.  See below for more information.
    47     47   .AP Tcl_VarTraceProc *proc in
    48     48   Procedure to invoke whenever one of the traced operations occurs.
    49         -.AP ClientData clientData in
           49  +.AP void *clientData in
    50     50   Arbitrary one-word value to pass to \fIproc\fR.
    51     51   .AP "const char" *name1 in
    52     52   Name of scalar or array variable (without array index).
    53     53   .AP "const char" *name2 in
    54     54   For a trace on an element of an array, gives the index of the
    55     55   element.  For traces on scalar variables or on whole arrays,
    56     56   is NULL.
    57         -.AP ClientData prevClientData in
           57  +.AP void *prevClientData in
    58     58   If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
    59     59   \fBTcl_VarTraceInfo2\fR, so this call will return information about
    60     60   next trace.  If NULL, this call will return information about first
    61     61   trace.
    62     62   .BE
    63     63   .SH DESCRIPTION
    64     64   .PP
................................................................................
   103    103   This gives the trace procedure a chance to update the array before
   104    104   array names or array get is called.  Note that this is called
   105    105   before an array set, but that will trigger write traces.
   106    106   .TP
   107    107   \fBTCL_TRACE_RESULT_DYNAMIC\fR
   108    108   The result of invoking the \fIproc\fR is a dynamically allocated
   109    109   string that will be released by the Tcl library via a call to
   110         -\fBckfree\fR.  Must not be specified at the same time as
          110  +\fBTcl_Free\fR.  Must not be specified at the same time as
   111    111   \fBTCL_TRACE_RESULT_OBJECT\fR.
   112    112   .TP
   113    113   \fBTCL_TRACE_RESULT_OBJECT\fR
   114    114   The result of invoking the \fIproc\fR is a Tcl_Obj* (cast to a char*)
   115    115   with a reference count of at least one.  The ownership of that
   116    116   reference will be transferred to the Tcl core for release (when the
   117    117   core has finished with it) via a call to \fBTcl_DecrRefCount\fR.  Must
................................................................................
   120    120   Whenever one of the specified operations occurs on the variable,
   121    121   \fIproc\fR will be invoked.
   122    122   It should have arguments and result that match the type
   123    123   \fBTcl_VarTraceProc\fR:
   124    124   .PP
   125    125   .CS
   126    126   typedef char *\fBTcl_VarTraceProc\fR(
   127         -        ClientData \fIclientData\fR,
          127  +        void *\fIclientData\fR,
   128    128           Tcl_Interp *\fIinterp\fR,
   129    129           char *\fIname1\fR,
   130    130           char *\fIname2\fR,
   131    131           int \fIflags\fR);
   132    132   .CE
   133    133   .PP
   134    134   The \fIclientData\fR and \fIinterp\fR parameters will
   135    135   have the same values as those passed to \fBTcl_TraceVar\fR when the
   136    136   trace was created.
   137         -\fIClientData\fR typically points to an application-specific
          137  +\fIclientData\fR typically points to an application-specific
   138    138   data structure that describes what to do when \fIproc\fR
   139    139   is invoked.
   140    140   \fIName1\fR and \fIname2\fR give the name of the traced variable
   141    141   in the normal two-part form (see the description of \fBTcl_TraceVar2\fR
   142    142   below for details).
   143    143   \fIFlags\fR is an OR-ed combination of bits providing several
   144    144   pieces of information.
................................................................................
   308    308   successful completion.
   309    309   If \fIproc\fR returns a non-NULL value it signifies that an
   310    310   error occurred.
   311    311   The return value must be a pointer to a static character string
   312    312   containing an error message,
   313    313   unless (\fIexactly\fR one of) the \fBTCL_TRACE_RESULT_DYNAMIC\fR and
   314    314   \fBTCL_TRACE_RESULT_OBJECT\fR flags is set, which specify that the result is
   315         -either a dynamic string (to be released with \fBckfree\fR) or a
          315  +either a dynamic string (to be released with \fBTcl_Free\fR) or a
   316    316   Tcl_Obj* (cast to char* and to be released with
   317    317   \fBTcl_DecrRefCount\fR) containing the error message.
   318    318   If a trace procedure returns an error, no further traces are
   319    319   invoked for the access and the traced access aborts with the
   320    320   given message.
   321    321   Trace procedures can use this facility to make variables
   322    322   read-only, for example (but note that the value of the variable
................................................................................
   327    327   The return value from \fIproc\fR is only used during read and
   328    328   write tracing.
   329    329   During unset traces, the return value is ignored and all relevant
   330    330   trace procedures will always be invoked.
   331    331   .SH "RESTRICTIONS"
   332    332   .PP
   333    333   A trace procedure can be called at any time, even when there
   334         -is a partially formed result in the interpreter's result area.  If
          334  +are partially formed results stored in the interpreter.  If
   335    335   the trace procedure does anything that could damage this result (such
   336         -as calling \fBTcl_Eval\fR) then it must save the original values of
   337         -the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
   338         -them before it returns.
          336  +as calling \fBTcl_Eval\fR) then it must use the \fBTcl_SaveInterpState\fR
          337  +and related routines to save and restore the original state of
          338  +the interpreter before it returns.
   339    339   .SH "UNDEFINED VARIABLES"
   340    340   .PP
   341    341   It is legal to set a trace on an undefined variable.
   342    342   The variable will still appear to be undefined until the
   343    343   first time its value is set.
   344    344   If an undefined variable is traced and then unset, the unset will fail
   345    345   with an error

Changes to doc/Utf.3.

    27     27   Tcl_UniChar *
    28     28   \fBTcl_UtfToUniCharDString\fR(\fIsrc, length, dsPtr\fR)
    29     29   .sp
    30     30   int
    31     31   \fBTcl_UniCharLen\fR(\fIuniStr\fR)
    32     32   .sp
    33     33   int
    34         -\fBTcl_UniCharNcmp\fR(\fIucs, uct, numChars\fR)
           34  +\fBTcl_UniCharNcmp\fR(\fIucs, uct, uniLength\fR)
    35     35   .sp
    36     36   int
    37         -\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, numChars\fR)
           37  +\fBTcl_UniCharNcasecmp\fR(\fIucs, uct, uniLength\fR)
    38     38   .sp
    39     39   int
    40     40   \fBTcl_UniCharCaseMatch\fR(\fIuniStr, uniPattern, nocase\fR)
    41     41   .sp
    42     42   int
    43         -\fBTcl_UtfNcmp\fR(\fIcs, ct, numChars\fR)
           43  +\fBTcl_UtfNcmp\fR(\fIcs, ct, length\fR)
    44     44   .sp
    45     45   int
    46         -\fBTcl_UtfNcasecmp\fR(\fIcs, ct, numChars\fR)
           46  +\fBTcl_UtfNcasecmp\fR(\fIcs, ct, length\fR)
    47     47   .sp
    48     48   int
    49     49   \fBTcl_UtfCharComplete\fR(\fIsrc, length\fR)
    50     50   .sp
    51     51   int
    52     52   \fBTcl_NumUtfChars\fR(\fIsrc, length\fR)
    53     53   .sp
................................................................................
    59     59   .sp
    60     60   const char *
    61     61   \fBTcl_UtfNext\fR(\fIsrc\fR)
    62     62   .sp
    63     63   const char *
    64     64   \fBTcl_UtfPrev\fR(\fIsrc, start\fR)
    65     65   .sp
    66         -Tcl_UniChar
           66  +int
    67     67   \fBTcl_UniCharAtIndex\fR(\fIsrc, index\fR)
    68     68   .sp
    69     69   const char *
    70     70   \fBTcl_UtfAtIndex\fR(\fIsrc, index\fR)
    71     71   .sp
    72         -int
           72  +size_t
    73     73   \fBTcl_UtfBackslash\fR(\fIsrc, readPtr, dst\fR)
    74     74   .SH ARGUMENTS
    75     75   .AS "const Tcl_UniChar" *uniPattern in/out
    76     76   .AP char *buf out
    77     77   Buffer in which the UTF-8 representation of the Tcl_UniChar is stored.  At most
    78     78   \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
    79     79   .AP int ch in
................................................................................
    90     90   A null-terminated Unicode string.
    91     91   .AP "const Tcl_UniChar" *ucs in
    92     92   A null-terminated Unicode string.
    93     93   .AP "const Tcl_UniChar" *uct in
    94     94   A null-terminated Unicode string.
    95     95   .AP "const Tcl_UniChar" *uniPattern in
    96     96   A null-terminated Unicode string.
    97         -.AP int length in
           97  +.AP size_t length in
    98     98   The length of the UTF-8 string in bytes (not UTF-8 characters).  If
    99         -negative, all bytes up to the first null byte are used.
   100         -.AP int uniLength in
   101         -The length of the Unicode string in characters.  Must be greater than or
   102         -equal to 0.
           99  +TCL_AUTO_LENGTH, all bytes up to the first null byte are used.
          100  +.AP size_t uniLength in
          101  +The length of the Unicode string in characters.
   103    102   .AP "Tcl_DString" *dsPtr in/out
   104    103   A pointer to a previously initialized \fBTcl_DString\fR.
   105         -.AP "unsigned long" numChars in
   106         -The number of characters to compare.
   107    104   .AP "const char" *start in
   108    105   Pointer to the beginning of a UTF-8 string.
   109         -.AP int index in
          106  +.AP size_t index in
   110    107   The index of a character (not byte) in the UTF-8 string.
   111    108   .AP int *readPtr out
   112    109   If non-NULL, filled with the number of bytes in the backslash sequence,
   113    110   including the backslash character.
   114    111   .AP char *dst out
   115    112   Buffer in which the bytes represented by the backslash sequence are stored.
   116    113   At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
................................................................................
   117    114   .AP int nocase in
   118    115   Specifies whether the match should be done case-sensitive (0) or
   119    116   case-insensitive (1).
   120    117   .BE
   121    118   
   122    119   .SH DESCRIPTION
   123    120   .PP
   124         -These routines convert between UTF-8 strings and Tcl_UniChars.  A
   125         -Tcl_UniChar is a Unicode character represented as an unsigned, fixed-size
          121  +These routines convert between UTF-8 strings and Unicode characters.  An
          122  +Unicode character represented as an unsigned, fixed-size
   126    123   quantity.  A UTF-8 character is a Unicode character represented as
   127    124   a varying-length sequence of up to \fBTCL_UTF_MAX\fR bytes.  A multibyte UTF-8
   128    125   sequence consists of a lead byte followed by some number of trail bytes.
   129    126   .PP
   130    127   \fBTCL_UTF_MAX\fR is the maximum number of bytes that it takes to
   131    128   represent one Unicode character in the UTF-8 representation.
   132    129   .PP
   133         -\fBTcl_UniCharToUtf\fR stores the Tcl_UniChar \fIch\fR as a UTF-8 string
          130  +\fBTcl_UniCharToUtf\fR stores the character \fIch\fR as a UTF-8 string
   134    131   in starting at \fIbuf\fR.  The return value is the number of bytes stored
   135         -in \fIbuf\fR.
          132  +in \fIbuf\fR. If ch is a high surrogate (range U+D800 - U+DBFF), then
          133  +the return value will be 1 and a single byte in the range 0xF0 - 0xF4
          134  +will be stored. If you still want to produce UTF-8 output for it (even
          135  +though knowing it's an illegal code-point on its own), just call
          136  +\fBTcl_UniCharToUtf\fR again specifying ch = -1.
   136    137   .PP
   137    138   \fBTcl_UtfToUniChar\fR reads one UTF-8 character starting at \fIsrc\fR
   138    139   and stores it as a Tcl_UniChar in \fI*chPtr\fR.  The return value is the
   139    140   number of bytes read from \fIsrc\fR.  The caller must ensure that the
   140    141   source buffer is long enough such that this routine does not run off the
   141    142   end and dereference non-existent or random memory; if the source buffer
   142    143   is known to be null-terminated, this will not happen.  If the input is
          144  +a byte in the range 0x80 - 0x9F, \fBTcl_UtfToUniChar\fR assumes the
          145  +cp1252 encoding, stores the corresponding Tcl_UniChar in \fI*chPtr\fR
          146  +and returns 1. If the input is otherwise
   143    147   not in proper UTF-8 format, \fBTcl_UtfToUniChar\fR will store the first
   144    148   byte of \fIsrc\fR in \fI*chPtr\fR as a Tcl_UniChar between 0x0000 and
   145    149   0x00ff and return 1.
   146    150   .PP
   147    151   \fBTcl_UniCharToUtfDString\fR converts the given Unicode string
   148    152   to UTF-8, storing the result in a previously initialized \fBTcl_DString\fR.
   149    153   You must specify \fIuniLength\fR, the length of the given Unicode string.
................................................................................
   165    169   \fBTcl_UniCharLen\fR corresponds to \fBstrlen\fR for Unicode
   166    170   characters.  It accepts a null-terminated Unicode string and returns
   167    171   the number of Unicode characters (not bytes) in that string.
   168    172   .PP
   169    173   \fBTcl_UniCharNcmp\fR and \fBTcl_UniCharNcasecmp\fR correspond to
   170    174   \fBstrncmp\fR and \fBstrncasecmp\fR, respectively, for Unicode characters.
   171    175   They accept two null-terminated Unicode strings and the number of characters
   172         -to compare.  Both strings are assumed to be at least \fInumChars\fR characters
          176  +to compare.  Both strings are assumed to be at least \fIuniLength\fR characters
   173    177   long. \fBTcl_UniCharNcmp\fR  compares the two strings character-by-character
   174    178   according to the Unicode character ordering.  It returns an integer greater
   175    179   than, equal to, or less than 0 if the first string is greater than, equal
   176    180   to, or less than the second string respectively.  \fBTcl_UniCharNcasecmp\fR
   177    181   is the Unicode case insensitive version.
   178    182   .PP
   179    183   \fBTcl_UniCharCaseMatch\fR is the Unicode equivalent to
   180    184   \fBTcl_StringCaseMatch\fR.  It accepts a null-terminated Unicode string,
   181    185   a Unicode pattern, and a boolean value specifying whether the match should
   182    186   be case sensitive and returns whether the string matches the pattern.
   183    187   .PP
   184    188   \fBTcl_UtfNcmp\fR corresponds to \fBstrncmp\fR for UTF-8 strings. It
   185    189   accepts two null-terminated UTF-8 strings and the number of characters
   186         -to compare.  (Both strings are assumed to be at least \fInumChars\fR
          190  +to compare.  (Both strings are assumed to be at least \fIlength\fR
   187    191   characters long.)  \fBTcl_UtfNcmp\fR compares the two strings
   188    192   character-by-character according to the Unicode character ordering.
   189    193   It returns an integer greater than, equal to, or less than 0 if the
   190    194   first string is greater than, equal to, or less than the second string
   191    195   respectively.
   192    196   .PP
   193    197   \fBTcl_UtfNcasecmp\fR corresponds to \fBstrncasecmp\fR for UTF-8
................................................................................
   196    200   characters.
   197    201   .PP
   198    202   \fBTcl_UtfCharComplete\fR returns 1 if the source UTF-8 string \fIsrc\fR
   199    203   of \fIlength\fR bytes is long enough to be decoded by
   200    204   \fBTcl_UtfToUniChar\fR, or 0 otherwise.  This function does not guarantee
   201    205   that the UTF-8 string is properly formed.  This routine is used by
   202    206   procedures that are operating on a byte at a time and need to know if a
   203         -full Tcl_UniChar has been seen.
          207  +full Unicode character has been seen.
   204    208   .PP
   205    209   \fBTcl_NumUtfChars\fR corresponds to \fBstrlen\fR for UTF-8 strings.  It
   206    210   returns the number of Tcl_UniChars that are represented by the UTF-8 string
   207    211   \fIsrc\fR.  The length of the source string is \fIlength\fR bytes.  If the
   208    212   length is negative, all bytes up to the first null byte are used.
   209    213   .PP
   210    214   \fBTcl_UtfFindFirst\fR corresponds to \fBstrchr\fR for UTF-8 strings.  It
   211         -returns a pointer to the first occurrence of the Tcl_UniChar \fIch\fR
          215  +returns a pointer to the first occurrence of the Unicode character \fIch\fR
   212    216   in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
   213    217   considered part of the UTF-8 string.
   214    218   .PP
   215    219   \fBTcl_UtfFindLast\fR corresponds to \fBstrrchr\fR for UTF-8 strings.  It
   216         -returns a pointer to the last occurrence of the Tcl_UniChar \fIch\fR
          220  +returns a pointer to the last occurrence of the Unicode character \fIch\fR
   217    221   in the null-terminated UTF-8 string \fIsrc\fR.  The null terminator is
   218    222   considered part of the UTF-8 string.
   219    223   .PP
   220    224   Given \fIsrc\fR, a pointer to some location in a UTF-8 string,
   221    225   \fBTcl_UtfNext\fR returns a pointer to the next UTF-8 character in the
   222    226   string.  The caller must not ask for the next character after the last
   223    227   character in the string if the string is not terminated by a null
................................................................................
   231    235   the start of the UTF-8 string.  If \fIsrc\fR was already at \fIstart\fR, the
   232    236   return value will be \fIstart\fR.
   233    237   .PP
   234    238   \fBTcl_UniCharAtIndex\fR corresponds to a C string array dereference or the
   235    239   Pascal Ord() function.  It returns the Tcl_UniChar represented at the
   236    240   specified character (not byte) \fIindex\fR in the UTF-8 string
   237    241   \fIsrc\fR.  The source string must contain at least \fIindex\fR
   238         -characters.  Behavior is undefined if a negative \fIindex\fR is given.
          242  +characters.
   239    243   .PP
   240    244   \fBTcl_UtfAtIndex\fR returns a pointer to the specified character (not
   241    245   byte) \fIindex\fR in the UTF-8 string \fIsrc\fR.  The source string must
   242    246   contain at least \fIindex\fR characters.  This is equivalent to calling
   243         -\fBTcl_UtfNext\fR \fIindex\fR times.  If a negative \fIindex\fR is given,
          247  +\fBTcl_UtfNext\fR \fIindex\fR times.  If \fIindex\fR is TCL_INDEX_NONE,
   244    248   the return pointer points to the first character in the source string.
   245    249   .PP
   246    250   \fBTcl_UtfBackslash\fR is a utility procedure used by several of the Tcl
   247    251   commands.  It parses a backslash sequence and stores the properly formed
   248    252   UTF-8 character represented by the backslash sequence in the output
   249    253   buffer \fIdst\fR.  At most \fBTCL_UTF_MAX\fR bytes are stored in the buffer.
   250    254   \fBTcl_UtfBackslash\fR modifies \fI*readPtr\fR to contain the number

Added doc/abstract.n.

            1  +'\"
            2  +'\" Copyright (c) 2018 Donal K. Fellows
            3  +'\"
            4  +'\" See the file "license.terms" for information on usage and redistribution
            5  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            6  +'\"
            7  +.TH abstract n 0.3 TclOO "TclOO Commands"
            8  +.so man.macros
            9  +.BS
           10  +'\" Note:  do not modify the .SH NAME line immediately below!
           11  +.SH NAME
           12  +oo::abstract \- a class that does not allow direct instances of itself
           13  +.SH SYNOPSIS
           14  +.nf
           15  +package require TclOO
           16  +
           17  +\fBoo::abstract\fI method \fR?\fIarg ...\fR?
           18  +.fi
           19  +.SH "CLASS HIERARCHY"
           20  +.nf
           21  +\fBoo::object\fR
           22  +   \(-> \fBoo::class\fR
           23  +       \(-> \fBoo::abstract\fR
           24  +.fi
           25  +.BE
           26  +.SH DESCRIPTION
           27  +Abstract classes are classes that can contain definitions, but which cannot be
           28  +directly manufactured; they are intended to only ever be inherited from and
           29  +instantiated indirectly. The characteristic methods of \fBoo::class\fR
           30  +(\fBcreate\fR and \fBnew\fR) are not exported by an instance of
           31  +\fBoo::abstract\fR.
           32  +.PP
           33  +Note that \fBoo::abstract\fR is not itself an instance of \fBoo::abstract\fR.
           34  +.SS CONSTRUCTOR
           35  +The \fBoo::abstract\fR class does not define an explicit constructor; this
           36  +means that it is effectively the same as the constructor of the
           37  +\fBoo::class\fR class.
           38  +.SS DESTRUCTOR
           39  +The \fBoo::abstract\fR class does not define an explicit destructor;
           40  +destroying an instance of it is just like destroying an ordinary class (and
           41  +will destroy all its subclasses).
           42  +.SS "EXPORTED METHODS"
           43  +The \fBoo::abstract\fR class defines no new exported methods.
           44  +.SS "NON-EXPORTED METHODS"
           45  +The \fBoo::abstract\fR class explicitly states that \fBcreate\fR,
           46  +\fBcreateWithNamespace\fR, and \fBnew\fR are unexported.
           47  +.SH EXAMPLES
           48  +.PP
           49  +This example defines a simple class hierarchy and creates a new instance of
           50  +it. It then invokes a method of the object before destroying the hierarchy and
           51  +showing that the destruction is transitive.
           52  +.PP
           53  +.CS
           54  +\fBoo::abstract\fR create fruit {
           55  +    method eat {} {
           56  +        puts "yummy!"
           57  +    }
           58  +}
           59  +oo::class create banana {
           60  +    superclass fruit
           61  +    method peel {} {
           62  +        puts "skin now off"
           63  +    }
           64  +}
           65  +set b [banana \fBnew\fR]
           66  +$b peel              \fI\(-> prints 'skin now off'\fR
           67  +$b eat               \fI\(-> prints 'yummy!'\fR
           68  +set f [fruit new]    \fI\(-> error 'unknown method "new"...'\fR
           69  +.CE
           70  +.SH "SEE ALSO"
           71  +oo::define(n), oo::object(n)
           72  +.SH KEYWORDS
           73  +abstract class, class, metaclass, object
           74  +.\" Local variables:
           75  +.\" mode: nroff
           76  +.\" fill-column: 78
           77  +.\" End:

Changes to doc/append.n.

    16     16   .BE
    17     17   .SH DESCRIPTION
    18     18   .PP
    19     19   Append all of the \fIvalue\fR arguments to the current value
    20     20   of variable \fIvarName\fR.  If \fIvarName\fR does not exist,
    21     21   it is given a value equal to the concatenation of all the
    22     22   \fIvalue\fR arguments.
           23  +.VS TIP508
           24  +If \fIvarName\fR indicate an element that does not exist of an array that has
           25  +a default value set, the concatenation of the default value and all the
           26  +\fIvalue\fR arguments will be stored in the array element.
           27  +.VE TIP508
    23     28   The result of this command is the new value stored in variable
    24     29   \fIvarName\fR.
    25     30   This command provides an efficient way to build up long
    26     31   variables incrementally.
    27     32   For example,
    28     33   .QW "\fBappend a $b\fR"
    29     34   is much more efficient than
................................................................................
    40     45   puts $var
    41     46   # Prints 0,1,2,3,4,5,6,7,8,9,10
    42     47   .CE
    43     48   .SH "SEE ALSO"
    44     49   concat(n), lappend(n)
    45     50   .SH KEYWORDS
    46     51   append, variable
    47         -'\" Local Variables:
    48         -'\" mode: nroff
    49         -'\" End:
           52  +.\" Local variables:
           53  +.\" mode: nroff
           54  +.\" fill-column: 78
           55  +.\" End:

Changes to doc/array.n.

     1      1   '\"
     2      2   '\" Copyright (c) 1993-1994 The Regents of the University of California.
     3      3   '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
     4      4   '\"
     5      5   '\" See the file "license.terms" for information on usage and redistribution
     6      6   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     7      7   '\"
     8         -.TH array n 8.3 Tcl "Tcl Built-In Commands"
            8  +.TH array n 8.7 Tcl "Tcl Built-In Commands"
     9      9   .so man.macros
    10     10   .BS
    11     11   '\" Note:  do not modify the .SH NAME line immediately below!
    12     12   .SH NAME
    13     13   array \- Manipulate array variables
    14     14   .SH SYNOPSIS
    15     15   \fBarray \fIoption arrayName\fR ?\fIarg arg ...\fR?
................................................................................
    31     31   \fISearchId\fR indicates which search on \fIarrayName\fR to
    32     32   check, and must have been the return value from a previous
    33     33   invocation of \fBarray startsearch\fR.
    34     34   This option is particularly useful if an array has an element
    35     35   with an empty name, since the return value from
    36     36   \fBarray nextelement\fR will not indicate whether the search
    37     37   has been completed.
           38  +.TP
           39  +\fBarray default \fIsubcommand arrayName args...\fR
           40  +.VS TIP508
           41  +Manages the default value of the array. Arrays initially have no default
           42  +value, but this command allows you to set one; the default value will be
           43  +returned when reading from an element of the array \fIarrayName\fR if the read
           44  +would otherwise result in an error. Note that this may cause the \fBappend\fR,
           45  +\fBdict\fR, \fBincr\fR and \fBlappend\fR commands to change their behavior in
           46  +relation to non-existing array elements.
           47  +.RS
           48  +.PP
           49  +The \fIsubcommand\fR argument controls what exact operation will be performed
           50  +on the default value of \fIarrayName\fR. Supported \fIsubcommand\fRs are:
           51  +.VE TIP508
           52  +.TP
           53  +\fBarray default exists \fIarrayName\fR
           54  +.VS TIP508
           55  +This returns a boolean value indicating whether a default value has been set
           56  +for the array \fIarrayName\fR. Returns a false value if \fIarrayName\fR does
           57  +not exist. Raises an error if \fIarrayName\fR is an existing variable that is
           58  +not an array.
           59  +.VE TIP508
           60  +.TP
           61  +\fBarray default get \fIarrayName\fR
           62  +.VS TIP508
           63  +This returns the current default value for the array \fIarrayName\fR.  Raises
           64  +an error if \fIarrayName\fR is an existing variable that is not an array, or
           65  +if \fIarrayName\fR is an array without a default value.
           66  +.VE TIP508
           67  +.TP
           68  +\fBarray default set \fIarrayName value\fR
           69  +.VS TIP508
           70  +This sets the default value for the array \fIarrayName\fR to \fIvalue\fR.
           71  +Returns the empty string. Raises an error if \fIarrayName\fR is an existing
           72  +variable that is not an array, or if \fIarrayName\fR is an illegal name for an
           73  +array. If \fIarrayName\fR does not currently exist, it is created as an empty
           74  +array as well as having its default value set.
           75  +.VE TIP508
           76  +.TP
           77  +\fBarray default unset \fIarrayName\fR
           78  +.VS TIP508
           79  +This removes the default value for the array \fIarrayName\fR and returns the
           80  +empty string. Does nothing if \fIarrayName\fR does not have a default
           81  +value. Raises an error if \fIarrayName\fR is an existing variable that is not
           82  +an array.
           83  +.VE TIP508
           84  +.RE
    38     85   .TP
    39     86   \fBarray donesearch \fIarrayName searchId\fR
    40     87   This command terminates an array search and destroys all the
    41     88   state associated with that search.  \fISearchId\fR indicates
    42     89   which search on \fIarrayName\fR to destroy, and must have
    43     90   been the return value from a previous invocation of
    44     91   \fBarray startsearch\fR.  Returns an empty string.
    45     92   .TP
    46     93   \fBarray exists \fIarrayName\fR
    47     94   Returns 1 if \fIarrayName\fR is an array variable, 0 if there
    48     95   is no variable by that name or if it is a scalar variable.
    49     96   .TP
           97  +\fBarray for {\fIkeyVariable valueVariable\fB} \fIarrayName body\fP
           98  +The first argument is a two element list of variable names for the
           99  +key and value of each entry in the array.  The second argument is the
          100  +array name to iterate over.  The third argument is the body to execute
          101  +for each key and value returned.
          102  +The ordering of the returned keys is undefined.
          103  +If an array element is deleted or a new array element is inserted during
          104  +the \fIarray for\fP process, the command will terminate with an error.
          105  +.TP
    50    106   \fBarray get \fIarrayName\fR ?\fIpattern\fR?
    51    107   Returns a list containing pairs of elements.  The first
    52    108   element in each pair is the name of an element in \fIarrayName\fR
    53    109   and the second element of each pair is the value of the
    54    110   array element.  The order of the pairs is undefined.
    55    111   If \fIpattern\fR is not specified, then all of the elements of the
    56    112   array are included in the result.
................................................................................
   181    237       number of buckets with 10 or more entries: 0
   182    238       average search distance for entry: 1.2
   183    239   .CE
   184    240   .SH "SEE ALSO"
   185    241   list(n), string(n), variable(n), trace(n), foreach(n)
   186    242   .SH KEYWORDS
   187    243   array, element names, search
          244  +.\" Local variables:
          245  +.\" mode: nroff
          246  +.\" fill-column: 78
          247  +.\" End:

Added doc/callback.n.

            1  +'\"
            2  +'\" Copyright (c) 2018 Donal K. Fellows
            3  +'\"
            4  +'\" See the file "license.terms" for information on usage and redistribution
            5  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            6  +'\"
            7  +.TH callback n 0.3 TclOO "TclOO Commands"
            8  +.so man.macros
            9  +.BS
           10  +'\" Note:  do not modify the .SH NAME line immediately below!
           11  +.SH NAME
           12  +callback, mymethod \- generate callbacks to methods
           13  +.SH SYNOPSIS
           14  +.nf
           15  +package require TclOO
           16  +
           17  +\fBcallback\fR \fImethodName\fR ?\fIarg ...\fR?
           18  +\fBmymethod\fR \fImethodName\fR ?\fIarg ...\fR?
           19  +.fi
           20  +.BE
           21  +.SH DESCRIPTION
           22  +The \fBcallback\fR command,
           23  +'\" Based on notes in the tcllib docs, we know the provenance of mymethod
           24  +also called \fBmymethod\fR for compatibility with the ooutil and snit packages
           25  +of Tcllib,
           26  +and which should only be used from within the context of a call to a method
           27  +(i.e. inside a method, constructor or destructor body) is used to generate a
           28  +script fragment that will invoke the method, \fImethodName\fR, on the current
           29  +object (as reported by \fBself\fR) when executed. Any additional arguments
           30  +provided will be provided as leading arguments to the callback. The resulting
           31  +script fragment shall be a proper list.
           32  +.PP
           33  +Note that it is up to the caller to ensure that the current object is able to
           34  +handle the call of \fImethodName\fR; this command does not check that.
           35  +\fImethodName\fR may refer to any exported or unexported method, but may not
           36  +refer to a private method as those can only be invoked directly from within
           37  +methods. If there is no such method present at the point when the callback is
           38  +invoked, the standard \fBunknown\fR method handler will be called.
           39  +.SH EXAMPLE
           40  +This is a simple echo server class. The \fBcallback\fR command is used in two
           41  +places, to arrange for the incoming socket connections to be handled by the
           42  +\fIAccept\fR method, and to arrange for the incoming bytes on those
           43  +connections to be handled by the \fIReceive\fR method.
           44  +.PP
           45  +.CS
           46  +oo::class create EchoServer {
           47  +    variable server clients
           48  +    constructor {port} {
           49  +        set server [socket -server [\fBcallback\fR Accept] $port]
           50  +        set clients {}
           51  +    }
           52  +    destructor {
           53  +        chan close $server
           54  +        foreach client [dict keys $clients] {
           55  +            chan close $client
           56  +        }
           57  +    }
           58  +
           59  +    method Accept {channel clientAddress clientPort} {
           60  +        dict set clients $channel [dict create \e
           61  +                address $clientAddress port $clientPort]
           62  +        chan event $channel readable [\fBcallback\fR Receive $channel]
           63  +    }
           64  +    method Receive {channel} {
           65  +        if {[chan gets $channel line] >= 0} {
           66  +            my echo $channel $line
           67  +        } else {
           68  +            chan close $channel
           69  +            dict unset clients $channel
           70  +        }
           71  +    }
           72  +
           73  +    method echo {channel line} {
           74  +        dict with clients $channel {
           75  +            chan puts $channel \e
           76  +                    [format {[%s:%d] %s} $address $port $line]
           77  +        }
           78  +    }
           79  +}
           80  +.CE
           81  +.SH "SEE ALSO"
           82  +chan(n), fileevent(n), my(n), self(n), socket(n), trace(n)
           83  +.SH KEYWORDS
           84  +callback, object
           85  +.\" Local Variables:
           86  +.\" mode: nroff
           87  +.\" fill-column: 78
           88  +.\" End:

Changes to doc/cd.n.

    37     37   .CS
    38     38   \fBcd\fR ../lib
    39     39   .CE
    40     40   .SH "SEE ALSO"
    41     41   filename(n), glob(n), pwd(n)
    42     42   .SH KEYWORDS
    43     43   working directory
           44  +'\" Local Variables:
           45  +'\" mode: nroff
           46  +'\" fill-column: 78
           47  +'\" End:

Added doc/classvariable.n.

            1  +'\"
            2  +'\" Copyright (c) 2011-2015 Andreas Kupries
            3  +'\" Copyright (c) 2018 Donal K. Fellows
            4  +'\"
            5  +'\" See the file "license.terms" for information on usage and redistribution
            6  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            7  +'\"
            8  +.TH classvariable n 0.3 TclOO "TclOO Commands"
            9  +.so man.macros
           10  +.BS
           11  +'\" Note:  do not modify the .SH NAME line immediately below!
           12  +.SH NAME
           13  +classvariable \- create link from local variable to variable in class
           14  +.SH SYNOPSIS
           15  +.nf
           16  +package require TclOO
           17  +
           18  +\fBclassvariable\fR \fIvariableName\fR ?\fI...\fR?
           19  +.fi
           20  +.BE
           21  +.SH DESCRIPTION
           22  +The \fBclassvariable\fR command is available within methods. It takes a series
           23  +of one or more variable names and makes them available in the method's scope;
           24  +those variable names must not be qualified and must not refer to array
           25  +elements. The originating scope for the variables is the namespace of the
           26  +class that the method was defined by. In other words, the referenced variables
           27  +are shared between all instances of that class.
           28  +.PP
           29  +Note: This command is equivalent to the command \fBtypevariable\fR provided by
           30  +the snit package in tcllib for approximately the same purpose. If used in a
           31  +method defined directly on a class instance (e.g., through the
           32  +\fBoo::objdefine\fR \fBmethod\fR definition) this is very much like just
           33  +using:
           34  +.PP
           35  +.CS
           36  +namespace upvar [namespace current] $var $var
           37  +.CE
           38  +.PP
           39  +for each variable listed to \fBclassvariable\fR.
           40  +.SH EXAMPLE
           41  +This class counts how many instances of it have been made.
           42  +.PP
           43  +.CS
           44  +oo::class create Counted {
           45  +    initialise {
           46  +        variable count 0
           47  +    }
           48  +
           49  +    variable number
           50  +    constructor {} {
           51  +        \fBclassvariable\fR count
           52  +        set number [incr count]
           53  +    }
           54  +
           55  +    method report {} {
           56  +        \fBclassvariable\fR count
           57  +        puts "This is instance $number of $count"
           58  +    }
           59  +}
           60  +
           61  +set a [Counted new]
           62  +set b [Counted new]
           63  +$a report
           64  +        \fI\(-> This is instance 1 of 2\fR
           65  +set c [Counted new]
           66  +$b report
           67  +        \fI\(-> This is instance 2 of 3\fR
           68  +$c report
           69  +        \fI\(-> This is instance 3 of 3\fR
           70  +.CE
           71  +.SH "SEE ALSO"
           72  +global(n), namespace(n), oo::class(n), oo::define(n), upvar(n), variable(n)
           73  +.SH KEYWORDS
           74  +class, class variable, variable
           75  +.\" Local Variables:
           76  +.\" mode: nroff
           77  +.\" fill-column: 78
           78  +.\" End:

Changes to doc/clock.n.

   448    448   If a format string lacks a \fB%z\fR or \fB%Z\fR format group,
   449    449   it is possible for the time to be ambiguous because it appears twice
   450    450   in the same day, once without and once with Daylight Saving Time.
   451    451   If this situation occurs, the first occurrence of the time is chosen.
   452    452   (For this reason, it is wise to have the input string contain the
   453    453   time zone when converting local times.  This caveat does not apply to
   454    454   UTC times.)
          455  +.PP
          456  +If the interpretation of the groups yields an impossible time because
          457  +a field is out of range, enough of that field's unit will be added to
          458  +or subtracted from the time to bring it in range. Thus, if attempting to
          459  +scan or format day 0 of the month, one day will be subtracted from day
          460  +1 of the month, yielding the last day of the previous month.
          461  +.PP
          462  +If the interpretation of the groups yields an impossible time because
          463  +a Daylight Saving Time change skips over that time, or an ambiguous
          464  +time because a Daylight Saving Time change skips back so that the clock
          465  +observes the given time twice, and no time zone specifier (\fB%z\fR
          466  +or \fB%Z\fR) is present in the format, the time is interpreted as
          467  +if the clock had not changed.
   455    468   .SH "FORMAT GROUPS"
   456    469   .PP
   457    470   The following format groups are recognized by the \fBclock scan\fR and
   458    471   \fBclock format\fR commands.
   459    472   .TP
   460    473   \fB%a\fR
   461    474   On output, receives an abbreviation (\fIe.g.,\fR \fBMon\fR) for the day
................................................................................
   869    882   time.  This is useful for determining the time on a specific day or
   870    883   doing other date-relative conversions.
   871    884   .PP
   872    885   The \fIinputString\fR argument consists of zero or more specifications of the
   873    886   following form:
   874    887   .TP
   875    888   \fItime\fR
   876         -A time of day, which is of the form: \fBhh?:mm?:ss?? ?meridian? ?zone?\fR
   877         -or \fBhhmm ?meridian? ?zone?\fR
   878         -If no meridian is specified, \fBhh\fR is interpreted on
          889  +.
          890  +A time of day, which is of the form:
          891  +.QW "\fIhh\fR?\fB:\fImm\fR?\fB:\fIss\fR?? ?\fImeridian\fR? ?\fIzone\fR?"
          892  +or
          893  +.QW "\fBhhmm \fR?\fBmeridian\fR? ?\fBzone\fR?" .
          894  +If no \fImeridian\fR is specified, \fIhh\fR is interpreted on
   879    895   a 24-hour clock.
   880    896   .TP
   881    897   \fIdate\fR
          898  +.
   882    899   A specific month and day with optional year.  The
   883    900   acceptable formats are
   884         -.QW "\fBmm/dd\fR?\fB/yy\fR?" ,
   885         -.QW "\fBmonthname dd\fR?\fB, yy\fR?" ,
   886         -.QW "\fBday, dd monthname \fR?\fByy\fR?" ,
   887         -.QW "\fBdd monthname yy\fR" ,
   888         -.QW "?\fBCC\fR?\fByymmdd\fR" ,
          901  +.QW "\fImm\fB/\fIdd\fR?\fB/\fIyy\fR?" ,
          902  +.QW "\fImonthname dd\fR?\fB, \fIyy\fR?" ,
          903  +.QW "\fIday\fB, \fIdd monthname \fR?\fIyy\fR?" ,
          904  +.QW "\fIdd monthname yy\fR" ,
          905  +.QW "?\fICC\fR?\fIyymmdd\fR" ,
   889    906   and
   890         -.QW "\fBdd-monthname-\fR?\fBCC\fR?\fByy\fR" .
          907  +.QW "\fIdd\fB-\fImonthname\fB-\fR?\fICC\fR?\fIyy\fR" .
   891    908   The default year is the current year.  If the year is less
   892    909   than 100, we treat the years 00-68 as 2000-2068 and the years 69-99
   893    910   as 1969-1999.  Not all platforms can represent the years 38-70, so
   894    911   an error may result if these years are used.
   895    912   .TP
   896    913   \fIISO 8601 point-in-time\fR
          914  +.
   897    915   An ISO 8601 point-in-time specification, such as
   898    916   .QW \fICCyymmdd\fBT\fIhhmmss\fR,
   899    917   where \fBT\fR is the literal
   900    918   .QW T ,
   901    919   .QW "\fICCyymmdd hhmmss\fR" ,
   902    920   or
   903         -.QW \fICCyymmdd\fBT\fIhh:mm:ss\fR .
          921  +.QW \fICCyymmdd\fBT\fIhh\fB:\fImm\fB:\fIss\fR .
   904    922   Note that only these three formats are accepted.
   905    923   The command does \fInot\fR accept the full range of point-in-time
   906    924   specifications specified in ISO8601.  Other formats can be recognized by
   907    925   giving an explicit \fB\-format\fR option to the \fBclock scan\fR command.
   908    926   .TP
   909    927   \fIrelative time\fR
          928  +.
   910    929   A specification relative to the current time.  The format is \fBnumber
   911    930   unit\fR. Acceptable units are \fByear\fR, \fBfortnight\fR,
   912    931   \fBmonth\fR, \fBweek\fR, \fBday\fR,
   913    932   \fBhour\fR, \fBminute\fR (or \fBmin\fR), and \fBsecond\fR (or \fBsec\fR).  The
   914    933   unit can be specified as a singular or plural, as in \fB3 weeks\fR.
   915    934   These modifiers may also be specified:
   916    935   \fBtomorrow\fR, \fByesterday\fR, \fBtoday\fR, \fBnow\fR,

Added doc/cookiejar.n.

            1  +'\"
            2  +'\" Copyright (c) 2014-2018 Donal K. Fellows.
            3  +'\"
            4  +'\" See the file "license.terms" for information on usage and redistribution
            5  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            6  +'\"
            7  +.TH "cookiejar" n 0.1 http "Tcl Bundled Packages"
            8  +.so man.macros
            9  +.BS
           10  +'\" Note:  do not modify the .SH NAME line immediately below!
           11  +.SH NAME
           12  +cookiejar \- Implementation of the Tcl http package cookie jar protocol
           13  +.SH SYNOPSIS
           14  +.nf
           15  +\fBpackage require\fR \fBcookiejar\fR ?\fB0.1\fR?
           16  +
           17  +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR?
           18  +\fB::http::cookiejar create\fR \fIname\fR ?\fIfilename\fR?
           19  +\fB::http::cookiejar new\fR ?\fIfilename\fR?
           20  +
           21  +\fIcookiejar\fR \fBdestroy\fR
           22  +\fIcookiejar\fR \fBforceLoadDomainData\fR
           23  +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR
           24  +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR
           25  +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR?
           26  +.fi
           27  +.SH DESCRIPTION
           28  +.PP
           29  +The cookiejar package provides an implementation of the http package's cookie
           30  +jar protocol using an SQLite database. It provides one main command,
           31  +\fB::http::cookiejar\fR, which is a TclOO class that should be instantiated to
           32  +create a cookie jar that manages a particular HTTP session.
           33  +.PP
           34  +The database management policy can be controlled at the package level by the
           35  +\fBconfigure\fR method on the \fB::http::cookiejar\fR class object:
           36  +.TP
           37  +\fB::http::cookiejar configure\fR ?\fIoptionName\fR? ?\fIoptionValue\fR?
           38  +.
           39  +If neither \fIoptionName\fR nor \fIoptionValue\fR are supplied, this returns a
           40  +copy of the configuration as a Tcl dictionary. If just \fIoptionName\fR is
           41  +supplied, just the value of the named option is returned. If both
           42  +\fIoptionName\fR and \fIoptionValue\fR are given, the named option is changed
           43  +to be the given value.
           44  +.RS
           45  +.PP
           46  +Supported options are:
           47  +.TP
           48  +\fB\-domainfile \fIfilename\fR
           49  +.
           50  +A file (defaulting to within the cookiejar package) with a description of the
           51  +list of top-level domains (e.g., \fB.com\fR or \fB.co.jp\fR). Such domains
           52  +\fImust not\fR accept cookies set upon them. Note that the list of such
           53  +domains is both security-sensitive and \fInot\fR constant and should be
           54  +periodically refetched. Cookie jars maintain their own cache of the domain
           55  +list.
           56  +.TP
           57  +\fB\-domainlist \fIurl\fR
           58  +.
           59  +A URL to fetch the list of top-level domains (e.g., \fB.com\fR or
           60  +\fB.co.jp\fR) from.  Such domains \fImust not\fR accept cookies set upon
           61  +them. Note that the list of such domains is both security-sensitive and
           62  +\fInot\fR constant and should be periodically refetched. Cookie jars maintain
           63  +their own cache of the domain list.
           64  +.TP
           65  +\fB\-domainrefresh \fIintervalMilliseconds\fR
           66  +.
           67  +The number of milliseconds between checks of the \fI\-domainlist\fR for new
           68  +domains.
           69  +.TP
           70  +\fB\-loglevel \fIlevel\fR
           71  +.
           72  +The logging level of this package. The logging level must be (in order of
           73  +decreasing verbosity) one of \fBdebug\fR, \fBinfo\fR, \fBwarn\fR, or
           74  +\fBerror\fR.
           75  +.TP
           76  +\fB\-offline \fIflag\fR
           77  +.
           78  +Allows the cookie managment engine to be placed into offline mode. In offline
           79  +mode, the list of domains is read immediately from the file configured in the
           80  +\fB\-domainfile\fR option, and the \fB\-domainlist\fR option is not used; it
           81  +also makes the \fB\-domainrefresh\fR option be effectively ignored.
           82  +.TP
           83  +\fB\-purgeold \fIintervalMilliseconds\fR
           84  +.
           85  +The number of milliseconds between checks of the database for expired
           86  +cookies; expired cookies are deleted.
           87  +.TP
           88  +\fB\-retain \fIcookieCount\fR
           89  +.
           90  +The maximum number of cookies to retain in the database.
           91  +.TP
           92  +\fB\-vacuumtrigger \fIdeletionCount\fR
           93  +.
           94  +A count of the number of persistent cookie deletions to go between vacuuming
           95  +the database.
           96  +.RE
           97  +.PP
           98  +Cookie jar instances may be made with any of the standard TclOO instance
           99  +creation methods (\fBcreate\fR or \fBnew\fR).
          100  +.TP
          101  +\fB::http::cookiejar new\fR ?\fIfilename\fR?
          102  +.
          103  +If a \fIfilename\fR argument is provided, it is the name of a file containing
          104  +an SQLite database that will contain the persistent cookies maintained by the
          105  +cookie jar; the database will be created if the file does not already
          106  +exist. If \fIfilename\fR is not supplied, the database will be held entirely within
          107  +memory, which effectively forces all cookies within it to be session cookies.
          108  +.SS "INSTANCE METHODS"
          109  +.PP
          110  +The following methods are supported on the instances:
          111  +.TP
          112  +\fIcookiejar\fR \fBdestroy\fR
          113  +.
          114  +This is the standard TclOO destruction method. It does \fInot\fR delete the
          115  +SQLite database if it is written to disk. Callers are responsible for ensuring
          116  +that the cookie jar is not in use by the http package at the time of
          117  +destruction.
          118  +.TP
          119  +\fIcookiejar\fR \fBforceLoadDomainData\fR
          120  +.
          121  +This method causes the cookie jar to immediately load (and cache) the domain
          122  +list data. The domain list will be loaded from the \fB\-domainlist\fR
          123  +configured a the package level if that is enabled, and otherwise will be
          124  +obtained from the \fB\-domainfile\fR configured at the package level.
          125  +.TP
          126  +\fIcookiejar\fR \fBgetCookies\fR \fIprotocol host path\fR
          127  +.
          128  +This method obtains the cookies for a particular HTTP request. \fIThis
          129  +implements the http cookie jar protocol.\fR
          130  +.TP
          131  +\fIcookiejar\fR \fBpolicyAllow\fR \fIoperation domain path\fR
          132  +.
          133  +This method is called by the \fBstoreCookie\fR method to get a decision on
          134  +whether to allow \fIoperation\fR to be performed for the \fIdomain\fR and
          135  +\fIpath\fR. This is checked immediately before the database is updated but
          136  +after the built-in security checks are done, and should return a boolean
          137  +value; if the value is false, the operation is rejected and the database is
          138  +not modified. The supported \fIoperation\fRs are:
          139  +.RS
          140  +.TP
          141  +\fBdelete\fR
          142  +.
          143  +The \fIdomain\fR is seeking to delete a cookie.
          144  +.TP
          145  +\fBsession\fR
          146  +.
          147  +The \fIdomain\fR is seeking to create or update a session cookie.
          148  +.TP
          149  +\fBset\fR
          150  +.
          151  +The \fIdomain\fR is seeking to create or update a persistent cookie (with a
          152  +defined lifetime).
          153  +.PP
          154  +The default implementation of this method just returns true, but subclasses of
          155  +this class may impose their own rules.
          156  +.RE
          157  +.TP
          158  +\fIcookiejar\fR \fBstoreCookie\fR \fIoptions\fR
          159  +.
          160  +This method stores a single cookie from a particular HTTP response. Cookies
          161  +that fail security checks are ignored. \fIThis implements the http cookie jar
          162  +protocol.\fR
          163  +.TP
          164  +\fIcookiejar\fR \fBlookup\fR ?\fIhost\fR? ?\fIkey\fR?
          165  +.
          166  +This method looks a cookie by exact host (or domain) matching. If neither
          167  +\fIhost\fR nor \fIkey\fR are supplied, the list of hosts for which a cookie is
          168  +stored is returned. If just \fIhost\fR (which may be a hostname or a domain
          169  +name) is supplied, the list of cookie keys stored for that host is returned.
          170  +If both \fIhost\fR and \fIkey\fR are supplied, the value for that key is
          171  +returned; it is an error if no such host or key match exactly.
          172  +.SH "EXAMPLES"
          173  +.PP
          174  +The simplest way of using a cookie jar is to just permanently configure it at
          175  +the start of the application.
          176  +.PP
          177  +.CS
          178  +package require http
          179  +\fBpackage require cookiejar\fR
          180  +
          181  +set cookiedb ~/.tclcookies.db
          182  +http::configure -cookiejar [\fBhttp::cookiejar new\fR $cookiedb]
          183  +
          184  +# No further explicit steps are required to use cookies
          185  +set tok [http::geturl http://core.tcl.tk/]
          186  +.CE
          187  +.PP
          188  +To only allow a particular domain to use cookies, perhaps because you only
          189  +want to enable a particular host to create and manipulate sessions, create a
          190  +subclass that imposes that policy.
          191  +.PP
          192  +.CS
          193  +package require http
          194  +\fBpackage require cookiejar\fR
          195  +
          196  +oo::class create MyCookieJar {
          197  +    superclass \fBhttp::cookiejar\fR
          198  +
          199  +    method \fBpolicyAllow\fR {operation domain path} {
          200  +        return [expr {$domain eq "my.example.com"}]
          201  +    }
          202  +}
          203  +
          204  +set cookiedb ~/.tclcookies.db
          205  +http::configure -cookiejar [MyCookieJar new $cookiedb]
          206  +
          207  +# No further explicit steps are required to use cookies
          208  +set tok [http::geturl http://core.tcl.tk/]
          209  +.CE
          210  +.SH "SEE ALSO"
          211  +http(n), oo::class(n), sqlite3(n)
          212  +.SH KEYWORDS
          213  +cookie, internet, security policy, www
          214  +'\" Local Variables:
          215  +'\" mode: nroff
          216  +'\" fill-column: 78
          217  +'\" End:

Changes to doc/coroutine.n.

    10     10   '\" Note:  do not modify the .SH NAME line immediately below!
    11     11   .SH NAME
    12     12   coroutine, yield, yieldto \- Create and produce values from coroutines
    13     13   .SH SYNOPSIS
    14     14   .nf
    15     15   \fBcoroutine \fIname command\fR ?\fIarg...\fR?
    16     16   \fByield\fR ?\fIvalue\fR?
    17         -.VS TIP396
    18     17   \fByieldto\fR \fIcommand\fR ?\fIarg...\fR?
    19     18   \fIname\fR ?\fIvalue...\fR?
    20         -.VE TIP396
           19  +.sp
           20  +.VS "8.7, TIP383"
           21  +\fBcoroinject \fIcoroName command\fR ?\fIarg...\fR?
           22  +\fBcoroprobe \fIcoroName command\fR ?\fIarg...\fR?
           23  +.VE "8.7, TIP383"
    21     24   .fi
    22     25   .BE
    23     26   .SH DESCRIPTION
    24     27   .PP
    25     28   The \fBcoroutine\fR command creates a new coroutine context (with associated
    26     29   command) named \fIname\fR and executes that context by calling \fIcommand\fR,
    27     30   passing in the other remaining arguments without further interpretation. Once
................................................................................
    35     38   of the context can then be resumed by calling the context command, optionally
    36     39   passing in the \fIsingle\fR value to use as the result of the \fByield\fR call
    37     40   that caused
    38     41   the context to be suspended. If the coroutine context never yields and instead
    39     42   returns conventionally, the result of the \fBcoroutine\fR command will be the
    40     43   result of the evaluation of the context.
    41     44   .PP
    42         -.VS TIP396
    43     45   The coroutine may also suspend its execution by use of the \fByieldto\fR
    44     46   command, which instead of returning, cedes execution to some command called
    45     47   \fIcommand\fR (resolved in the context of the coroutine) and to which \fIany
    46     48   number\fR of arguments may be passed. Since every coroutine has a context
    47     49   command, \fByieldto\fR can be used to transfer control directly from one
    48     50   coroutine to another (this is only advisable if the two coroutines are
    49     51   expecting this to happen) but \fIany\fR command may be the target. If a
................................................................................
    54     56   decide what to do with those values.
    55     57   .PP
    56     58   The recommended way of writing a version of \fByield\fR that allows resumption
    57     59   with multiple arguments is by using \fByieldto\fR and the \fBreturn\fR
    58     60   command, like this:
    59     61   .PP
    60     62   .CS
    61         -proc yieldm {value} {
    62         -    \fByieldto\fR return -level 0 $value
           63  +proc yieldMultiple {value} {
           64  +    tailcall \fByieldto\fR string cat $value
    63     65   }
    64     66   .CE
    65         -.VE TIP396
    66     67   .PP
    67     68   The coroutine can also be deleted by destroying the command \fIname\fR, and
    68     69   the name of the current coroutine can be retrieved by using
    69     70   \fBinfo coroutine\fR.
    70     71   If there are deletion traces on variables in the coroutine's
    71     72   implementation, they will fire at the point when the coroutine is explicitly
    72     73   deleted (or, naturally, if the command returns conventionally).
    73     74   .PP
    74     75   At the point when \fIcommand\fR is called, the current namespace will be the
    75     76   global namespace and there will be no stack frames above it (in the sense of
    76     77   \fBupvar\fR and \fBuplevel\fR). However, which command to call will be
    77     78   determined in the namespace that the \fBcoroutine\fR command was called from.
           79  +.PP
           80  +.VS "8.7, TIP383"
           81  +A suspended coroutine (i.e., one that has \fByield\fRed or \fByieldto\fR-d)
           82  +may have its state inspected (or modified) at that point by using
           83  +\fBcoroprobe\fR to run a command at the point where the coroutine is at. The
           84  +command takes the name of the coroutine to run the command in, \fIcoroName\fR,
           85  +and the name of a command (any any arguments it requires) to immediately run
           86  +at that point. The result of that command is the result of the \fBcoroprobe\fR
           87  +command, and the gross state of the coroutine remains the same afterwards
           88  +(i.e., the coroutine is still expecting the results of a \fByield\fR or
           89  +\fByieldto\fR as before) though variables may have been changed.
           90  +.PP
           91  +Similarly, the \fBcoroinject\fR command may be used to place a command to be
           92  +run inside a suspended coroutine (when it is resumed) to process arguments,
           93  +with quite a bit of similarity to \fBcoroprobe\fR. However, with
           94  +\fBcoroinject\fR there are several key differences:
           95  +.VE "8.7, TIP383"
           96  +.IP \(bu
           97  +.VS "8.7, TIP383"
           98  +The coroutine is not immediately resumed after the injection has been done.  A
           99  +consequence of this is that multiple injections may be done before the
          100  +coroutine is resumed. There injected commands are performed in \fIreverse
          101  +order of definition\fR (that is, they are internally stored on a stack).
          102  +.VE "8.7, TIP383"
          103  +.IP \(bu
          104  +.VS "8.7, TIP383"
          105  +An additional two arguments are appended to the list of arguments to be run
          106  +(that is, the \fIcommand\fR and its \fIargs\fR are extended by two elements).
          107  +The first is the name of the command that suspended the coroutine (\fByield\fR
          108  +or \fByieldto\fR), and the second is the argument (or list of arguments, in
          109  +the case of \fByieldto\fR) that is the current resumption value.
          110  +.VE "8.7, TIP383"
          111  +.IP \(bu
          112  +.VS "8.7, TIP383"
          113  +The result of the injected command is used as the result of the \fByield\fR or
          114  +\fByieldto\fR that caused the coroutine to become suspended. Where there are
          115  +multiple injected commands, the result of one becomes the resumption value
          116  +processed by the next.
          117  +.PP
          118  +The injection is a one-off. It is not retained once it has been executed. It
          119  +may \fByield\fR or \fByieldto\fR as part of its execution.
          120  +.PP
          121  +Note that running coroutines may be neither probed nor injected; the
          122  +operations may only be applied to
          123  +.VE "8.7, TIP383"
    78    124   .SH EXAMPLES
    79    125   .PP
    80    126   This example shows a coroutine that will produce an infinite sequence of
    81    127   even values, and a loop that consumes the first ten of them.
    82    128   .PP
    83    129   .CS
    84    130   proc allNumbers {} {
................................................................................
   134    180       }
   135    181   }} allNumbers
   136    182   for {set i 1} {$i <= 20} {incr i} {
   137    183       puts "prime#$i = [\fIeratosthenes\fR]"
   138    184   }
   139    185   .CE
   140    186   .PP
   141         -.VS TIP396
   142    187   This example shows how a value can be passed around a group of three
   143    188   coroutines that yield to each other:
   144    189   .PP
   145    190   .CS
   146    191   proc juggler {name target {value ""}} {
   147    192       if {$value eq ""} {
   148    193           set value [\fByield\fR [info coroutine]]
   149    194       }
   150    195       while {$value ne ""} {
   151    196           puts "$name : $value"
   152    197           set value [string range $value 0 end-1]
   153         -        lassign [\fByieldto\fR $target $value] value
          198  +        lassign [\fByieldto\fR \fI$target\fR $value] value
   154    199       }
   155    200   }
   156    201   \fBcoroutine\fR j1 juggler Larry [
   157    202       \fBcoroutine\fR j2 juggler Curly [
   158    203           \fBcoroutine\fR j3 juggler Moe j1]] "Nyuck!Nyuck!Nyuck!"
   159    204   .CE
   160         -.VE TIP396
          205  +.PP
          206  +.VS "8.7, TIP383"
          207  +This example shows a simple coroutine that collects non-empty values and
          208  +returns a list of them when not given an argument. It also shows how we can
          209  +look inside the coroutine to find out what it is doing, and how we can modify
          210  +the input on a one-off basis.
          211  +.PP
          212  +.CS
          213  +proc collectorImpl {} {
          214  +    set me [info coroutine]
          215  +    set accumulator {}
          216  +    for {set val [\fByield\fR $me]} {$val ne ""} {set val [\fByield\fR]} {
          217  +        lappend accumulator $val
          218  +    }
          219  +    return $accumulator
          220  +}
          221  +
          222  +\fBcoroutine\fR collect collectorImpl
          223  +\fIcollect\fR 123
          224  +\fIcollect\fR "abc def"
          225  +\fIcollect\fR 456
          226  +
          227  +puts [\fBcoroprobe \fIcollect\fR set accumulator]
          228  +# ==> 123 {abc def} 456
          229  +
          230  +\fIcollect\fR "pqr"
          231  +
          232  +\fBcoroinject \fIcollect\fR apply {{type value} {
          233  +    puts "Received '$value' at a $type in [info coroutine]"
          234  +    return [string toupper $value]
          235  +}}
          236  +
          237  +\fIcollect\fR rst
          238  +# ==> Received 'rst' at a yield in ::collect
          239  +\fIcollect\fR xyz
          240  +
          241  +puts [\fIcollect\fR]
          242  +# ==> 123 {abc def} 456 pqr RST xyz
          243  +.CE
          244  +.PP
          245  +This example shows a simple coroutine that collects non-empty values and
          246  +returns a list of them when not given an argument. It also shows how we can
          247  +look inside the coroutine to find out what it is doing.
          248  +.VE "8.7, TIP383"
   161    249   .SS "DETAILED SEMANTICS"
   162    250   .PP
   163    251   This example demonstrates that coroutines start from the global namespace, and
   164    252   that \fIcommand\fR resolution happens before the coroutine stack is created.
   165    253   .PP
   166    254   .CS
   167    255   proc report {where level} {

Changes to doc/define.n.

     1      1   '\"
     2         -'\" Copyright (c) 2007 Donal K. Fellows
            2  +'\" Copyright (c) 2007-2018 Donal K. Fellows
     3      3   '\"
     4      4   '\" See the file "license.terms" for information on usage and redistribution
     5      5   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     6      6   '\"
     7      7   .TH define n 0.3 TclOO "TclOO Commands"
     8      8   .so man.macros
     9      9   .BS
................................................................................
    30     30   configuration of all subclasses of the class and all objects that are
    31     31   instances of that class or which mix it in (as modified by any per-instance
    32     32   configuration). The way in which the configuration is done is controlled by
    33     33   either the \fIdefScript\fR argument or by the \fIsubcommand\fR and following
    34     34   \fIarg\fR arguments; when the second is present, it is exactly as if all the
    35     35   arguments from \fIsubcommand\fR onwards are made into a list and that list is
    36     36   used as the \fIdefScript\fR argument.
    37         -.SS "CONFIGURING CLASSES"
           37  +.PP
           38  +Note that the constructor for \fBoo::class\fR will call \fBoo::define\fR on
           39  +the script argument that it is provided. This is a convenient way to create
           40  +and define a class in one step.
           41  +.SH "CONFIGURING CLASSES"
    38     42   .PP
    39     43   The following commands are supported in the \fIdefScript\fR for
    40     44   \fBoo::define\fR, each of which may also be used in the \fIsubcommand\fR form:
           45  +.TP
           46  +\fBclassmethod\fI name\fR ?\fIargList bodyScrip\fR?
           47  +.VS TIP478
           48  +This creates a class method, or (if \fIargList\fR and \fIbodyScript\fR are
           49  +omitted) promotes an existing method on the class object to be a class
           50  +method. The \fIname\fR, \fIargList\fR and \fIbodyScript\fR arguments are as in
           51  +the \fBmethod\fR definition, below.
           52  +.RS
           53  +.PP
           54  +Class methods can be called on either the class itself or on the instances of
           55  +that class. When they are called, the current object (see the \fBsel\fR and
           56  +\fBmy\fR commands) is the class on which they are called or the class of the
           57  +instance on which they are called, depending on whether they are called on the
           58  +class or an instance of the class, respectively. If called on a subclass or
           59  +instance of the subclass, the current object is the subclass.
           60  +.PP
           61  +In a private definition context, the methods as invoked on classes are
           62  +\fInot\fR private, but the methods as invoked on instances of classes are
           63  +private.
           64  +.RE
           65  +.VE TIP478
    41     66   .TP
    42     67   \fBconstructor\fI argList bodyScript\fR
    43     68   .
    44     69   This creates or updates the constructor for a class. The formal arguments to
    45     70   the constructor (defined using the same format as for the Tcl \fBproc\fR
    46     71   command) will be \fIargList\fR, and the body of the constructor will be
    47     72   \fIbodyScript\fR. When the body of the constructor is evaluated, the current
    48     73   namespace of the constructor will be a namespace that is unique to the object
    49     74   being constructed. Within the constructor, the \fBnext\fR command should be
    50     75   used to call the superclasses' constructors. If \fIbodyScript\fR is the empty
    51     76   string, the constructor will be deleted.
    52         -.TP
    53         -\fBdeletemethod\fI name\fR ?\fIname ...\fR
    54         -.
    55         -This deletes each of the methods called \fIname\fR from a class. The methods
    56         -must have previously existed in that class. Does not affect the superclasses
    57         -of the class, nor does it affect the subclasses or instances of the class
    58         -(except when they have a call chain through the class being modified).
           77  +.RS
           78  +.PP
           79  +Classes do not need to have a constructor defined. If none is specified, the
           80  +superclass's constructor will be used instead.
           81  +.RE
    59     82   .TP
    60     83   \fBdestructor\fI bodyScript\fR
    61     84   .
    62     85   This creates or updates the destructor for a class. Destructors take no
    63     86   arguments, and the body of the destructor will be \fIbodyScript\fR. The
    64     87   destructor is called when objects of the class are deleted, and when called
    65     88   will have the object's unique namespace as the current namespace. Destructors
................................................................................
    76     99   \fBexport\fI name \fR?\fIname ...\fR?
    77    100   .
    78    101   This arranges for each of the named methods, \fIname\fR, to be exported
    79    102   (i.e. usable outside an instance through the instance object's command) by the
    80    103   class being defined. Note that the methods themselves may be actually defined
    81    104   by a superclass; subclass exports override superclass visibility, and may in
    82    105   turn be overridden by instances.
    83         -.TP
    84         -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
    85         -.VS
    86         -This slot (see \fBSLOTTED DEFINITIONS\fR below)
    87         -.VE
    88         -sets or updates the list of method names that are used to guard whether
    89         -method call to instances of the class may be called and what the method's
    90         -results are. Each \fImethodName\fR names a single filtering method (which may
    91         -be exposed or not exposed); it is not an error for a non-existent method to be
    92         -named since they may be defined by subclasses.
    93         -.VS
    94         -By default, this slot works by appending.
    95         -.VE
    96    106   .TP
    97    107   \fBforward\fI name cmdName \fR?\fIarg ...\fR?
    98    108   .
    99    109   This creates or updates a forwarded method called \fIname\fR. The method is
   100    110   defined be forwarded to the command called \fIcmdName\fR, with additional
   101    111   arguments, \fIarg\fR etc., added before those arguments specified by the
   102    112   caller of the method. The \fIcmdName\fR will always be resolved using the
   103    113   rules of the invoking objects' namespaces, i.e., when \fIcmdName\fR is not
   104    114   fully-qualified, the command will be searched for in each object's namespace,
   105    115   using the instances' namespace's path, or by looking in the global namespace.
   106    116   The method will be exported if \fIname\fR starts with a lower-case letter, and
   107    117   non-exported otherwise.
          118  +.RS
          119  +.PP
          120  +.VS TIP500
          121  +If in a private definition context (see the \fBprivate\fR definition command,
          122  +below), this command creates private forwarded methods.
          123  +.VE TIP500
          124  +.RE
   108    125   .TP
   109         -\fBmethod\fI name argList bodyScript\fR
          126  +\fBinitialise\fI script\fR
          127  +.TP
          128  +\fBinitialize\fI script\fR
          129  +.VS TIP478
          130  +This evaluates \fIscript\fR in a context which supports local variables and
          131  +where the current namespace is the instance namespace of the class object
          132  +itself. This is useful for setting up, e.g., class-scoped variables.
          133  +.VE TIP478
          134  +.TP
          135  +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR
   110    136   .
   111    137   This creates or updates a method that is implemented as a procedure-like
   112    138   script. The name of the method is \fIname\fR, the formal arguments to the
   113    139   method (defined using the same format as for the Tcl \fBproc\fR command) will
   114    140   be \fIargList\fR, and the body of the method will be \fIbodyScript\fR. When
   115    141   the body of the method is evaluated, the current namespace of the method will
   116    142   be a namespace that is unique to the current object. The method will be
   117    143   exported if \fIname\fR starts with a lower-case letter, and non-exported
   118    144   otherwise; this behavior can be overridden via \fBexport\fR and
   119         -\fBunexport\fR.
   120         -.TP
   121         -\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
   122         -.VS
   123         -This slot (see \fBSLOTTED DEFINITIONS\fR below)
   124         -.VE
   125         -sets or updates the list of additional classes that are to be mixed into
   126         -all the instances of the class being defined. Each \fIclassName\fR argument
   127         -names a single class that is to be mixed in.
   128         -.VS
   129         -By default, this slot works by replacement.
   130         -.VE
   131         -.TP
   132         -\fBrenamemethod\fI fromName toName\fR
   133         -.
   134         -This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
   135         -method must have previously existed in the class, and \fItoName\fR must not
   136         -previously refer to a method in that class. Does not affect the superclasses
   137         -of the class, nor does it affect the subclasses or instances of the class
   138         -(except when they have a call chain through the class being modified). Does
   139         -not change the export status of the method; if it was exported before, it will
   140         -be afterwards.
          145  +\fBunexport\fR
          146  +.VS  TIP519
          147  +or by specifying \fB\-export\fR, \fB\-private\fR or \fB\-unexport\fR in the
          148  +optional parameter \fIoption\fR.
          149  +.VE TIP519
          150  +.RS
          151  +.PP
          152  +.VS TIP500
          153  +If in a private definition context (see the \fBprivate\fR definition command,
          154  +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command
          155  +creates private procedure-like methods.
          156  +.VE TIP500
          157  +.RE
          158  +.TP
          159  +\fBprivate \fIcmd arg...\fR
          160  +.TP
          161  +\fBprivate \fIscript\fR
          162  +.
          163  +.VS TIP500
          164  +This evaluates the \fIscript\fR (or the list of command and arguments given by
          165  +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
          166  +current class will be private definitions.
          167  +.RS
          168  +.PP
          169  +The following class definition commands are affected by \fBprivate\fR:
          170  +\fBforward\fR, \fBmethod\fR, \fBself\fR, and \fBvariable\fR. Nesting
          171  +\fBprivate\fR inside \fBprivate\fR has no cumulative effect; the innermost
          172  +definition context is just a private definition context. All other definition
          173  +commands have no difference in behavior when used in a private definition
          174  +context.
          175  +.RE
          176  +.VE TIP500
   141    177   .TP
   142    178   \fBself\fI subcommand arg ...\fR
   143    179   .TP
   144    180   \fBself\fI script\fR
   145    181   .TP
   146    182   \fBself\fR
   147    183   .
................................................................................
   155    191   .QW "\fBoo::objdefine \fIcls subcommand ...\fR" .
   156    192   .RS
   157    193   .PP
   158    194   .VS TIP470
   159    195   If no arguments at all are used, this gives the name of the class currently
   160    196   being configured.
   161    197   .VE TIP470
          198  +.VS TIP500
          199  +If in a private definition context (see the \fBprivate\fR definition command,
          200  +below), the definitions on the class object will also be made in a private
          201  +definition context.
          202  +.VE TIP500
   162    203   .RE
   163    204   .TP
   164    205   \fBsuperclass\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
   165         -.VS
          206  +.
   166    207   This slot (see \fBSLOTTED DEFINITIONS\fR below)
   167         -.VE
   168    208   allows the alteration of the superclasses of the class being defined.
   169    209   Each \fIclassName\fR argument names one class that is to be a superclass of
   170    210   the defined class. Note that objects must not be changed from being classes to
   171    211   being non-classes or vice-versa, that an empty parent class is equivalent to
   172    212   \fBoo::object\fR, and that the parent classes of \fBoo::object\fR and
   173    213   \fBoo::class\fR may not be modified.
   174         -.VS
   175    214   By default, this slot works by replacement.
   176         -.VE
   177    215   .TP
   178    216   \fBunexport\fI name \fR?\fIname ...\fR?
   179    217   .
   180    218   This arranges for each of the named methods, \fIname\fR, to be not exported
   181    219   (i.e. not usable outside the instance through the instance object's command,
   182    220   but instead just through the \fBmy\fR command visible in each object's
   183    221   context) by the class being defined. Note that the methods themselves may be
   184    222   actually defined by a superclass; subclass unexports override superclass
   185    223   visibility, and may be overridden by instance unexports.
   186    224   .TP
   187    225   \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
   188         -.VS
          226  +.
   189    227   This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
   190    228   variables to be automatically made
   191    229   available in the methods, constructor and destructor declared by the class
   192    230   being defined. Each variable name must not have any namespace
   193    231   separators and must not look like an array access. All variables will be
   194         -actually present in the instance object on which the method is executed. Note
          232  +actually present in the namespace of the instance object on which the method
          233  +is executed. Note
   195    234   that the variable lists declared by a superclass or subclass are completely
   196    235   disjoint, as are variable lists declared by instances; the list of variable
   197    236   names is just for methods (and constructors and destructors) declared by this
   198    237   class. By default, this slot works by appending.
   199         -.VE
   200         -.SS "CONFIGURING OBJECTS"
          238  +.RS
          239  +.PP
          240  +.VS TIP500
          241  +If in a private definition context (see the \fBprivate\fR definition command,
          242  +below), this slot manipulates the list of private variable bindings for this
          243  +class. In a private variable binding, the name of the variable within the
          244  +instance object is different to the name given in the definition; the name
          245  +used in the definition is the name that you use to access the variable within
          246  +the methods of this class, and the name of the variable in the instance
          247  +namespace has a unique prefix that makes accidental use from other classes
          248  +extremely unlikely.
          249  +.VE TIP500
          250  +.RE
          251  +.SS "ADVANCED CLASS CONFIGURATION OPTIONS"
          252  +.PP
          253  +The following definitions are also supported, but are not required in simple
          254  +programs:
          255  +.TP
          256  +\fBdefinitionnamespace\fR ?\fIkind\fR? \fInamespaceName\fR
          257  +.VS TIP524
          258  +This allows control over what namespace will be used by the \fBoo::define\fR
          259  +and \fBoo::objdefine\fR commands to look up the definition commands they
          260  +use. When any object has a definition operation applied to it, \fIthe class that
          261  +it is an instance of\fR (and its superclasses and mixins) is consulted for
          262  +what definition namespace to use. \fBoo::define\fR gets the class definition
          263  +namespace, and \fB::oo::objdefine\fR gets the instance definition namespace,
          264  +but both otherwise use the identical lookup operation.
          265  +.RS
          266  +.PP
          267  +This sets the definition namespace of kind \fIkind\fR provided by the current
          268  +class to \fInamespaceName\fR. The \fInamespaceName\fR must refer to a
          269  +currently existing namespace, or must be the empty string (to stop the current
          270  +class from having such a namespace connected). The \fIkind\fR, if supplied,
          271  +must be either \fB\-class\fR (the default) or \fB\-instance\fR to specify the
          272  +whether the namespace for use with \fBoo::define\fR or \fBoo::objdefine\fR
          273  +respectively is being set.
          274  +.PP
          275  +The class \fBoo::object\fR has its instance namespace locked to
          276  +\fB::oo::objdefine\fR, and the class \fBoo::class\fR has its class namespace
          277  +locked to \fB::oo::define\fR. A consequence of this is that effective use of
          278  +this feature for classes requires the definition of a metaclass.
          279  +.RE
          280  +.VE TIP524
          281  +.TP
          282  +\fBdeletemethod\fI name\fR ?\fIname ...\fR?
          283  +.
          284  +This deletes each of the methods called \fIname\fR from a class. The methods
          285  +must have previously existed in that class. Does not affect the superclasses
          286  +of the class, nor does it affect the subclasses or instances of the class
          287  +(except when they have a call chain through the class being modified) or the
          288  +class object itself.
          289  +.TP
          290  +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
          291  +.
          292  +This slot (see \fBSLOTTED DEFINITIONS\fR below)
          293  +sets or updates the list of method names that are used to guard whether
          294  +method call to instances of the class may be called and what the method's
          295  +results are. Each \fImethodName\fR names a single filtering method (which may
          296  +be exposed or not exposed); it is not an error for a non-existent method to be
          297  +named since they may be defined by subclasses.
          298  +By default, this slot works by appending.
          299  +.TP
          300  +\fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
          301  +.
          302  +This slot (see \fBSLOTTED DEFINITIONS\fR below)
          303  +sets or updates the list of additional classes that are to be mixed into
          304  +all the instances of the class being defined. Each \fIclassName\fR argument
          305  +names a single class that is to be mixed in.
          306  +By default, this slot works by replacement.
          307  +.TP
          308  +\fBrenamemethod\fI fromName toName\fR
          309  +.
          310  +This renames the method called \fIfromName\fR in a class to \fItoName\fR. The
          311  +method must have previously existed in the class, and \fItoName\fR must not
          312  +previously refer to a method in that class. Does not affect the superclasses
          313  +of the class, nor does it affect the subclasses or instances of the class
          314  +(except when they have a call chain through the class being modified), or the
          315  +class object itself. Does
          316  +not change the export status of the method; if it was exported before, it will
          317  +be afterwards.
          318  +.SH "CONFIGURING OBJECTS"
   201    319   .PP
   202    320   The following commands are supported in the \fIdefScript\fR for
   203    321   \fBoo::objdefine\fR, each of which may also be used in the \fIsubcommand\fR
   204    322   form:
   205    323   .TP
   206         -\fBclass\fI className\fR
   207         -.
   208         -This allows the class of an object to be changed after creation. Note that the
   209         -class's constructors are not called when this is done, and so the object may
   210         -well be in an inconsistent state unless additional configuration work is done.
   211         -.TP
   212         -\fBdeletemethod\fI name\fR ?\fIname ...\fR
   213         -.
   214         -This deletes each of the methods called \fIname\fR from an object. The methods
   215         -must have previously existed in that object. Does not affect the classes that
   216         -the object is an instance of.
   217         -.TP
   218    324   \fBexport\fI name \fR?\fIname ...\fR?
   219    325   .
   220    326   This arranges for each of the named methods, \fIname\fR, to be exported
   221    327   (i.e. usable outside the object through the object's command) by the object
   222    328   being defined. Note that the methods themselves may be actually defined by a
   223    329   class or superclass; object exports override class visibility.
   224         -.TP
   225         -\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
   226         -.VS
   227         -This slot (see \fBSLOTTED DEFINITIONS\fR below)
   228         -.VE
   229         -sets or updates the list of method names that are used to guard whether a
   230         -method call to the object may be called and what the method's results are.
   231         -Each \fImethodName\fR names a single filtering method (which may be exposed or
   232         -not exposed); it is not an error for a non-existent method to be named. Note
   233         -that the actual list of filters also depends on the filters set upon any
   234         -classes that the object is an instance of.
   235         -.VS
   236         -By default, this slot works by appending.
   237         -.VE
   238    330   .TP
   239    331   \fBforward\fI name cmdName \fR?\fIarg ...\fR?
   240    332   .
   241    333   This creates or updates a forwarded object method called \fIname\fR. The
   242    334   method is defined be forwarded to the command called \fIcmdName\fR, with
   243    335   additional arguments, \fIarg\fR etc., added before those arguments specified
   244    336   by the caller of the method. Forwarded methods should be deleted using the
   245    337   \fBmethod\fR subcommand. The method will be exported if \fIname\fR starts with
   246    338   a lower-case letter, and non-exported otherwise.
          339  +.RS
          340  +.PP
          341  +.VS TIP500
          342  +If in a private definition context (see the \fBprivate\fR definition command,
          343  +below), this command creates private forwarded methods.
          344  +.VE TIP500
          345  +.RE
   247    346   .TP
   248         -\fBmethod\fI name argList bodyScript\fR
          347  +\fBmethod\fI name \fR?\fIoption\fR? \fIargList bodyScript\fR
   249    348   .
   250    349   This creates, updates or deletes an object method. The name of the method is
   251    350   \fIname\fR, the formal arguments to the method (defined using the same format
   252    351   as for the Tcl \fBproc\fR command) will be \fIargList\fR, and the body of the
   253    352   method will be \fIbodyScript\fR. When the body of the method is evaluated, the
   254    353   current namespace of the method will be a namespace that is unique to the
   255    354   object. The method will be exported if \fIname\fR starts with a lower-case
   256         -letter, and non-exported otherwise.
          355  +letter, and non-exported otherwise;
          356  +.VS  TIP519
          357  +this can be overridden by specifying \fB\-export\fR, \fB\-private\fR or
          358  +\fB\-unexport\fR in the optional parameter \fIoption\fR, or via the
          359  +\fBexport\fR and \fBunexport\fR definitions.
          360  +.VE TIP519
          361  +.RS
          362  +.PP
          363  +.VS TIP500
          364  +If in a private definition context (see the \fBprivate\fR definition command,
          365  +below) or if the \fB\-private\fR flag is given for \fIoption\fR, this command
          366  +creates private procedure-like methods.
          367  +.VE TIP500
          368  +.RE
   257    369   .TP
   258    370   \fBmixin\fR ?\fI\-slotOperation\fR? ?\fIclassName ...\fR?
   259         -.VS
          371  +.
   260    372   This slot (see \fBSLOTTED DEFINITIONS\fR below)
   261         -.VE
   262    373   sets or updates a per-object list of additional classes that are to be
   263    374   mixed into the object. Each argument, \fIclassName\fR, names a single class
   264    375   that is to be mixed in.
   265         -.VS
   266    376   By default, this slot works by replacement.
   267         -.VE
   268    377   .TP
   269         -\fBrenamemethod\fI fromName toName\fR
   270         -.
   271         -This renames the method called \fIfromName\fR in an object to \fItoName\fR.
   272         -The method must have previously existed in the object, and \fItoName\fR must
   273         -not previously refer to a method in that object. Does not affect the classes
   274         -that the object is an instance of. Does not change the export status of the
   275         -method; if it was exported before, it will be afterwards.
          378  +\fBprivate \fIcmd arg...\fR
   276    379   .TP
   277         -\fBself \fR
   278         -.
   279         -.VS TIP470
   280         -This gives the name of the object currently being configured.
   281         -.VE TIP470
          380  +\fBprivate \fIscript\fR
          381  +.VS TIP500
          382  +This evaluates the \fIscript\fR (or the list of command and arguments given by
          383  +\fIcmd\fR and \fIarg\fRs) in a context where the definitions made on the
          384  +current object will be private definitions.
          385  +.RS
          386  +.PP
          387  +The following class definition commands are affected by \fBprivate\fR:
          388  +\fBforward\fR, \fBmethod\fR, and \fBvariable\fR. Nesting \fBprivate\fR inside
          389  +\fBprivate\fR has no cumulative effect; the innermost definition context is
          390  +just a private definition context. All other definition commands have no
          391  +difference in behavior when used in a private definition context.
          392  +.RE
          393  +.VE TIP500
   282    394   .TP
   283    395   \fBunexport\fI name \fR?\fIname ...\fR?
   284    396   .
   285    397   This arranges for each of the named methods, \fIname\fR, to be not exported
   286    398   (i.e. not usable outside the object through the object's command, but instead
   287    399   just through the \fBmy\fR command visible in the object's context) by the
   288    400   object being defined. Note that the methods themselves may be actually defined
   289    401   by a class; instance unexports override class visibility.
   290    402   .TP
   291    403   \fBvariable\fR ?\fI\-slotOperation\fR? ?\fIname ...\fR?
   292         -.VS
          404  +.
   293    405   This slot (see \fBSLOTTED DEFINITIONS\fR below) arranges for each of the named
   294    406   variables to be automatically made available in the methods declared by the
   295    407   object being defined.  Each variable name must not have any namespace
   296    408   separators and must not look like an array access. All variables will be
   297         -actually present in the object on which the method is executed. Note that the
          409  +actually present in the namespace of the object on which the method is
          410  +executed. Note that the
   298    411   variable lists declared by the classes and mixins of which the object is an
   299    412   instance are completely disjoint; the list of variable names is just for
   300    413   methods declared by this object. By default, this slot works by appending.
          414  +.RS
          415  +.PP
          416  +.VS TIP500
          417  +If in a private definition context (see the \fBprivate\fR definition command,
          418  +below), this slot manipulates the list of private variable bindings for this
          419  +object.  In a private variable binding, the name of the variable within the
          420  +instance object is different to the name given in the definition; the name
          421  +used in the definition is the name that you use to access the variable within
          422  +the methods of this instance object, and the name of the variable in the
          423  +instance namespace has a unique prefix that makes accidental use from
          424  +superclass methods extremely unlikely.
          425  +.VE TIP500
          426  +.RE
          427  +.SS "ADVANCED OBJECT CONFIGURATION OPTIONS"
          428  +.PP
          429  +The following definitions are also supported, but are not required in simple
          430  +programs:
          431  +.TP
          432  +\fBclass\fI className\fR
          433  +.
          434  +This allows the class of an object to be changed after creation. Note that the
          435  +class's constructors are not called when this is done, and so the object may
          436  +well be in an inconsistent state unless additional configuration work is done.
          437  +.TP
          438  +\fBdeletemethod\fI name\fR ?\fIname ...\fR
          439  +.
          440  +This deletes each of the methods called \fIname\fR from an object. The methods
          441  +must have previously existed in that object (e.g., because it was created
          442  +through \fBoo::objdefine method\fR). Does not affect the classes that the
          443  +object is an instance of, or remove the exposure of those class-provided
          444  +methods in the instance of that class.
          445  +.TP
          446  +\fBfilter\fR ?\fI\-slotOperation\fR? ?\fImethodName ...\fR?
          447  +.
          448  +This slot (see \fBSLOTTED DEFINITIONS\fR below)
          449  +sets or updates the list of method names that are used to guard whether a
          450  +method call to the object may be called and what the method's results are.
          451  +Each \fImethodName\fR names a single filtering method (which may be exposed or
          452  +not exposed); it is not an error for a non-existent method to be named. Note
          453  +that the actual list of filters also depends on the filters set upon any
          454  +classes that the object is an instance of.
          455  +By default, this slot works by appending.
          456  +.TP
          457  +\fBrenamemethod\fI fromName toName\fR
          458  +.
          459  +This renames the method called \fIfromName\fR in an object to \fItoName\fR.
          460  +The method must have previously existed in the object, and \fItoName\fR must
          461  +not previously refer to a method in that object. Does not affect the classes
          462  +that the object is an instance of and cannot rename in an instance object the
          463  +methods provided by those classes (though a \fBoo::objdefine forward\fRed
          464  +method may provide an equivalent capability). Does not change the export
          465  +status of the method; if it was exported before, it will be afterwards.
          466  +.TP
          467  +\fBself \fR
          468  +.VS TIP470
          469  +This gives the name of the object currently being configured.
          470  +.VE TIP470
          471  +.SH "PRIVATE METHODS"
          472  +.VS TIP500
          473  +When a class or instance has a private method, that private method can only be
          474  +invoked from within methods of that class or instance. Other callers of the
          475  +object's methods \fIcannot\fR invoke private methods, it is as if the private
          476  +methods do not exist. However, a private method of a class \fIcan\fR be
          477  +invoked from the class's methods when those methods are being used on another
          478  +instance object; this means that a class can use them to coordinate behaviour
          479  +between several instances of itself without interfering with how other
          480  +classes (especially either subclasses or superclasses) interact. Private
          481  +methods precede all mixed in classes in the method call order (as reported by
          482  +\fBself call\fR).
          483  +.VE TIP500
   301    484   .SH "SLOTTED DEFINITIONS"
   302    485   Some of the configurable definitions of a class or object are \fIslotted
   303    486   definitions\fR. This means that the configuration is implemented by a slot
   304    487   object, that is an instance of the class \fBoo::Slot\fR, which manages a list
   305    488   of values (class names, variable names, etc.) that comprises the contents of
   306         -the slot. The class defines three operations (as methods) that may be done on
          489  +the slot. The class defines five operations (as methods) that may be done on
   307    490   the slot:
   308         -.VE
   309    491   .TP
   310    492   \fIslot\fR \fB\-append\fR ?\fImember ...\fR?
   311         -.VS
          493  +.
   312    494   This appends the given \fImember\fR elements to the slot definition.
   313         -.VE
   314    495   .TP
   315    496   \fIslot\fR \fB\-clear\fR
   316         -.VS
          497  +.
   317    498   This sets the slot definition to the empty list.
   318         -.VE
          499  +.TP
          500  +\fIslot\fR \fB\-prepend\fR ?\fImember ...\fR?
          501  +.VS TIP516
          502  +This prepends the given \fImember\fR elements to the slot definition.
          503  +.VE TIP516
          504  +.TP
          505  +\fIslot\fR \fB\-remove\fR ?\fImember ...\fR?
          506  +.VS TIP516
          507  +This removes the given \fImember\fR elements from the slot definition.
          508  +.VE TIP516
   319    509   .TP
   320    510   \fIslot\fR \fB\-set\fR ?\fImember ...\fR?
   321         -.VS
          511  +.
   322    512   This replaces the slot definition with the given \fImember\fR elements.
   323    513   .PP
   324    514   A consequence of this is that any use of a slot's default operation where the
   325    515   first member argument begins with a hyphen will be an error. One of the above
   326    516   operations should be used explicitly in those circumstances.
   327    517   .SS "SLOT IMPLEMENTATION"
   328    518   Internally, slot objects also define a method \fB\-\-default\-operation\fR
   329    519   which is forwarded to the default operation of the slot (thus, for the class
   330    520   .QW \fBvariable\fR
   331    521   slot, this is forwarded to
   332    522   .QW "\fBmy \-append\fR" ),
   333    523   and these methods which provide the implementation interface:
   334         -.VE
   335    524   .TP
   336    525   \fIslot\fR \fBGet\fR
   337         -.VS
   338         -Returns a list that is the current contents of the slot. This method must
   339         -always be called from a stack frame created by a call to \fBoo::define\fR or
   340         -\fBoo::objdefine\fR.
   341         -.VE
          526  +.
          527  +Returns a list that is the current contents of the slot, but does not modify
          528  +the slot. This method must always be called from a stack frame created by a
          529  +call to \fBoo::define\fR or \fBoo::objdefine\fR. This method \fIshould not\fR
          530  +return an error unless it is called from outside a definition context or with
          531  +the wrong number of arguments.
          532  +.RS
          533  +.PP
          534  +.VS TIP516
          535  +The elements of the list should be fully resolved, if that is a meaningful
          536  +concept to the slot.
          537  +.VE TIP516
          538  +.RE
          539  +.TP
          540  +\fIslot\fR \fBResolve\fR \fIslotElement\fR
          541  +.VS TIP516
          542  +Returns \fIslotElement\fR with a resolution operation applied to it, but does
          543  +not modify the slot. For slots of simple strings, this is an operation that
          544  +does nothing, whereas for slots of classes, this maps a class name to its
          545  +fully-qualified class name.  This method must always be called from a stack
          546  +frame created by a call to \fBoo::define\fR or \fBoo::objdefine\fR.  This
          547  +method \fIshould not\fR return an error unless it is called from outside a
          548  +definition context or with the wrong number of arguments; unresolvable
          549  +arguments should be returned as is (as not all slot operations strictly
          550  +require that values are resolvable to work).
          551  +.RS
          552  +.PP
          553  +Implementations \fIshould not\fR enforce uniqueness and ordering constraints
          554  +in this method; that is the responsibility of the \fBSet\fR method.
          555  +.RE
          556  +.VE TIP516
   342    557   .TP
   343    558   \fIslot\fR \fBSet \fIelementList\fR
   344         -.VS
          559  +.
   345    560   Sets the contents of the slot to the list \fIelementList\fR and returns the
   346    561   empty string. This method must always be called from a stack frame created by
   347         -a call to \fBoo::define\fR or \fBoo::objdefine\fR.
          562  +a call to \fBoo::define\fR or \fBoo::objdefine\fR. This method may return an
          563  +error if it rejects the change to the slot contents (e.g., because of invalid
          564  +values) as well as if it is called from outside a definition context or with
          565  +the wrong number of arguments.
          566  +.RS
          567  +.PP
          568  +This method \fImay\fR reorder and filter the elements if this is necessary in
          569  +order to satisfy the underlying constraints of the slot. (For example, slots
          570  +of classes enforce a uniqueness constraint that places each element in the
          571  +earliest location in the slot that it can.)
          572  +.RE
   348    573   .PP
   349    574   The implementation of these methods is slot-dependent (and responsible for
   350    575   accessing the correct part of the class or object definition). Slots also have
   351    576   an unknown method handler to tie all these pieces together, and they hide
   352    577   their \fBdestroy\fR method so that it is not invoked inadvertently. It is
   353    578   \fIrecommended\fR that any user changes to the slot mechanism be restricted to
   354    579   defining new operations whose names start with a hyphen.
   355         -.VE
          580  +.PP
          581  +.VS TIP516
          582  +Most slot operations will initially \fBResolve\fR their argument list, combine
          583  +it with the results of the \fBGet\fR method, and then \fBSet\fR the result.
          584  +Some operations omit one or both of the first two steps; omitting the third
          585  +would result in an idempotent read-only operation (but the standard mechanism
          586  +for reading from slots is via \fBinfo class\fR and \fBinfo object\fR).
          587  +.VE TIP516
   356    588   .SH EXAMPLES
   357    589   This example demonstrates how to use both forms of the \fBoo::define\fR and
   358    590   \fBoo::objdefine\fR commands (they work in the same way), as well as
   359         -illustrating four of the subcommands of them.
          591  +illustrating four of their subcommands.
   360    592   .PP
   361    593   .CS
   362    594   oo::class create c
   363    595   c create o
   364    596   \fBoo::define\fR c \fBmethod\fR foo {} {
   365    597       puts "world"
   366    598   }
................................................................................
   405    637   }
   406    638   \fBoo::objdefine\fR inst {
   407    639       \fBmixin -append\fR B
   408    640   }
   409    641   inst m1              \fI\(-> prints "red brick"\fR
   410    642   inst m2              \fI\(-> prints "blue brick"\fR
   411    643   .CE
          644  +.PP
          645  +.VS TIP478
          646  +This example shows how to create and use class variables. It is a class that
          647  +counts how many instances of itself have been made.
          648  +.PP
          649  +.CS
          650  +oo::class create Counted
          651  +\fBoo::define\fR Counted {
          652  +    \fBinitialise\fR {
          653  +        variable count 0
          654  +    }
          655  +
          656  +    \fBvariable\fR number
          657  +    \fBconstructor\fR {} {
          658  +        classvariable count
          659  +        set number [incr count]
          660  +    }
          661  +
          662  +    \fBmethod\fR report {} {
          663  +        classvariable count
          664  +        puts "This is instance $number of $count"
          665  +    }
          666  +}
          667  +
          668  +set a [Counted new]
          669  +set b [Counted new]
          670  +$a report
          671  +        \fI\(-> This is instance 1 of 2\fR
          672  +set c [Counted new]
          673  +$b report
          674  +        \fI\(-> This is instance 2 of 3\fR
          675  +$c report
          676  +        \fI\(-> This is instance 3 of 3\fR
          677  +.CE
          678  +.PP
          679  +This example demonstrates how to use class methods. (Note that the constructor
          680  +for \fBoo::class\fR calls \fBoo::define\fR on the class.)
          681  +.PP
          682  +.CS
          683  +oo::class create DBTable {
          684  +    \fBclassmethod\fR find {description} {
          685  +        puts "DB: locate row from [self] matching $description"
          686  +        return [my new]
          687  +    }
          688  +    \fBclassmethod\fR insert {description} {
          689  +        puts "DB: create row in [self] matching $description"
          690  +        return [my new]
          691  +    }
          692  +    \fBmethod\fR update {description} {
          693  +        puts "DB: update row [self] with $description"
          694  +    }
          695  +    \fBmethod\fR delete {} {
          696  +        puts "DB: delete row [self]"
          697  +        my destroy; # Just delete the object, not the DB row
          698  +    }
          699  +}
          700  +
          701  +oo::class create Users {
          702  +    \fBsuperclass\fR DBTable
          703  +}
          704  +oo::class create Groups {
          705  +    \fBsuperclass\fR DBTable
          706  +}
          707  +
          708  +set u1 [Users insert "username=abc"]
          709  +        \fI\(-> DB: create row from ::Users matching username=abc\fR
          710  +set u2 [Users insert "username=def"]
          711  +        \fI\(-> DB: create row from ::Users matching username=def\fR
          712  +$u2 update "group=NULL"
          713  +        \fI\(-> DB: update row ::oo::Obj124 with group=NULL\fR
          714  +$u1 delete
          715  +        \fI\(-> DB: delete row ::oo::Obj123\fR
          716  +set g [Group find "groupname=webadmins"]
          717  +        \fI\(-> DB: locate row ::Group with groupname=webadmins\fR
          718  +$g update "emailaddress=admins"
          719  +        \fI\(-> DB: update row ::oo::Obj125 with emailaddress=admins\fR
          720  +.CE
          721  +.VE TIP478
          722  +.PP
          723  +.VS TIP524
          724  +This example shows how to make a custom definition for a class. Note that it
          725  +explicitly includes delegation to the existing definition commands via
          726  +\fBnamespace path\fR.
          727  +.PP
          728  +.CS
          729  +namespace eval myDefinitions {
          730  +    # Delegate to existing definitions where not overridden
          731  +    namespace path \fB::oo::define\fR
          732  +
          733  +    # A custom type of method
          734  +    proc exprmethod {name arguments body} {
          735  +        tailcall \fBmethod\fR $name $arguments [list expr $body]
          736  +    }
          737  +
          738  +    # A custom way of building a constructor
          739  +    proc parameters args {
          740  +        uplevel 1 [list \fBvariable\fR {*}$args]
          741  +        set body [join [lmap a $args {
          742  +            string map [list VAR $a] {
          743  +                set [my varname VAR] [expr {double($VAR)}]
          744  +            }
          745  +        }] ";"]
          746  +        tailcall \fBconstructor\fR $args $body
          747  +    }
          748  +}
          749  +
          750  +# Bind the namespace into a (very simple) metaclass for use
          751  +oo::class create exprclass {
          752  +    \fBsuperclass\fR oo::class
          753  +    \fBdefinitionnamespace\fR myDefinitions
          754  +}
          755  +
          756  +# Use the custom definitions
          757  +exprclass create quadratic {
          758  +    parameters a b c
          759  +    exprmethod evaluate {x} {
          760  +        ($a * $x**2) + ($b * $x) + $c
          761  +    }
          762  +}
          763  +
          764  +# Showing the resulting class and object in action
          765  +quadratic create quad 1 2 3
          766  +for {set x 0} {$x <= 4} {incr x} {
          767  +    puts [format "quad(%d) = %.2f" $x [quad evaluate $x]]
          768  +}
          769  +        \fI\(-> quad(0) = 3.00\fR
          770  +        \fI\(-> quad(1) = 6.00\fR
          771  +        \fI\(-> quad(2) = 11.00\fR
          772  +        \fI\(-> quad(3) = 18.00\fR
          773  +        \fI\(-> quad(4) = 27.00\fR
          774  +.CE
          775  +.VE TIP524
   412    776   .SH "SEE ALSO"
   413    777   next(n), oo::class(n), oo::object(n)
   414    778   .SH KEYWORDS
   415    779   class, definition, method, object, slot
   416    780   .\" Local variables:
   417    781   .\" mode: nroff
   418    782   .\" fill-column: 78
   419    783   .\" End:

Changes to doc/dict.n.

    23     23   \fBdict append \fIdictionaryVariable key \fR?\fIstring ...\fR?
    24     24   .
    25     25   This appends the given string (or strings) to the value that the given
    26     26   key maps to in the dictionary value contained in the given variable,
    27     27   writing the resulting dictionary value back to that variable.
    28     28   Non-existent keys are treated as if they map to an empty string. The
    29     29   updated dictionary value is returned.
           30  +.VS TIP508
           31  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
           32  +array that has a default value set, the default value and will be used as the
           33  +value of the dictionary prior to the appending operation.
           34  +.VE TIP508
    30     35   .TP
    31     36   \fBdict create \fR?\fIkey value ...\fR?
    32     37   .
    33     38   Return a new dictionary that contains each of the key/value mappings
    34     39   listed as arguments (keys and values alternating, with each key being
    35     40   followed by its associated value.)
    36     41   .TP
................................................................................
   110    115   elements in a manner similar to \fBarray get\fR. That is, the first
   111    116   element of each pair would be the key and the second element would be
   112    117   the value for that key.
   113    118   .PP
   114    119   It is an error to attempt to retrieve a value for a key that is not
   115    120   present in the dictionary.
   116    121   .RE
          122  +.TP
          123  +\fBdict getdef \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR
          124  +.TP
          125  +\fBdict getwithdefault \fIdictionaryValue \fR?\fIkey ...\fR? \fIkey default\fR
          126  +.VS "8.7, TIP342"
          127  +This behaves the same as \fBdict get\fR (with at least one \fIkey\fR
          128  +argument), returning the value that the key path maps to in the
          129  +dictionary \fIdictionaryValue\fR, except that instead of producing an
          130  +error because the \fIkey\fR (or one of the \fIkey\fRs on the key path)
          131  +is absent, it returns the \fIdefault\fR argument instead.
          132  +.RS
          133  +.PP
          134  +Note that there must always be at least one \fIkey\fR provided, and that
          135  +\fBdict getdef\fR and \fBdict getwithdefault\fR are aliases for each other.
          136  +.RE
          137  +.VE "8.7, TIP342"
   117    138   .TP
   118    139   \fBdict incr \fIdictionaryVariable key \fR?\fIincrement\fR?
   119    140   .
   120    141   This adds the given increment value (an integer that defaults to 1 if
   121    142   not specified) to the value that the given key maps to in the
   122    143   dictionary value contained in the given variable, writing the
   123    144   resulting dictionary value back to that variable. Non-existent keys
   124    145   are treated as if they map to 0. It is an error to increment a value
   125    146   for an existing key if that value is not an integer. The updated
   126    147   dictionary value is returned.
          148  +.VS TIP508
          149  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          150  +array that has a default value set, the default value and will be used as the
          151  +value of the dictionary prior to the incrementing operation.
          152  +.VE TIP508
   127    153   .TP
   128    154   \fBdict info \fIdictionaryValue\fR
   129    155   .
   130    156   This returns information (intended for display to people) about the
   131    157   given dictionary though the format of this data is dependent on the
   132    158   implementation of the dictionary. For dictionaries that are
   133    159   implemented by hash tables, it is expected that this will return the
................................................................................
   145    171   This appends the given items to the list value that the given key maps
   146    172   to in the dictionary value contained in the given variable, writing
   147    173   the resulting dictionary value back to that variable. Non-existent
   148    174   keys are treated as if they map to an empty list, and it is legal for
   149    175   there to be no items to append to the list. It is an error for the
   150    176   value that the key maps to to not be representable as a list. The
   151    177   updated dictionary value is returned.
          178  +.VS TIP508
          179  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          180  +array that has a default value set, the default value and will be used as the
          181  +value of the dictionary prior to the list-appending operation.
          182  +.VE TIP508
   152    183   .TP
   153    184   \fBdict map \fR{\fIkeyVariable valueVariable\fR} \fIdictionaryValue body\fR
   154    185   .
   155    186   This command applies a transformation to each element of a dictionary,
   156    187   returning a new dictionary. It takes three arguments: the first is a
   157    188   two-element list of variable names (for the key and value respectively of each
   158    189   mapping in the dictionary), the second the dictionary value to iterate across,
................................................................................
   202    233   \fBdict set \fIdictionaryVariable key \fR?\fIkey ...\fR? \fIvalue\fR
   203    234   .
   204    235   This operation takes the name of a variable containing a dictionary
   205    236   value and places an updated dictionary value in that variable
   206    237   containing a mapping from the given key to the given value. When
   207    238   multiple keys are present, this operation creates or updates a chain
   208    239   of nested dictionaries. The updated dictionary value is returned.
          240  +.VS TIP508
          241  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          242  +array that has a default value set, the default value and will be used as the
          243  +value of the dictionary prior to the value insert/update operation.
          244  +.VE TIP508
   209    245   .TP
   210    246   \fBdict size \fIdictionaryValue\fR
   211    247   .
   212    248   Return the number of key/value mappings in the given dictionary value.
   213    249   .TP
   214    250   \fBdict unset \fIdictionaryVariable key \fR?\fIkey ...\fR?
   215    251   .
................................................................................
   217    253   variable containing a dictionary value and places an updated
   218    254   dictionary value in that variable that does not contain a mapping for
   219    255   the given key. Where multiple keys are present, this describes a path
   220    256   through nested dictionaries to the mapping to remove. At least one key
   221    257   must be specified, but the last key on the key-path need not exist.
   222    258   All other components on the path must exist. The updated dictionary
   223    259   value is returned.
          260  +.VS TIP508
          261  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          262  +array that has a default value set, the default value and will be used as the
          263  +value of the dictionary prior to the value remove operation.
          264  +.VE TIP508
   224    265   .TP
   225    266   \fBdict update \fIdictionaryVariable key varName \fR?\fIkey varName ...\fR? \fIbody\fR
   226    267   .
   227    268   Execute the Tcl script in \fIbody\fR with the value for each \fIkey\fR
   228    269   (as found by reading the dictionary value in \fIdictionaryVariable\fR)
   229    270   mapped to the variable \fIvarName\fR. There may be multiple
   230    271   \fIkey\fR/\fIvarName\fR pairs. If a \fIkey\fR does not have a mapping,
................................................................................
   232    273   terminates, any changes made to the \fIvarName\fRs is reflected back
   233    274   to the dictionary within \fIdictionaryVariable\fR (unless
   234    275   \fIdictionaryVariable\fR itself becomes unreadable, when all updates
   235    276   are silently discarded), even if the result of \fIbody\fR is an error
   236    277   or some other kind of exceptional exit. The result of \fBdict
   237    278   update\fR is (unless some kind of error occurs) the result of the
   238    279   evaluation of \fIbody\fR.
          280  +.VS TIP508
          281  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          282  +array that has a default value set, the default value and will be used as the
          283  +value of the dictionary prior to the update operation.
          284  +.VE TIP508
   239    285   .RS
   240    286   .PP
   241    287   Each \fIvarName\fR is mapped in the scope enclosing the \fBdict update\fR;
   242    288   it is recommended that this command only be used in a local scope
   243    289   (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
   244    290   this, the variables set by \fBdict update\fR will continue to
   245    291   exist after the command finishes (unless explicitly \fBunset\fR).
................................................................................
   266    312   for the execution of \fIbody\fR. As with \fBdict update\fR, making
   267    313   \fIdictionaryVariable\fR unreadable will make the updates to the
   268    314   dictionary be discarded, and this also happens if the contents of
   269    315   \fIdictionaryVariable\fR are adjusted so that the chain of
   270    316   dictionaries no longer exists. The result of \fBdict with\fR is
   271    317   (unless some kind of error occurs) the result of the evaluation of
   272    318   \fIbody\fR.
          319  +.VS TIP508
          320  +If \fIdictionaryVarable\fR indicates an element that does not exist of an
          321  +array that has a default value set, the default value and will be used as the
          322  +value of the dictionary prior to the updating operation.
          323  +.VE TIP508
   273    324   .RS
   274    325   .PP
   275    326   The variables are mapped in the scope enclosing the \fBdict with\fR;
   276    327   it is recommended that this command only be used in a local scope
   277    328   (\fBproc\fRedure, lambda term for \fBapply\fR, or method). Because of
   278    329   this, the variables set by \fBdict with\fR will continue to
   279    330   exist after the command finishes (unless explicitly \fBunset\fR).

Changes to doc/eof.n.

    55     55       puts "Read record: $record"
    56     56   }
    57     57   .CE
    58     58   .SH "SEE ALSO"
    59     59   file(n), open(n), close(n), fblocked(n), Tcl_StandardChannels(3)
    60     60   .SH KEYWORDS
    61     61   channel, end of file
           62  +'\" Local Variables:
           63  +'\" mode: nroff
           64  +'\" fill-column: 78
           65  +'\" End:

Changes to doc/exec.n.

   212    212   .QW \[email protected]\0\fIfileId\fR
   213    213   notation, does not work.  When reading from a socket, a 16-bit DOS
   214    214   application will hang and a 32-bit application will return immediately with
   215    215   end-of-file.  When either type of application writes to a socket, the
   216    216   information is instead sent to the console, if one is present, or is
   217    217   discarded.
   218    218   .RS
          219  +.PP
          220  +Note that the current escape resp. quoting of arguments for windows works only
          221  +with executables using CommandLineToArgv, CRT-library or similar, as well as
          222  +with the windows batch files (excepting the newline, see below).
          223  +Although it is the common escape algorithm, but, in fact, the way how the
          224  +executable parses the command-line (resp. splits it into single arguments)
          225  +is decisive.
          226  +.PP
          227  +Unfortunately, there is currently no way to supply newline character within
          228  +an argument to the batch files (\fB.cmd\fR or \fB.bat\fR) or to the command
          229  +processor (\fBcmd.exe /c\fR), because this causes truncation of command-line
          230  +(also the argument chain) on the first newline character.
          231  +But it works properly with an executable (using CommandLineToArgv, etc).
   219    232   .PP
   220    233   The Tk console text widget does not provide real standard IO capabilities.
   221    234   Under Tk, when redirecting from standard input, all applications will see an
   222    235   immediate end-of-file; information redirected to standard output or standard
   223    236   error will be discarded.
   224    237   .PP
   225    238   Either forward or backward slashes are accepted as path separators for
................................................................................
   405    418   .CS
   406    419   \fBexec\fR cmp.bat somefile.c -o somefile
   407    420   .CE
   408    421   .PP
   409    422   With the file \fIcmp.bat\fR looking something like:
   410    423   .PP
   411    424   .CS
          425  +@gcc %*
          426  +.CE
          427  +or like another variant using single parameters:
          428  +.CS
   412    429   @gcc %1 %2 %3 %4 %5 %6 %7 %8 %9
   413    430   .CE
   414    431   .SS "WORKING WITH COMMAND BUILT-INS"
   415    432   .PP
   416    433   Sometimes you need to be careful, as different programs may have the
   417    434   same name and be in the path. It can then happen that typing a command
   418    435   at the DOS prompt finds \fIa different program\fR than the same

Changes to doc/exit.n.

    45     45       \fBexit\fR 2
    46     46   }
    47     47   .CE
    48     48   .SH "SEE ALSO"
    49     49   exec(n)
    50     50   .SH KEYWORDS
    51     51   abort, exit, process
           52  +'\" Local Variables:
           53  +'\" mode: nroff
           54  +'\" fill-column: 78
           55  +'\" End:

Changes to doc/expr.n.

    91     91   \fBTcl\fR.
    92     92   .PP
    93     93   Below are some examples of simple expressions where the value of \fBa\fR is 3
    94     94   and the value of \fBb\fR is 6.  The command on the left side of each line
    95     95   produces the value on the right side.
    96     96   .PP
    97     97   .CS
    98         -.ta 6c
           98  +.ta 9c
    99     99   \fBexpr\fR 3.1 + $a	\fI6.1\fR
   100    100   \fBexpr\fR 2 + "$a.$b"	\fI5.6\fR
   101    101   \fBexpr\fR 4*[llength "6 2"]	\fI8\fR
   102    102   \fBexpr\fR {{word one} < "word $a"}	\fI0\fR
   103    103   .CE
   104    104   .SS OPERATORS
   105    105   .PP
................................................................................
   120    120   .
   121    121   Unary minus, unary plus, bit-wise NOT, logical NOT.  These operators
   122    122   may only be applied to numeric operands, and bit-wise NOT may only be
   123    123   applied to integers.
   124    124   .TP 20
   125    125   \fB**\fR
   126    126   .
   127         -Exponentiation.  Valid for numeric operands.
          127  +Exponentiation.  Valid for numeric operands.  The maximum exponent value
          128  +that Tcl can handle if the first number is an integer > 1 is 268435455.
   128    129   .TP 20
   129    130   \fB*\0\0/\0\0%\fR
   130    131   .
   131    132   Multiply and divide, which are valid for numeric operands, and remainder, which
   132    133   is valid for integers.  The remainder, an absolute value smaller than the
   133    134   absolute value of the divisor, has the same sign as the divisor.
   134    135   .RS
................................................................................
   183    184   \fB|\fR
   184    185   .
   185    186   Bit-wise OR.  Valid for integer operands.
   186    187   .TP 20
   187    188   \fB&&\fR
   188    189   .
   189    190   Logical AND.  If both operands are true, the result is 1, or 0 otherwise.
   190         -
          191  +This operator evaluates lazily; it only evaluates its second operand if it
          192  +must in order to determine its result.
          193  +This operator evaluates lazily; it only evaluates its second operand if it
          194  +must in order to determine its result.
   191    195   .TP 20
   192    196   \fB||\fR
   193    197   .
   194    198   Logical OR.  If both operands are false, the result is 0, or 1 otherwise.
          199  +This operator evaluates lazily; it only evaluates its second operand if it
          200  +must in order to determine its result.
   195    201   .TP 20
   196         -\fIx\fB?\fIy\fB:\fIz\fR
          202  +\fIx \fB?\fI y \fB:\fI z\fR
   197    203   .
   198    204   If-then-else, as in C.  If \fIx\fR is false , the result is the value of
   199    205   \fIy\fR.  Otherwise the result is the value of \fIz\fR.
          206  +This operator evaluates lazily; it evaluates only one of \fIy\fR or \fIz\fR.
   200    207   .PP
   201    208   The exponentiation operator promotes types in the same way that the multiply
   202    209   and divide operators do, and the result is is the same as the result of
   203    210   \fBpow\fR.
   204    211   Exponentiation groups right-to-left within a precedence level. Other binary
   205    212   operators group left-to-right.  For example, the value of
          213  +.PP
   206    214   .PP
   207    215   .CS
   208    216   \fBexpr\fR {4*2 < 7}
   209    217   .CE
   210    218   .PP
   211    219   is 0, while the value of
   212    220   .PP
................................................................................
   330    338   substitutions on, enclosing an expression in braces or otherwise quoting it
   331    339   so that it's a static value allows the Tcl compiler to generate bytecode for
   332    340   the expression, resulting in better speed and smaller storage requirements.
   333    341   This also avoids issues that can arise if Tcl is allowed to perform
   334    342   substitution on the value before \fBexpr\fR is called.
   335    343   .PP
   336    344   In the following example, the value of the expression is 11 because the Tcl parser first
   337         -substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR.  Enclosing the
   338         -expression in braces would result in a syntax error.
          345  +substitutes \fB$b\fR and \fBexpr\fR then substitutes \fB$a\fR as part
          346  +of evaluating the expression
          347  +.QW "$a + 2*4" .
          348  +Enclosing the
          349  +expression in braces would result in a syntax error as \fB$b\fR does
          350  +not evaluate to a numeric value.
          351  +.PP
   339    352   .CS
   340    353   set a 3
   341    354   set b {$a + 2}
   342    355   \fBexpr\fR $b*4
   343    356   .CE
   344    357   .PP
   345         -
   346         -When an expression is generated at runtime, like the one above is, the bytcode
          358  +When an expression is generated at runtime, like the one above is, the bytecode
   347    359   compiler must ensure that new code is generated each time the expression
   348    360   is evaluated.  This is the most costly kind of expression from a performance
   349    361   perspective.  In such cases, consider directly using the commands described in
   350    362   the \fBmathfunc\fR(n) or \fBmathop\fR(n) documentation instead of \fBexpr\fR.
   351         -
          363  +.PP
   352    364   Most expressions are not formed at runtime, but are literal strings or contain
   353    365   substitutions that don't introduce other substitutions.  To allow the bytecode
   354    366   compiler to work with an expression as a string literal at compilation time,
   355    367   ensure that it contains no substitutions or that it is enclosed in braces or
   356    368   otherwise quoted to prevent Tcl from performing substitutions, allowing
   357    369   \fBexpr\fR to perform them instead.
          370  +.PP
          371  +If it is necessary to include a non-constant expression string within the
          372  +wider context of an otherwise-constant expression, the most efficient
          373  +technique is to put the varying part inside a recursive \fBexpr\fR, as this at
          374  +least allows for the compilation of the outer part, though it does mean that
          375  +the varying part must itself be evaluated as a separate expression. Thus, in
          376  +this example the result is 20 and the outer expression benefits from fully
          377  +cached bytecode compilation.
          378  +.PP
          379  +.CS
          380  +set a 3
          381  +set b {$a + 2}
          382  +\fBexpr\fR {[\fBexpr\fR $b] * 4}
          383  +.CE
          384  +.PP
          385  +In general, you should enclose your expression in braces wherever possible,
          386  +and where not possible, the argument to \fBexpr\fR should be an expression
          387  +defined elsewhere as simply as possible. It is usually more efficient and
          388  +safer to use other techniques (e.g., the commands in the \fBtcl::mathop\fR
          389  +namespace) than it is to do complex expression generation.
   358    390   .SH EXAMPLES
   359    391   .PP
   360    392   A numeric comparison whose result is 1:
          393  +.PP
   361    394   .CS
   362    395   \fBexpr\fR {"0x03" > "2"}
   363    396   .CE
   364    397   .PP
   365    398   A string comparison whose result is 1:
          399  +.PP
   366    400   .CS
   367    401   \fBexpr\fR {"0y" > "0x12"}
   368    402   .CE
   369    403   .PP
   370    404   Define a procedure that computes an
   371    405   .QW interesting
   372    406   mathematical function:

Changes to doc/fblocked.n.

    61     61   socket -server connect 12345
    62     62   vwait forever
    63     63   .CE
    64     64   .SH "SEE ALSO"
    65     65   gets(n), open(n), read(n), socket(n), Tcl_StandardChannels(3)
    66     66   .SH KEYWORDS
    67     67   blocking, nonblocking
           68  +'\" Local Variables:
           69  +'\" mode: nroff
           70  +'\" fill-column: 78
           71  +'\" End:

Changes to doc/file.n.

   428    428   \fBfile tail \fIname\fR
   429    429   .
   430    430   Returns all of the characters in the last filesystem component of
   431    431   \fIname\fR.  Any trailing directory separator in \fIname\fR is ignored.
   432    432   If \fIname\fR contains no separators then returns \fIname\fR.  So,
   433    433   \fBfile tail a/b\fR, \fBfile tail a/b/\fR and \fBfile tail b\fR all
   434    434   return \fBb\fR.
          435  +.TP
          436  +\fBfile tempdir\fR ?\fItemplate\fR?
          437  +.VS "8.7, TIP 431"
          438  +Creates a temporary directory (guaranteed to be newly created and writable by
          439  +the current script) and returns its name. If \fItemplate\fR is given, it
          440  +specifies one of or both of the existing directory (on a filesystem controlled
          441  +by the operating system) to contain the temporary directory, and the base part
          442  +of the directory name; it is considered to have the location of the directory
          443  +if there is a directory separator in the name, and the base part is everything
          444  +after the last directory separator (if non-empty).  The default containing
          445  +directory is determined by system-specific operations, and the default base
          446  +name prefix is
          447  +.QW \fBtcl\fR .
          448  +.RS
          449  +.PP
          450  +The following output is typical and illustrative; the actual output will vary
          451  +between platforms:
          452  +.PP
          453  +.CS
          454  +% \fBfile tempdir\fR
          455  +/var/tmp/tcl_u0kuy5
          456  + % \fBfile tempdir\fR /tmp/myapp
          457  +/tmp/myapp_8o7r9L
          458  +% \fBfile tempdir\fR /tmp/
          459  +/tmp/tcl_1mOJHD
          460  +% \fBfile tempdir\fR myapp
          461  +/var/tmp/myapp_0ihS0n
          462  +.CE
          463  +.RE
          464  +.VE "8.7, TIP 431"
   435    465   .TP
   436    466   \fBfile tempfile\fR ?\fInameVar\fR? ?\fItemplate\fR?
   437    467   '\" TIP #210
   438    468   .VS 8.6
   439    469   Creates a temporary file and returns a read-write channel opened on that file.
   440    470   If the \fInameVar\fR is given, it specifies a variable that the name of the
   441    471   temporary file will be written into; if absent, Tcl will attempt to arrange

Changes to doc/fileevent.n.

   150    150   \fBfileevent\fR is based on the \fBaddinput\fR command created
   151    151   by Mark Diekhans.
   152    152   .SH "SEE ALSO"
   153    153   fconfigure(n), gets(n), interp(n), puts(n), read(n), Tcl_StandardChannels(3)
   154    154   .SH KEYWORDS
   155    155   asynchronous I/O, blocking, channel, event handler, nonblocking, readable,
   156    156   script, writable.
          157  +'\" Local Variables:
          158  +'\" mode: nroff
          159  +'\" fill-column: 78
          160  +'\" End:

Changes to doc/filename.n.

   172    172   .QW .....abc
   173    173   is illegal.
   174    174   .SH "SEE ALSO"
   175    175   file(n), glob(n)
   176    176   .SH KEYWORDS
   177    177   current directory, absolute file name, relative file name,
   178    178   volume-relative file name, portability
          179  +'\" Local Variables:
          180  +'\" mode: nroff
          181  +'\" fill-column: 78
          182  +'\" End:

Changes to doc/flush.n.

    39     39   gets stdin name
    40     40   puts "Hello there, $name!"
    41     41   .CE
    42     42   .SH "SEE ALSO"
    43     43   file(n), open(n), socket(n), Tcl_StandardChannels(3)
    44     44   .SH KEYWORDS
    45     45   blocking, buffer, channel, flush, nonblocking, output
           46  +'\" Local Variables:
           47  +'\" mode: nroff
           48  +'\" fill-column: 78
           49  +'\" End:

Changes to doc/foreach.n.

    98     98   .CE
    99     99   
   100    100   .SH "SEE ALSO"
   101    101   for(n), while(n), break(n), continue(n)
   102    102   
   103    103   .SH KEYWORDS
   104    104   foreach, iteration, list, loop
          105  +'\" Local Variables:
          106  +'\" mode: nroff
          107  +'\" fill-column: 78
          108  +'\" End:

Changes to doc/global.n.

    52     52       append accumulator $string \en
    53     53   }
    54     54   .CE
    55     55   .SH "SEE ALSO"
    56     56   namespace(n), upvar(n), variable(n)
    57     57   .SH KEYWORDS
    58     58   global, namespace, procedure, variable
           59  +'\" Local Variables:
           60  +'\" mode: nroff
           61  +'\" fill-column: 78
           62  +'\" End:

Changes to doc/history.n.

    96     96   is modified to eliminate the history command and replace it with
    97     97   the result of the history command.
    98     98   If you want to redo an event without modifying history, then use
    99     99   the \fBevent\fR operation to retrieve some event,
   100    100   and the \fBadd\fR operation to add it to history and execute it.
   101    101   .SH KEYWORDS
   102    102   event, history, record
          103  +'\" Local Variables:
          104  +'\" mode: nroff
          105  +'\" fill-column: 78
          106  +'\" End:

Changes to doc/http.n.

     2      2   '\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
     3      3   '\" Copyright (c) 1998-2000 by Ajuba Solutions.
     4      4   '\" Copyright (c) 2004 ActiveState Corporation.
     5      5   '\"
     6      6   '\" See the file "license.terms" for information on usage and redistribution
     7      7   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
     8      8   '\"
     9         -.TH "http" n 2.7 http "Tcl Bundled Packages"
            9  +.TH "http" n 2.9 http "Tcl Bundled Packages"
    10     10   .so man.macros
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   http \- Client-side implementation of the HTTP/1.1 protocol
    15     15   .SH SYNOPSIS
    16         -\fBpackage require http ?2.7?\fR
           16  +\fBpackage require http\fI ?\fB2.8\fR?
    17     17   .\" See Also -useragent option documentation in body!
    18     18   .sp
    19         -\fB::http::config ?\fI\-option value\fR ...?
           19  +\fB::http::config\fR ?\fI\-option value\fR ...?
    20     20   .sp
    21     21   \fB::http::geturl \fIurl\fR ?\fI\-option value\fR ...?
    22     22   .sp
    23     23   \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
           24  +.sp
           25  +\fB::http::quoteString\fR \fIvalue\fR
    24     26   .sp
    25     27   \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
    26     28   .sp
    27     29   \fB::http::wait \fItoken\fR
    28     30   .sp
    29     31   \fB::http::status \fItoken\fR
    30     32   .sp
................................................................................
    40     42   .sp
    41     43   \fB::http::error \fItoken\fR
    42     44   .sp
    43     45   \fB::http::cleanup \fItoken\fR
    44     46   .sp
    45     47   \fB::http::register \fIproto port command\fR
    46     48   .sp
           49  +\fB::http::registerError \fIport\fR ?\fImessage\fR?
           50  +.sp
    47     51   \fB::http::unregister \fIproto\fR
    48     52   .BE
    49     53   .SH DESCRIPTION
    50     54   .PP
    51     55   The \fBhttp\fR package provides the client side of the HTTP/1.1
    52         -protocol, as defined in RFC 2616.
           56  +protocol, as defined in RFC 7230 to RFC 7235, which supersede RFC 2616.
    53     57   The package implements the GET, POST, and HEAD operations
    54     58   of HTTP/1.1.  It allows configuration of a proxy host to get through
    55     59   firewalls.  The package is compatible with the \fBSafesock\fR security
    56     60   policy, so it can be used by untrusted applets to do URL fetching from
    57     61   a restricted set of hosts. This package can be extended to support
    58     62   additional HTTP transport protocols, such as HTTPS, by providing
    59     63   a custom \fBsocket\fR command, via \fB::http::register\fR.
................................................................................
    90     94   \fB\-accept\fR \fImimetypes\fR
    91     95   .
    92     96   The Accept header of the request.  The default is */*, which means that
    93     97   all types of documents are accepted.  Otherwise you can supply a
    94     98   comma-separated list of mime type patterns that you are
    95     99   willing to receive.  For example,
    96    100   .QW "image/gif, image/jpeg, text/*" .
          101  +.TP
          102  +\fB\-cookiejar\fR \fIcommand\fR
          103  +.VS TIP406
          104  +The cookie store for the package to use to manage HTTP cookies.
          105  +\fIcommand\fR is a command prefix list; if the empty list (the
          106  +default value) is used, no cookies will be sent by requests or stored
          107  +from responses. The command indicated by \fIcommand\fR, if supplied,
          108  +must obey the \fBCOOKIE JAR PROTOCOL\fR described below.
          109  +.VE TIP406
          110  +.TP
          111  +\fB\-pipeline\fR \fIboolean\fR
          112  +.
          113  +Specifies whether HTTP/1.1 transactions on a persistent socket will be
          114  +pipelined.  See the \fBPERSISTENT SOCKETS\fR section for details. The default
          115  +is 1.
          116  +.TP
          117  +\fB\-postfresh\fR \fIboolean\fR
          118  +.
          119  +Specifies whether requests that use the \fBPOST\fR method will always use a
          120  +fresh socket, overriding the \fB-keepalive\fR option of
          121  +command \fBhttp::geturl\fR.  See the \fBPERSISTENT SOCKETS\fR section for details.
          122  +The default is 0.
    97    123   .TP
    98    124   \fB\-proxyhost\fR \fIhostname\fR
    99    125   .
   100    126   The name of the proxy host, if any.  If this value is the
   101    127   empty string, the URL host is contacted directly.
   102    128   .TP
   103    129   \fB\-proxyport\fR \fInumber\fR
................................................................................
   111    137   to determine if a proxy is required for a given host.  One argument, a
   112    138   host name, is added to \fIcommand\fR when it is invoked.  If a proxy
   113    139   is required, the callback should return a two-element list containing
   114    140   the proxy server and proxy port.  Otherwise the filter should return
   115    141   an empty list.  The default filter returns the values of the
   116    142   \fB\-proxyhost\fR and \fB\-proxyport\fR settings if they are
   117    143   non-empty.
          144  +.TP
          145  +\fB\-repost\fR \fIboolean\fR
          146  +.
          147  +Specifies what to do if a POST request over a persistent connection fails
          148  +because the server has half-closed the connection.  If boolean \fBtrue\fR, the
          149  +request
          150  +will be automatically retried; if boolean \fBfalse\fR it will not, and the
          151  +application
          152  +that uses \fBhttp::geturl\fR is expected to seek user confirmation before
          153  +retrying the POST.  The value \fBtrue\fR should be used only under certain
          154  +conditions. See the \fBPERSISTENT SOCKETS\fR section for details. The
          155  +default is 0.
   118    156   .TP
   119    157   \fB\-urlencoding\fR \fIencoding\fR
   120    158   .
   121    159   The \fIencoding\fR used for creating the x-url-encoded URLs with
   122         -\fB::http::formatQuery\fR.  The default is \fButf-8\fR, as specified by RFC
          160  +\fB::http::formatQuery\fR and \fB::http::quoteString\fR.
          161  +The default is \fButf-8\fR, as specified by RFC
   123    162   2718.  Prior to http 2.5 this was unspecified, and that behavior can be
   124    163   returned by specifying the empty string (\fB{}\fR), although
   125    164   \fIiso8859-1\fR is recommended to restore similar behavior but without the
   126         -\fB::http::formatQuery\fR throwing an error processing non-latin-1
   127         -characters.
          165  +\fB::http::formatQuery\fR or \fB::http::quoteString\fR
          166  +throwing an error processing non-latin-1 characters.
   128    167   .TP
   129    168   \fB\-useragent\fR \fIstring\fR
   130    169   .
   131         -The value of the User-Agent header in the HTTP request.  The default is
   132         -.QW "\fBTcl http client package 2.7\fR" .
          170  +The value of the User-Agent header in the HTTP request.  In an unsafe
          171  +interpreter, the default value depends upon the operating system, and
          172  +the version numbers of \fBhttp\fR and \fBTcl\fR, and is (for example)
          173  +.QW "\fBMozilla/5.0 (Windows; U; Windows NT 10.0) http/2.8.12 Tcl/8.6.8\fR" .
          174  +A safe interpreter cannot determine its operating system, and so the default
          175  +in a safe interpreter is to use a Windows 10 value with the current version
          176  +numbers of \fBhttp\fR and \fBTcl\fR.
          177  +.TP
          178  +\fB\-zip\fR \fIboolean\fR
          179  +.
          180  +If the value is boolean \fBtrue\fR, then by default requests will send a header
          181  +.QW "\fBAccept-Encoding: gzip,deflate,compress\fR" .
          182  +If the value is boolean \fBfalse\fR, then by default this header will not be sent.
          183  +In either case the default can be overridden for an individual request by
          184  +supplying a custom \fBAccept-Encoding\fR header in the \fB-headers\fR option
          185  +of \fBhttp::geturl\fR. The default is 1.
   133    186   .RE
   134    187   .TP
   135    188   \fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR?
   136    189   .
   137    190   The \fB::http::geturl\fR command is the main procedure in the package.
   138    191   The \fB\-query\fR option causes a POST operation and
   139    192   the \fB\-validate\fR option causes a HEAD operation;
................................................................................
   223    276   .CS
   224    277   Pragma: no-cache
   225    278   .CE
   226    279   .RE
   227    280   .TP
   228    281   \fB\-keepalive\fR \fIboolean\fR
   229    282   .
   230         -If true, attempt to keep the connection open for servicing
          283  +If boolean \fBtrue\fR, attempt to keep the connection open for servicing
   231    284   multiple requests.  Default is 0.
   232    285   .TP
   233    286   \fB\-method\fR \fItype\fR
   234    287   .
   235    288   Force the HTTP request method to \fItype\fR. \fB::http::geturl\fR will
   236    289   auto-select GET, POST or HEAD based on other options, but this option
   237    290   enables choices like PUT and DELETE for webdav support.
................................................................................
   329    382   \fB::http::formatQuery\fR \fIkey value\fR ?\fIkey value\fR ...?
   330    383   .
   331    384   This procedure does x-url-encoding of query data.  It takes an even
   332    385   number of arguments that are the keys and values of the query.  It
   333    386   encodes the keys and values, and generates one string that has the
   334    387   proper & and = separators.  The result is suitable for the
   335    388   \fB\-query\fR value passed to \fB::http::geturl\fR.
          389  +.TP
          390  +\fB::http::quoteString\fR \fIvalue\fR
          391  +.
          392  +This procedure does x-url-encoding of string.  It takes a single argument and
          393  +encodes it.
   336    394   .TP
   337    395   \fB::http::reset\fR \fItoken\fR ?\fIwhy\fR?
   338    396   .
   339    397   This command resets the HTTP transaction identified by \fItoken\fR, if any.
   340    398   This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to
   341    399   \fBreset\fR, and then calls the registered \fB\-command\fR callback.
   342    400   .TP
................................................................................
   410    468   package require tls
   411    469   
   412    470   ::http::register https 443 ::tls::socket
   413    471   
   414    472   set token [::http::geturl https://my.secure.site/]
   415    473   .CE
   416    474   .RE
          475  +.TP
          476  +\fB::http::registerError\fR \fIport\fR ?\fImessage\fR?
          477  +.
          478  +This procedure allows a registered protocol handler to deliver an error
          479  +message for use by \fBhttp\fR.  Calling this command does not raise an
          480  +error. The command is useful when a registered protocol detects an problem
          481  +(for example, an invalid TLS certificate) that will cause an error to
          482  +propagate to \fBhttp\fR.  The command allows \fBhttp\fR to provide a
          483  +precise error message rather than a general one.  The command returns the
          484  +value provided by the last call with argument \fImessage\fR, or the empty
          485  +string if no such call has been made.
   417    486   .TP
   418    487   \fB::http::unregister\fR \fIproto\fR
   419    488   .
   420    489   This procedure unregisters a protocol handler that was previously
   421    490   registered via \fB::http::register\fR, returning a two-item list of
   422    491   the default port and handler command that was previously installed
   423    492   (via \fB::http::register\fR) if there was such a handler, and an error if
................................................................................
   500    569   Once the data associated with the URL is no longer needed, the state
   501    570   array should be unset to free up storage.
   502    571   The \fB::http::cleanup\fR procedure is provided for that purpose.
   503    572   The following elements of
   504    573   the array are supported:
   505    574   .RS
   506    575   .TP
          576  +\fBbinary\fR
          577  +.
          578  +This is boolean \fBtrue\fR if (after decoding any compression specified
          579  +by the
          580  +.QW "Content-Encoding"
          581  +response header) the HTTP response is binary.  It is boolean \fBfalse\fR
          582  +if the HTTP response is text.
          583  +.TP
   507    584   \fBbody\fR
   508    585   .
   509    586   The contents of the URL.  This will be empty if the \fB\-channel\fR
   510    587   option has been specified.  This value is returned by the \fB::http::data\fR command.
   511    588   .TP
   512    589   \fBcharset\fR
   513    590   .
................................................................................
   598    675   .
   599    676   A copy of the \fBContent-Type\fR meta-data value.
   600    677   .TP
   601    678   \fBurl\fR
   602    679   .
   603    680   The requested URL.
   604    681   .RE
          682  +.SH "PERSISTENT CONNECTIONS"
          683  +.PP
          684  +.SS "BASICS"
          685  +.PP
          686  +See RFC 7230 Sec 6, which supersedes RFC 2616 Sec 8.1.
          687  +.PP
          688  +A persistent connection allows multiple HTTP/1.1 transactions to be
          689  +carried over the same TCP connection.  Pipelining allows a
          690  +client to make multiple requests over a persistent connection without
          691  +waiting for each response.  The server sends responses in the same order
          692  +that the requests were received.
          693  +.PP
          694  +If a POST request fails to complete, typically user confirmation is
          695  +needed before sending the request again.  The user may wish to verify
          696  +whether the server was modified by the failed POST request, before
          697  +sending the same request again.
          698  +.PP
          699  +A HTTP request will use a persistent socket if the call to
          700  +\fBhttp::geturl\fR has the option \fB-keepalive true\fR. It will use
          701  +pipelining where permitted if the \fBhttp::config\fR option
          702  +\fB-pipeline\fR is boolean \fBtrue\fR (its default value).
          703  +.PP
          704  +The http package maintains no more than one persistent connection to each
          705  +server (i.e. each value of
          706  +.QW "domain:port" ).
          707  +If \fBhttp::geturl\fR is called to make a request over a persistent
          708  +connection while the connection is busy with another request, the new
          709  +request will be held in a queue until the connection is free.
          710  +.PP
          711  +The http package does not support HTTP/1.0 persistent connections
          712  +controlled by the \fBKeep-Alive\fR header.
          713  +.SS "SPECIAL CASES"
          714  +.PP
          715  +This subsection discusses issues related to closure of the
          716  +persistent connection by the server, automatic retry of failed requests,
          717  +the special treatment necessary for POST requests, and the options for
          718  +dealing with these cases.
          719  +.PP
          720  +In accordance with RFC 7230, \fBhttp::geturl\fR does not pipeline
          721  +requests that use the POST method.  If a POST uses a persistent
          722  +connection and is not the first request on that connection,
          723  +\fBhttp::geturl\fR waits until it has received the response for the previous
          724  +request; or (if \fBhttp::config\fR option \fB-postfresh\fR is boolean \fBtrue\fR) it
          725  +uses a new connection for each POST.
          726  +.PP
          727  +If the server is processing a number of pipelined requests, and sends a
          728  +response header
          729  +.QW "\fBConnection: close\fR"
          730  +with one of the responses (other than the last), then subsequent responses
          731  +are unfulfilled. \fBhttp::geturl\fR will send the unfulfilled requests again
          732  +over a new connection.
          733  +.PP
          734  +A difficulty arises when a HTTP client sends a request over a persistent
          735  +connection that has been idle for a while.  The HTTP server may
          736  +half-close an apparently idle connection while the client is sending a
          737  +request, but before the request arrives at the server: in this case (an
          738  +.QW "asynchronous close event" )
          739  +the request will fail.  The difficulty arises because the client cannot
          740  +be certain whether the POST modified the state of the server.  For HEAD or
          741  +GET requests, \fBhttp::geturl\fR opens another connection and retransmits
          742  +the failed request. However, if the request was a POST, RFC 7230 forbids
          743  +automatic retry by default, suggesting either user confirmation, or
          744  +confirmation by user-agent software that has semantic understanding of
          745  +the application.  The \fBhttp::config\fR option \fB-repost\fR allows for
          746  +either possibility.
          747  +.PP
          748  +Asynchronous close events can occur only in a short interval of time.  The
          749  +\fBhttp\fR package monitors each persistent connection for closure by the
          750  +server.  Upon detection, the connection is also closed at the client end,
          751  +and subsequent requests will use a fresh connection.
          752  +.PP
          753  +If the \fBhttp::geturl\fR command is called with option \fB-keepalive true\fR,
          754  +then it will both try to use an existing persistent connection
          755  +(if one is available), and it will send the server a
          756  +.QW "\fBConnection: keep-alive\fR"
          757  +request header asking to keep the connection open for future requests.
          758  +.PP
          759  +The \fBhttp::config\fR options \fB-pipeline\fR, \fB-postfresh\fR, and
          760  +\fB-repost\fR relate to persistent connections.
          761  +.PP
          762  +Option \fB-pipeline\fR, if boolean \fBtrue\fR, will pipeline GET and HEAD requests
          763  +made
          764  +over a persistent connection.  POST requests will not be pipelined - if the
          765  +POST is not the first transaction on the connection, its request will not
          766  +be sent until the previous response has finished.  GET and HEAD requests
          767  +made after a POST will not be sent until the POST response has been
          768  +delivered, and will not be sent if the POST fails.
          769  +.PP
          770  +Option \fB-postfresh\fR, if boolean \fBtrue\fR, will override the \fBhttp::geturl\fR option
          771  +\fB-keepalive\fR, and always open a fresh connection for a POST request.
          772  +.PP
          773  +Option \fB-repost\fR, if \fBtrue\fR, permits automatic retry of a POST request
          774  +that fails because it uses a persistent connection that the server has
          775  +half-closed (an
          776  +.QW "asynchronous close event" ).
          777  +Subsequent GET and HEAD requests in a failed pipeline will also be retried.
          778  +\fIThe -repost option should be used only if the application understands
          779  +that the retry is appropriate\fR - specifically, the application must know
          780  +that if the failed POST successfully modified the state of the server, a repeat POST
          781  +would have no adverse effect.
          782  +.VS TIP406
          783  +.SH "COOKIE JAR PROTOCOL"
          784  +.PP
          785  +Cookies are short key-value pairs used to implement sessions within the
          786  +otherwise-stateless HTTP protocol. (See RFC 6265 for details; Tcl does not
          787  +implement the Cookie2 protocol as that is rarely seen in the wild.)
          788  +.PP
          789  +Cookie storage managment commands \(em
          790  +.QW "cookie jars"
          791  +\(em must support these subcommands which form the HTTP cookie storage
          792  +management protocol. Note that \fIcookieJar\fR below does not have to be a
          793  +command name; it is properly a command prefix (a Tcl list of words that will
          794  +be expanded in place) and admits many possible implementations.
          795  +.PP
          796  +Though not formally part of the protocol, it is expected that particular
          797  +values of \fIcookieJar\fR will correspond to sessions; it is up to the caller
          798  +of \fB::http::config\fR to decide what session applies and to manage the
          799  +deletion of said sessions when they are no longer desired (which should be
          800  +when they not configured as the current cookie jar).
          801  +.TP
          802  +\fIcookieJar \fBgetCookies \fIprotocol host requestPath\fR
          803  +.
          804  +This command asks the cookie jar what cookies should be supplied for a
          805  +particular request. It should take the \fIprotocol\fR (typically \fBhttp\fR or
          806  +\fBhttps\fR), \fIhost\fR name and \fIrequestPath\fR (parsed from the \fIurl\fR
          807  +argument to \fB::http::geturl\fR) and return a list of cookie keys and values
          808  +that describe the cookies to supply to the remote host. The list must have an
          809  +even number of elements.
          810  +.RS
          811  +.PP
          812  +There should only ever be at most one cookie with a particular key for any
          813  +request (typically the one with the most specific \fIhost\fR/domain match and
          814  +most specific \fIrequestPath\fR/path match), but there may be many cookies
          815  +with different names in any request.
          816  +.RE
          817  +.TP
          818  +\fIcookieJar \fBstoreCookie \fIcookieDictionary\fR
          819  +.
          820  +This command asks the cookie jar to store a particular cookie that was
          821  +returned by a request; the result of this command is ignored. The cookie
          822  +(which will have been parsed by the http package) is described by a
          823  +dictionary, \fIcookieDictionary\fR, that may have the following keys:
          824  +.RS
          825  +.TP
          826  +\fBdomain\fR
          827  +.
          828  +This is always present. Its value describes the domain hostname \fIor
          829  +prefix\fR that the cookie should be returned for.  The checking of the domain
          830  +against the origin (below) should be careful since sites that issue cookies
          831  +should only do so for domains related to themselves. Cookies that do not obey
          832  +a relevant origin matching rule should be ignored.
          833  +.TP
          834  +\fBexpires\fR
          835  +.
          836  +This is optional. If present, the cookie is intended to be a persistent cookie
          837  +and the value of the option is the Tcl timestamp (in seconds from the same
          838  +base as \fBclock seconds\fR) of when the cookie expires (which may be in the
          839  +past, which should result in the cookie being deleted immediately). If absent,
          840  +the cookie is intended to be a session cookie that should be not persisted
          841  +beyond the lifetime of the cookie jar.
          842  +.TP
          843  +\fBhostonly\fR
          844  +.
          845  +This is always present. Its value is a boolean that describes whether the
          846  +cookie is a single host cookie (true) or a domain-level cookie (false).
          847  +.TP
          848  +\fBhttponly\fR
          849  +.
          850  +This is always present. Its value is a boolean that is true when the site
          851  +wishes the cookie to only ever be used with HTTP (or HTTPS) traffic.
          852  +.TP
          853  +\fBkey\fR
          854  +.
          855  +This is always present. Its value is the \fIkey\fR of the cookie, which is
          856  +part of the information that must be return when sending this cookie back in a
          857  +future request.
          858  +.TP
          859  +\fBorigin\fR
          860  +.
          861  +This is always present. Its value describes where the http package believes it
          862  +received the cookie from, which may be useful for checking whether the
          863  +cookie's domain is valid.
          864  +.TP
          865  +\fBpath\fR
          866  +.
          867  +This is always present. Its value describes the path prefix of requests to the
          868  +cookie domain where the cookie should be returned.
          869  +.TP
          870  +\fBsecure\fR
          871  +.
          872  +This is always present. Its value is a boolean that is true when the cookie
          873  +should only used on requests sent over secure channels (typically HTTPS).
          874  +.TP
          875  +\fBvalue\fR
          876  +.
          877  +This is always present. Its value is the value of the cookie, which is part of
          878  +the information that must be return when sending this cookie back in a future
          879  +request.
          880  +.PP
          881  +Other keys may always be ignored; they have no meaning in this protocol.
          882  +.RE
          883  +.VE TIP406
   605    884   .SH EXAMPLE
   606    885   .PP
   607    886   This example creates a procedure to copy a URL to a file while printing a
   608    887   progress meter, and prints the meta-data associated with the URL.
   609    888   .PP
   610    889   .CS
   611    890   proc httpcopy { url file {chunk 4096} } {

Added doc/idna.n.

            1  +'\"
            2  +'\" Copyright (c) 2014-2018 Donal K. Fellows.
            3  +'\"
            4  +'\" See the file "license.terms" for information on usage and redistribution
            5  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            6  +'\"
            7  +.TH "idna" n 0.1 http "Tcl Bundled Packages"
            8  +.so man.macros
            9  +.BS
           10  +'\" Note:  do not modify the .SH NAME line immediately below!
           11  +.SH NAME
           12  +tcl::idna \- Support for normalization of Internationalized Domain Names
           13  +.SH SYNOPSIS
           14  +.nf
           15  +package require tcl::idna 1.0
           16  +
           17  +\fBtcl::idna decode\fR \fIhostname\fR
           18  +\fBtcl::idna encode\fR \fIhostname\fR
           19  +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR?
           20  +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR?
           21  +\fBtcl::idna version\fR
           22  +.fi
           23  +.SH DESCRIPTION
           24  +This package provides an implementation of the punycode scheme used in
           25  +Internationalised Domain Names, and some access commands. (See RFC 3492 for a
           26  +description of punycode.)
           27  +.TP
           28  +\fBtcl::idna decode\fR \fIhostname\fR
           29  +.
           30  +This command takes the name of a host that potentially contains
           31  +punycode-encoded character sequences, \fIhostname\fR, and returns the hostname
           32  +as might be displayed to the user. Note that there are often UNICODE
           33  +characters that have extremely similar glyphs, so care should be taken with
           34  +displaying hostnames to users.
           35  +.TP
           36  +\fBtcl::idna encode\fR \fIhostname\fR
           37  +.
           38  +This command takes the name of a host as might be displayed to the user,
           39  +\fIhostname\fR, and returns the version of the hostname with characters not
           40  +permitted in basic hostnames encoded with punycode.
           41  +.TP
           42  +\fBtcl::idna puny\fR \fIsubcommand ...\fR
           43  +.
           44  +This command provides direct access to the basic punycode encoder and
           45  +decoder. It supports two \fIsubcommand\fRs:
           46  +.RS
           47  +.TP
           48  +\fBtcl::idna puny decode\fR \fIstring\fR ?\fIcase\fR?
           49  +.
           50  +This command decodes the punycode-encoded string, \fIstring\fR, and returns
           51  +the result. If \fIcase\fR is provided, it is a boolean to make the case be
           52  +folded to upper case (if \fIcase\fR is true) or lower case (if \fIcase\fR is
           53  +false) during the decoding process; if omitted, no case transformation is
           54  +applied.
           55  +.TP
           56  +\fBtcl::idna puny encode\fR \fIstring\fR ?\fIcase\fR?
           57  +.
           58  +This command encodes the string, \fIstring\fR, and returns the
           59  +punycode-encoded version of the string. If \fIcase\fR is provided, it is a
           60  +boolean to make the case be folded to upper case (if \fIcase\fR is true) or
           61  +lower case (if \fIcase\fR is false) during the encoding process; if omitted,
           62  +no case transformation is applied.
           63  +.RE
           64  +.TP
           65  +\fBtcl::idna version\fR
           66  +.
           67  +This returns the version of the \fBtcl::idna\fR package.
           68  +.SH "EXAMPLE"
           69  +.PP
           70  +This is an example of how punycoding of a string works:
           71  +.PP
           72  +.CS
           73  +package require tcl::idna
           74  +
           75  +puts [\fBtcl::idna puny encode\fR "abc\(->def"]
           76  +#    prints: \fIabcdef-kn2c\fR
           77  +puts [\fBtcl::idna puny decode\fR "abcdef-kn2c"]
           78  +#    prints: \fIabc\(->def\fR
           79  +.CE
           80  +'\" TODO: show how it handles a real domain name
           81  +.SH "SEE ALSO"
           82  +http(n), cookiejar(n)
           83  +.SH KEYWORDS
           84  +internet, www
           85  +'\" Local Variables:
           86  +'\" mode: nroff
           87  +'\" fill-column: 78
           88  +'\" End:

Changes to doc/incr.n.

    23     23   1 is added to \fIvarName\fR.
    24     24   The new value is stored as a decimal string in variable \fIvarName\fR
    25     25   and also returned as result.
    26     26   .PP
    27     27   Starting with the Tcl 8.5 release, the variable \fIvarName\fR passed
    28     28   to \fBincr\fR may be unset, and in that case, it will be set to
    29     29   the value \fIincrement\fR or to the default increment value of \fB1\fR.
           30  +.VS TIP508
           31  +If \fIvarName\fR indicate an element that does not exist of an array that has
           32  +a default value set, the sum of the default value and the \fIincrement\fR (or
           33  +1) will be stored in the array element.
           34  +.VE TIP508
    30     35   .SH EXAMPLES
    31     36   .PP
    32     37   Add one to the contents of the variable \fIx\fR:
    33     38   .PP
    34     39   .CS
    35     40   \fBincr\fR x
    36     41   .CE
................................................................................
    55     60   .CS
    56     61   \fBincr\fR x 0
    57     62   .CE
    58     63   .SH "SEE ALSO"
    59     64   expr(n), set(n)
    60     65   .SH KEYWORDS
    61     66   add, increment, variable, value
           67  +.\" Local variables:
           68  +.\" mode: nroff
           69  +.\" fill-column: 78
           70  +.\" End:

Changes to doc/info.n.

     9      9   '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
    10     10   '\"
    11     11   .TH info n 8.4 Tcl "Tcl Built-In Commands"
    12     12   .so man.macros
    13     13   .BS
    14     14   '\" Note:  do not modify the .SH NAME line immediately below!
    15     15   .SH NAME
    16         -info \- Return information about the state of the Tcl interpreter
           16  +info \- Information about the state of the Tcl interpreter
    17     17   .SH SYNOPSIS
    18     18   \fBinfo \fIoption \fR?\fIarg arg ...\fR?
    19     19   .BE
    20     20   .SH DESCRIPTION
    21     21   .PP
    22         -This command provides information about various internals of the Tcl
    23         -interpreter.
    24         -The legal \fIoption\fRs (which may be abbreviated) are:
           22  +Available commands:
    25     23   .TP
    26     24   \fBinfo args \fIprocname\fR
    27     25   .
    28         -Returns a list containing the names of the arguments to procedure
    29         -\fIprocname\fR, in order.  \fIProcname\fR must be the name of a
    30         -Tcl command procedure.
           26  +Returns the names of the parameters to the procedure named \fIprocname\fR.
    31     27   .TP
    32     28   \fBinfo body \fIprocname\fR
    33     29   .
    34         -Returns the body of procedure \fIprocname\fR.  \fIProcname\fR must be
    35         -the name of a Tcl command procedure.
           30  +Returns the body of the procedure named \fIprocname\fR.
    36     31   .TP
    37     32   \fBinfo class\fI subcommand class\fR ?\fIarg ...\fR
    38         -.VS 8.6
    39         -Returns information about the class, \fIclass\fR. The \fIsubcommand\fRs are
    40         -described in \fBCLASS INTROSPECTION\fR below.
    41         -.VE 8.6
           33  +.
           34  +Returns information about the class named \fIclass\fR.
           35  +See \fBCLASS INTROSPECTION\fR below.
    42     36   .TP
    43     37   \fBinfo cmdcount\fR
    44     38   .
    45         -Returns a count of the total number of commands that have been invoked
    46         -in this interpreter.
           39  +Returns the total number of commands evaluated in this interpreter.
           40  +.TP
           41  +\fBinfo cmdtype \fIcommandName\fR
           42  +.VS TIP426
           43  +Returns a the type of the command named \fIcommandName\fR.
           44  +Built-in types are:
           45  +.RS
           46  +.IP \fBalias\fR
           47  +\fIcommandName\fR was created by \fBinterp alias\fR.
           48  +In a safe interpreter an alias is only visible if both the alias and the
           49  +target are visible.
           50  +.IP \fBcoroutine\fR
           51  +\fIcommandName\fR was created by \fBcoroutine\fR.
           52  +.IP \fBensemble\fR
           53  +\fIcommandName\fR was created by \fBnamespace ensemble\fR.
           54  +.IP \fBimport\fR
           55  +\fIcommandName\fR was created by \fBnamespace import\fR.
           56  +.IP \fBnative\fR
           57  +\fIcommandName\fR was created by the \fBTcl_CreateObjProc\fR
           58  +interface directly without further registration of the type of command.
           59  +.IP \fBobject\fR
           60  +\fIcommandName\fR is the public command that represents an
           61  +instance of \fBoo::object\fR or one of its subclasses.
           62  +.IP \fBprivateObject\fR
           63  +\fIcommandName\fR is the private command, \fBmy\fR by default,
           64  +that represents an instance of \fBoo::object\fR or one of its subclasses.
           65  +.IP \fBproc\fR
           66  +\fIcommandName\fR was created by \fBproc\fR.
           67  +.IP \fBslave\fR
           68  +\fIcommandName\fR was created by \fBinterp create\fR.
           69  +.IP \fBzlibStream\fR
           70  +\fIcommandName\fR was created by \fBzlib stream\fR.
           71  +.PP
           72  +Other types may be also registered as well.  See \fBTcl_RegisterCommandTypeName\fR.
           73  +.RE
           74  +.VE TIP426
    47     75   .TP
    48     76   \fBinfo commands \fR?\fIpattern\fR?
    49     77   .
    50         -If \fIpattern\fR is not specified,
    51         -returns a list of names of all the Tcl commands visible
    52         -(i.e. executable without using a qualified name) to the current namespace,
    53         -including both the built-in commands written in C and
    54         -the command procedures defined using the \fBproc\fR command.
    55         -If \fIpattern\fR is specified,
    56         -only those names matching \fIpattern\fR are returned.
    57         -Matching is determined using the same rules as for \fBstring match\fR.
    58         -\fIpattern\fR can be a qualified name like \fBFoo::print*\fR.
    59         -That is, it may specify a particular namespace
    60         -using a sequence of namespace names separated by double colons (\fB::\fR),
    61         -and may have pattern matching special characters
    62         -at the end to specify a set of commands in that namespace.
    63         -If \fIpattern\fR is a qualified name,
    64         -the resulting list of command names has each one qualified with the name
    65         -of the specified namespace, and only the commands defined in the named
    66         -namespace are returned.
    67         -.\" Technically, most of this hasn't changed; that's mostly just the
    68         -.\" way it always worked. Hardly anyone knew that though.
           78  +Returns the names of all commands visible in the current namespace.  If
           79  +\fIpattern\fR is given, returns only those names that match according to
           80  +\fBstring match\fR.  Only the last component of \fIpattern\fR is a pattern.
           81  +Other components identify a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
           82  +\fBnamespace\fR(n) documentation.
    69     83   .TP
    70     84   \fBinfo complete \fIcommand\fR
    71     85   .
    72         -Returns 1 if \fIcommand\fR is a complete Tcl command in the sense of
    73         -having no unclosed quotes, braces, brackets or array element names.
    74         -If the command does not appear to be complete then 0 is returned.
    75         -This command is typically used in line-oriented input environments
    76         -to allow users to type in commands that span multiple lines;  if the
    77         -command is not complete, the script can delay evaluating it until additional
    78         -lines have been typed to complete the command.
           86  +Returns 1 if \fIcommand\fR is a complete command, and \fB0\fR otherwise.
           87  +Typically used in line-oriented input environments
           88  +to allow users to type in commands that span multiple lines.
    79     89   .TP
    80     90   \fBinfo coroutine\fR
    81         -.VS 8.6
    82         -Returns the name of the currently executing \fBcoroutine\fR, or the empty
    83         -string if either no coroutine is currently executing, or the current coroutine
    84         -has been deleted (but has not yet returned or yielded since deletion).
    85         -.VE 8.6
           91  +.
           92  +Returns the name of the current \fBcoroutine\fR, or the empty
           93  +string if there is no current coroutine or the current coroutine
           94  +has been deleted.
    86     95   .TP
    87         -\fBinfo default \fIprocname arg varname\fR
           96  +\fBinfo default \fIprocname parameter varname\fR
    88     97   .
    89         -\fIProcname\fR must be the name of a Tcl command procedure and \fIarg\fR
    90         -must be the name of an argument to that procedure.  If \fIarg\fR
    91         -does not have a default value then the command returns \fB0\fR.
    92         -Otherwise it returns \fB1\fR and places the default value of \fIarg\fR
    93         -into variable \fIvarname\fR.
           98  +If the parameter \fIparameter\fR for the procedure named \fIprocname\fR has a
           99  +default value, stores that value in \fIvarname\fR and returns \fB1\fR.
          100  +Otherwise, returns \fB0\fR.
    94    101   .TP
    95    102   \fBinfo errorstack \fR?\fIinterp\fR?
    96         -.VS 8.6
    97         -Returns, in a form that is programmatically easy to parse, the function names
    98         -and arguments at each level from the call stack of the last error in the given
    99         -\fIinterp\fR, or in the current one if not specified.
          103  +.
          104  +Returns a description of the active command at each level for the
          105  +last error in the current interpreter, or in the interpreter named
          106  +\fIinterp\fR if given.
   100    107   .RS
   101    108   .PP
   102         -This form is an even-sized list alternating tokens and parameters. Tokens are
          109  +The description is a dictionary of tokens and parameters. Tokens are
   103    110   currently either \fBCALL\fR, \fBUP\fR, or \fBINNER\fR, but other values may be
   104         -introduced in the future. \fBCALL\fR indicates a procedure call, and its
          111  +introduced in the future. \fBCALL\fR indicates a command call, and its
   105    112   parameter is the corresponding \fBinfo level\fR \fB0\fR. \fBUP\fR indicates a
   106    113   shift in variable frames generated by \fBuplevel\fR or similar, and applies to
   107    114   the previous \fBCALL\fR item. Its parameter is the level offset. \fBINNER\fR
   108    115   identifies the
   109    116   .QW "inner context" ,
   110    117   which is the innermost atomic command or bytecode instruction that raised the
   111    118   error, along with its arguments when available. While \fBCALL\fR and \fBUP\fR
   112         -allow to follow complex call paths, \fBINNER\fR homes in on the offending
   113         -operation in the innermost procedure call, even going to sub-expression
          119  +provide a trail of the call path, \fBINNER\fR provides details of the offending
          120  +operation in the innermost procedure call, even to sub-expression
   114    121   granularity.
   115    122   .PP
   116    123   This information is also present in the \fB\-errorstack\fR entry of the
   117    124   options dictionary returned by 3-argument \fBcatch\fR; \fBinfo errorstack\fR
   118    125   is a convenient way of retrieving it for uncaught errors at top-level in an
   119         -interactive \fBtclsh\fR.
          126  +interactive \fBinterpreter\fR.
   120    127   .RE
   121         -.VE 8.6
   122    128   .TP
   123    129   \fBinfo exists \fIvarName\fR
   124    130   .
   125         -Returns \fB1\fR if the variable named \fIvarName\fR exists in the
   126         -current context (either as a global or local variable) and has been
   127         -defined by being given a value, returns \fB0\fR otherwise.
          131  +Returns \fB1\fR if a variable named \fIvarName\fR is visible and has been
          132  +defined, and \fB0\fR otherwise.
   128    133   .TP
   129         -\fBinfo frame\fR ?\fInumber\fR?
          134  +\fBinfo frame\fR ?\fIdepth\fR?
   130    135   .
   131         -This command provides access to all frames on the stack, even those
   132         -hidden from \fBinfo level\fR. If \fInumber\fR is not specified, this
   133         -command returns a number giving the frame level of the command. This
   134         -is 1 if the command is invoked at top-level. If \fInumber\fR is
   135         -specified, then the result is a dictionary containing the location
   136         -information for the command at the \fInumber\fRed level on the stack.
          136  +Returns the depth of the call to \fBinfo frame\fR itself.  Otherwise, returns a
          137  +dictionary describing the active command at the \fIdepth\fR, which counts all
          138  +commands visible to \fBinfo level\fR, plus commands that don't create a new
          139  +level, such as \fBeval\fR, \fBsource\fR, or \fIuplevel\fR. The frame depth is
          140  +always greater than the current level.
   137    141   .RS
   138    142   .PP
   139         -If \fInumber\fR is positive (> 0) then it selects a particular stack
   140         -level (1 refers to the outer-most active command, 2 to the command it
   141         -called, and so on, up to the current frame level which refers to
   142         -\fBinfo frame\fR itself); otherwise it gives a level relative to the
   143         -current command (0 refers to the current command, i.e., \fBinfo
   144         -frame\fR itself, -1 to its caller, and so on).
          143  +If \fIdepth\fR is greater than \fB0\fR it is the frame at that depth.  Otherwise
          144  +it is the number of frames up from the current frame.
   145    145   .PP
   146         -This is similar to how \fBinfo level\fR works, except that this
   147         -subcommand reports all frames, like \fBsource\fRd scripts,
   148         -\fBeval\fRs, \fBuplevel\fRs, etc.
   149         -.PP
   150         -Note that for nested commands, like
          146  +As with \fBinfo level\fR and error traces, for nested commands like
   151    147   .QW "foo [bar [x]]" ,
   152    148   only
   153    149   .QW x
   154         -will be seen by an \fBinfo frame\fR invoked within
          150  +is seen by \fBinfo frame\fR invoked within
   155    151   .QW x .
   156         -This is the same as for \fBinfo level\fR and error stack traces.
   157    152   .PP
   158         -The result dictionary may contain the keys listed below, with the
   159         -specified meanings for their values:
          153  +The dictionary may contain the following keys:
   160    154   .TP
   161    155   \fBtype\fR
   162    156   .
   163         -This entry is always present and describes the nature of the location
   164         -for the command. The recognized values are \fBsource\fR, \fBproc\fR,
          157  +Always present.  Possible values are \fBsource\fR, \fBproc\fR,
   165    158   \fBeval\fR, and \fBprecompiled\fR.
   166    159   .RS
   167    160   .TP
   168    161   \fBsource\fR\0\0\0\0\0\0\0\0
   169    162   .
   170         -means that the command is found in a script loaded by the \fBsource\fR
          163  +A script loaded via the \fBsource\fR
   171    164   command.
   172    165   .TP
   173    166   \fBproc\fR\0\0\0\0\0\0\0\0
   174    167   .
   175         -means that the command is found in dynamically created procedure body.
          168  +The body of a procedure that could not be traced back to a
          169  +line in a particular script.
   176    170   .TP
   177    171   \fBeval\fR\0\0\0\0\0\0\0\0
   178    172   .
   179         -means that the command is executed by \fBeval\fR or \fBuplevel\fR.
          173  +The body of a script provided to \fBeval\fR or \fBuplevel\fR.
   180    174   .TP
   181    175   \fBprecompiled\fR\0\0\0\0\0\0\0\0
   182    176   .
   183         -means that the command is found in a pre-compiled script (loadable by
   184         -the package \fBtbcload\fR), and no further information will be
   185         -available.
          177  +A pre-compiled script (loadable by the package
          178  +\fBtbcload\fR), and no further information is available.
   186    179   .RE
   187    180   .TP
   188    181   \fBline\fR
   189    182   .
   190         -This entry provides the number of the line the command is at inside of
   191         -the script it is a part of. This information is not present for type
   192         -\fBprecompiled\fR. For type \fBsource\fR this information is counted
   193         -relative to the beginning of the file, whereas for the last two types
   194         -the line is counted relative to the start of the script.
          183  +The line number of of the command inside its script.  Not available for
          184  +\fBprecompiled\fR commands.  When the type is \fBsource\fR, the line number is
          185  +relative to the beginning of the file, whereas for the last two types it is
          186  +relative to the start of the script.
   195    187   .TP
   196    188   \fBfile\fR
   197    189   .
   198         -This entry is present only for type \fBsource\fR. It provides the
   199         -normalized path of the file the command is in.
          190  +For type \fBsource\fR, provides the normalized path of the file that contains
          191  +the command.
   200    192   .TP
   201    193   \fBcmd\fR
   202    194   .
   203         -This entry provides the string representation of the command. This is
   204         -usually the unsubstituted form, however for commands which are a
   205         -canonically-constructed list (e.g., as produced by the \fBlist\fR command)
   206         -executed by \fBeval\fR it is the substituted form as they have no other
   207         -string representation. Care is taken that the canonicality property of
   208         -the latter is not spoiled.
          195  +The command before substitutions were performed.
   209    196   .TP
   210    197   \fBproc\fR
   211    198   .
   212         -This entry is present only if the command is found in the body of a
   213         -regular Tcl procedure. It then provides the name of that procedure.
          199  +For type \fBprod\fR, the name of the procedure containing the command.
   214    200   .TP
   215    201   \fBlambda\fR
   216    202   .
   217         -This entry is present only if the command is found in the body of an
   218         -anonymous Tcl procedure, i.e. a lambda. It then provides the entire
   219         -definition of the lambda in question.
          203  +For a command in a script evaluated as the body of an unnamed routine via the
          204  +\fBapply\fR command, the definition of that routine.
   220    205   .TP
   221    206   \fBlevel\fR
   222    207   .
   223         -This entry is present only if the queried frame has a corresponding
   224         -frame returned by \fBinfo level\fR. It provides the index of this
   225         -frame, relative to the current level (0 and negative numbers).
          208  +For a frame that corresponds to a level, (to be determined).
   226    209   .PP
   227         -A thing of note is that for procedures statically defined in files the
   228         -locations of commands in their bodies will be reported with type
   229         -\fBsource\fR and absolute line numbers, and not as type
   230         -\fBproc\fR. The same is true for procedures nested in statically
   231         -defined procedures, and literal eval scripts in files or statically
   232         -defined procedures.
          210  +When a command can be traced to its literal definition in some script, e.g.
          211  +procedures nested in statically defined procedures, and literal eval scripts in
          212  +files or statically defined procedures, its type is \fBsource\fR and its
          213  +location is the absolute line number in the script.  Otherwise, its type is
          214  +\fBproc\fR and its location is its line number within the body of the
          215  +procedure.
   233    216   .PP
   234    217   In contrast, procedure definitions and \fBeval\fR within a dynamically
   235    218   \fBeval\fRuated environment count line numbers relative to the start of
   236    219   their script, even if they would be able to count relative to the
   237    220   start of the outer dynamic script. That type of number usually makes
   238    221   more sense.
   239    222   .PP
   240         -A different way of describing this behaviour is that file based
          223  +A different way of describing this behaviour is that file-based
   241    224   locations are tracked as deeply as possible, and where this is not
   242    225   possible the lines are counted based on the smallest possible
   243    226   \fBeval\fR or procedure body, as that scope is usually easier to find
   244    227   than any dynamic outer scope.
   245    228   .PP
   246    229   The syntactic form \fB{*}\fR is handled like \fBeval\fR. I.e. if it
   247    230   is given a literal list argument the system tracks the line number
   248    231   within the list words as well, and otherwise all line numbers are
   249    232   counted relative to the start of each word (smallest scope)
   250    233   .RE
   251    234   .TP
   252    235   \fBinfo functions \fR?\fIpattern\fR?
   253    236   .
   254         -If \fIpattern\fR is not specified, returns a list of all the math
          237  +If \fIpattern\fR is not given, returns a list of all the math
   255    238   functions currently defined.
   256         -If \fIpattern\fR is specified, only those functions whose name matches
   257         -\fIpattern\fR are returned.  Matching is determined using the same
   258         -rules as for \fBstring match\fR.
          239  +If \fIpattern\fR is given, returns only those names that match
          240  +\fIpattern\fR according to \fBstring match\fR.
   259    241   .TP
   260    242   \fBinfo globals \fR?\fIpattern\fR?
   261    243   .
   262         -If \fIpattern\fR is not specified, returns a list of all the names
          244  +If \fIpattern\fR is not given, returns a list of all the names
   263    245   of currently-defined global variables.
   264    246   Global variables are variables in the global namespace.
   265         -If \fIpattern\fR is specified, only those names matching \fIpattern\fR
          247  +If \fIpattern\fR is given, only those names matching \fIpattern\fR
   266    248   are returned.  Matching is determined using the same rules as for
   267    249   \fBstring match\fR.
   268    250   .TP
   269    251   \fBinfo hostname\fR
   270    252   .
   271         -Returns the name of the computer on which this invocation is being
   272         -executed.
   273         -Note that this name is not guaranteed to be the fully qualified domain
   274         -name of the host.  Where machines have several different names (as is
          253  +Returns the name of the current host.
          254  +
          255  +This name is not guaranteed to be the fully-qualified domain
          256  +name of the host.  Where machines have several different names, as is
   275    257   common on systems with both TCP/IP (DNS) and NetBIOS-based networking
   276         -installed,) it is the name that is suitable for TCP/IP networking that
          258  +installed, it is the name that is suitable for TCP/IP networking that
   277    259   is returned.
   278    260   .TP
   279         -\fBinfo level\fR ?\fInumber\fR?
          261  +\fBinfo level\fR ?\fIlevel\fR?
   280    262   .
   281         -If \fInumber\fR is not specified, this command returns a number
   282         -giving the stack level of the invoking procedure, or 0 if the
   283         -command is invoked at top-level.  If \fInumber\fR is specified,
   284         -then the result is a list consisting of the name and arguments for the
   285         -procedure call at level \fInumber\fR on the stack.  If \fInumber\fR
   286         -is positive then it selects a particular stack level (1 refers
   287         -to the top-most active procedure, 2 to the procedure it called, and
   288         -so on); otherwise it gives a level relative to the current level
   289         -(0 refers to the current procedure, -1 to its caller, and so on).
   290         -See the \fBuplevel\fR command for more information on what stack
   291         -levels mean.
          263  +If \fInumber\fR is not given, the level this routine was called from.
          264  +Otherwise returns the complete command active at the given level.  If
          265  +\fInumber\fR is greater than \fB0\fR, it is the desired level.  Otherwise, it
          266  +is \fInumber\fR levels up from the current level.  A complete command is the
          267  +words in the command, with all subsitutions performed, meaning that it is a
          268  +list.  See \fBuplevel\fR for more information on levels.
   292    269   .TP
   293    270   \fBinfo library\fR
   294    271   .
   295         -Returns the name of the library directory in which standard Tcl
   296         -scripts are stored.
   297         -This is actually the value of the \fBtcl_library\fR
   298         -variable and may be changed by setting \fBtcl_library\fR.
          272  +Returns the value of \fBtcl_library\fR, which is the name of the library
          273  +directory in which the scripts distributed with Tcl scripts are stored.
   299    274   .TP
   300    275   \fBinfo loaded \fR?\fIinterp\fR? ?\fIpackage\fR?
   301    276   .
   302         -Returns the filename loaded as part of \fIpackage\fR. If \fIpackage\fR
   303         -is not specified, returns a list describing all of the packages
   304         -that have been loaded into \fIinterp\fR with the \fBload\fR command.
   305         -Each list element is a sub-list with two elements consisting of the
   306         -name of the file from which the package was loaded and the name of
   307         -the package.
   308         -For statically-loaded packages the file name will be an empty string.
   309         -If \fIinterp\fR is omitted then information is returned for all packages
   310         -loaded in any interpreter in the process.
   311         -To get a list of just the packages in the current interpreter, specify
   312         -an empty string for the \fIinterp\fR argument.
          277  +Returns the name of each file loaded in \fIinterp\fR va \fBload\fR as part of
          278  +\fIpackage\fR .  If \fIpackage\fR is not given, returns a list where each item
          279  +is the name of the loaded file and the name of the package for which the file
          280  +was loaded.  For a statically-loaded package the name of the file is the empty
          281  +string.  For \fInterp\fR, the empty string is the current interpreter.
   313    282   .TP
   314    283   \fBinfo locals \fR?\fIpattern\fR?
   315    284   .
   316         -If \fIpattern\fR is not specified, returns a list of all the names
   317         -of currently-defined local variables, including arguments to the
   318         -current procedure, if any.
   319         -Variables defined with the \fBglobal\fR, \fBupvar\fR  and
   320         -\fBvariable\fR commands will not be returned.
   321         -If \fIpattern\fR is specified, only those names matching \fIpattern\fR
   322         -are returned.  Matching is determined using the same rules as for
   323         -\fBstring match\fR.
          285  +If \fIpattern\fR is given, returns the name of each local variable matching
          286  +\fIpattern\fR according to \fBstring match\fR.  Otherwise, returns the name of
          287  +each local variable.  A variables defined with the \fBglobal\fR, \fBupvar\fR or
          288  +\fBvariable\fR is not local.
          289  +
   324    290   .TP
   325    291   \fBinfo nameofexecutable\fR
   326    292   .
   327         -Returns the full path name of the binary file from which the application
   328         -was invoked.  If Tcl was unable to identify the file, then an empty
   329         -string is returned.
          293  +Returns the absolute pathname of the program for the current interpreter.  If
          294  +such a file can not be identified an empty string is returned.
   330    295   .TP
   331    296   \fBinfo object\fI subcommand object\fR ?\fIarg ...\fR
   332         -.VS 8.6
   333         -Returns information about the object, \fIobject\fR. The \fIsubcommand\fRs are
   334         -described in \fBOBJECT INTROSPECTION\fR below.
   335         -.VE 8.6
          297  +.
          298  +Returns information about the object named \fIobject\fR. \fIsubcommand\fR is
          299  +described \fBOBJECT INTROSPECTION\fR below.
   336    300   .TP
   337    301   \fBinfo patchlevel\fR
   338    302   .
   339         -Returns the value of the global variable \fBtcl_patchLevel\fR, which holds
   340         -the exact version of the Tcl library by default.
          303  +Returns the value of the global variable \fBtcl_patchLevel\fR, in which the
          304  +exact version of the Tcl library initially stored.
   341    305   .TP
   342    306   \fBinfo procs \fR?\fIpattern\fR?
   343    307   .
   344         -If \fIpattern\fR is not specified, returns a list of all the
   345         -names of Tcl command procedures in the current namespace.
   346         -If \fIpattern\fR is specified,
   347         -only those procedure names in the current namespace
   348         -matching \fIpattern\fR are returned.
   349         -Matching is determined using the same rules as for
   350         -\fBstring match\fR.
   351         -If \fIpattern\fR contains any namespace separators, they are used to
   352         -select a namespace relative to the current namespace (or relative to
   353         -the global namespace if \fIpattern\fR starts with \fB::\fR) to match
   354         -within; the matching pattern is taken to be the part after the last
   355         -namespace separator.
          308  +Returns the names of all visible procedures. If \fIpattern\fR is given, returns
          309  +only those names that match according to \fBstring match\fR.  Only the final
          310  +component in \fIpattern\fR is actually considered a pattern.  Any qualifying
          311  +components simply select a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
          312  +\fBnamespace\fR(n) documentation.
   356    313   .TP
   357    314   \fBinfo script\fR ?\fIfilename\fR?
   358    315   .
   359         -If a Tcl script file is currently being evaluated (i.e. there is a
   360         -call to \fBTcl_EvalFile\fR active or there is an active invocation
   361         -of the \fBsource\fR command), then this command returns the name
   362         -of the innermost file being processed.  If \fIfilename\fR is specified,
   363         -then the return value of this command will be modified for the
   364         -duration of the active invocation to return that name.  This is
   365         -useful in virtual file system applications.
   366         -Otherwise the command returns an empty string.
          316  +Returns the pathname of the innermost script currently being evaluated, or the
          317  +empty string if no pathname can be determined.  If \fIfilename\fR is given,
          318  +sets the return value of any future calls to \fBinfo script\fR for the duration
          319  +of the innermost active script.  This is useful in virtual file system
          320  +applications.
   367    321   .TP
   368    322   \fBinfo sharedlibextension\fR
   369    323   .
   370         -Returns the extension used on this platform for the names of files
   371         -containing shared libraries (for example, \fB.so\fR under Solaris).
   372         -If shared libraries are not supported on this platform then an empty
   373         -string is returned.
          324  +Returns the extension used on this platform for names of shared libraries, e.g.
          325  +\fB.so\fR under Solaris.  Returns the empty string if shared libraries are not
          326  +supported on this platform.
   374    327   .TP
   375    328   \fBinfo tclversion\fR
   376    329   .
   377         -Returns the value of the global variable \fBtcl_version\fR, which holds the
   378         -major and minor version of the Tcl library by default.
          330  +Returns the value of the global variable \fBtcl_version\fR, in which the
          331  +major and minor version of the Tcl library are stored.
   379    332   .TP
   380    333   \fBinfo vars\fR ?\fIpattern\fR?
   381    334   .
   382         -If \fIpattern\fR is not specified,
   383         -returns a list of all the names of currently-visible variables.
   384         -This includes locals and currently-visible globals.
   385         -If \fIpattern\fR is specified, only those names matching \fIpattern\fR
   386         -are returned.  Matching is determined using the same rules as for
   387         -\fBstring match\fR.
   388         -\fIpattern\fR can be a qualified name like \fBFoo::option*\fR.
   389         -That is, it may specify a particular namespace
   390         -using a sequence of namespace names separated by double colons (\fB::\fR),
   391         -and may have pattern matching special characters
   392         -at the end to specify a set of variables in that namespace.
   393         -If \fIpattern\fR is a qualified name,
   394         -the resulting list of variable names
   395         -has each matching namespace variable qualified with the name
   396         -of its namespace.
   397         -Note that a currently-visible variable may not yet
   398         -.QW exist
   399         -if it has not
   400         -been set (e.g. a variable declared but not set by \fBvariable\fR).
          335  +If \fIpattern\fR is not given, returns the names of all visible variables.  If
          336  +\fIpattern\fR is given, returns only those names that match according to
          337  +\fBstring match\fR.  Only the last component of \fIpattern\fR is a pattern.
          338  +Other components identify a namespace.  See \fBNAMESPACE RESOLUTION\fR in the
          339  +\fBnamespace\fR(n) documentation.  When \fIpattern\fR is a qualified name,
          340  +results are fully qualified.
          341  +
          342  +A variable that has declared but not yet defined is included in the results.
   401    343   .SS "CLASS INTROSPECTION"
   402         -.VS 8.6
   403    344   .PP
   404    345   The following \fIsubcommand\fR values are supported by \fBinfo class\fR:
   405         -.VE 8.6
   406    346   .TP
   407    347   \fBinfo class call\fI class method\fR
   408         -.VS
          348  +.
   409    349   Returns a description of the method implementations that are used to provide a
   410    350   stereotypical instance of \fIclass\fR's implementation of \fImethod\fR
   411    351   (stereotypical instances being objects instantiated by a class without having
   412    352   any object-specific definitions added). This consists of a list of lists of
   413    353   four elements, where each sublist consists of a word that describes the
   414    354   general type of method implementation (being one of \fBmethod\fR for an
   415         -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
          355  +ordinary method, \fBfilter\fR for an applied filter,
          356  +.VS TIP500
          357  +\fBprivate\fR for a private method,
          358  +.VE TIP500
          359  +and \fBunknown\fR for a
   416    360   method that is invoked as part of unknown method handling), a word giving the
   417    361   name of the particular method invoked (which is always the same as
   418    362   \fImethod\fR for the \fBmethod\fR type, and
   419    363   .QW \fBunknown\fR
   420    364   for the \fBunknown\fR type), a word giving the fully qualified name of the
   421    365   class that defined the method, and a word describing the type of method
   422    366   implementation (see \fBinfo class methodtype\fR).
   423    367   .RS
   424    368   .PP
   425    369   Note that there is no inspection of whether the method implementations
   426         -actually use \fBnext\fR to transfer control along the call chain.
          370  +actually use \fBnext\fR to transfer control along the call chain,
          371  +.VS TIP500
          372  +and the call chains that this command files do not actually contain private
          373  +methods.
          374  +.VE TIP500
   427    375   .RE
   428         -.VE 8.6
   429    376   .TP
   430    377   \fBinfo class constructor\fI class\fR
   431         -.VS 8.6
          378  +.
   432    379   This subcommand returns a description of the definition of the constructor of
   433    380   class \fIclass\fR. The definition is described as a two element list; the first
   434    381   element is the list of arguments to the constructor in a form suitable for
   435    382   passing to another call to \fBproc\fR or a method definition, and the second
   436    383   element is the body of the constructor. If no constructor is present, this
   437    384   returns the empty list.
   438         -.VE 8.6
   439    385   .TP
   440    386   \fBinfo class definition\fI class method\fR
   441         -.VS 8.6
          387  +.
   442    388   This subcommand returns a description of the definition of the method named
   443    389   \fImethod\fR of class \fIclass\fR. The definition is described as a two element
   444    390   list; the first element is the list of arguments to the method in a form
   445    391   suitable for passing to another call to \fBproc\fR or a method definition, and
   446    392   the second element is the body of the method.
   447         -.VE 8.6
          393  +.TP
          394  +\fBinfo class definitionnamespace\fI class\fR ?\fIkind\fR?
          395  +.VS TIP524
          396  +This subcommand returns the definition namespace for \fIkind\fR definitions of
          397  +the class \fIclass\fR; the definition namespace only affects the instances of
          398  +\fIclass\fR, not \fIclass\fR itself. The \fIkind\fR can be either
          399  +\fB\-class\fR to return the definition namespace used for \fBoo::define\fR, or
          400  +\fB\-instance\fR to return the definition namespace used for
          401  +\fBoo::objdefine\fR; the \fB\-class\fR kind is default (though this is only
          402  +actually useful on classes that are subclasses of \fBoo::class\fR).
          403  +.RS
          404  +.PP
          405  +If \fIclass\fR does not provide a definition namespace of the given kind,
          406  +this command returns the empty string. In those circumstances, the
          407  +\fBoo::define\fR and \fBoo::objdefine\fR commands look up which definition
          408  +namespace to use using the class inheritance hierarchy.
          409  +.RE
          410  +.VE TIP524
   448    411   .TP
   449    412   \fBinfo class destructor\fI class\fR
   450         -.VS 8.6
          413  +.
   451    414   This subcommand returns the body of the destructor of class \fIclass\fR. If no
   452    415   destructor is present, this returns the empty string.
   453         -.VE 8.6
   454    416   .TP
   455    417   \fBinfo class filters\fI class\fR
   456         -.VS 8.6
          418  +.
   457    419   This subcommand returns the list of filter methods set on the class.
   458         -.VE 8.6
   459    420   .TP
   460    421   \fBinfo class forward\fI class method\fR
   461         -.VS 8.6
          422  +.
   462    423   This subcommand returns the argument list for the method forwarding called
   463    424   \fImethod\fR that is set on the class called \fIclass\fR.
   464         -.VE 8.6
   465    425   .TP
   466    426   \fBinfo class instances\fI class\fR ?\fIpattern\fR?
   467         -.VS 8.6
          427  +.
   468    428   This subcommand returns a list of instances of class \fIclass\fR. If the
   469    429   optional \fIpattern\fR argument is present, it constrains the list of returned
   470    430   instances to those that match it according to the rules of \fBstring match\fR.
   471         -.VE 8.6
   472    431   .TP
   473    432   \fBinfo class methods\fI class\fR ?\fIoptions...\fR?
   474         -.VS 8.6
          433  +.
   475    434   This subcommand returns a list of all public (i.e. exported) methods of the
   476    435   class called \fIclass\fR. Any of the following \fIoption\fRs may be
   477         -specified, controlling exactly which method names are returned:
          436  +given, controlling exactly which method names are returned:
   478    437   .RS
   479         -.VE 8.6
   480    438   .TP
   481    439   \fB\-all\fR
   482         -.VS 8.6
   483         -If the \fB\-all\fR flag is given, the list of methods will include those
          440  +.
          441  +If the \fB\-all\fR flag is given,
          442  +.VS TIP500
          443  +and the \fB\-scope\fR flag is not given,
          444  +.VE TIP500
          445  +the list of methods will include those
   484    446   methods defined not just by the class, but also by the class's superclasses
   485    447   and mixins.
   486         -.VE 8.6
   487    448   .TP
   488    449   \fB\-private\fR
   489         -.VS 8.6
   490         -If the \fB\-private\fR flag is given, the list of methods will also include
   491         -the private (i.e. non-exported) methods of the class (and superclasses and
          450  +.
          451  +If the \fB\-private\fR flag is given,
          452  +.VS TIP500
          453  +and the \fB\-scope\fR flag is not given,
          454  +.VE TIP500
          455  +the list of methods will also include
          456  +the non-exported methods of the class (and superclasses and
   492    457   mixins, if \fB\-all\fR is also given).
          458  +.VS TIP500
          459  +Note that this naming is an unfortunate clash with true private methods; this
          460  +option name is retained for backward compatibility.
          461  +.VE TIP500
          462  +.TP
          463  +\fB\-scope\fI scope\fR
          464  +.VS TIP500
          465  +Returns a list of all methods on \fIclass\fR that have the given visibility
          466  +\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
          467  +\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
          468  +.RS
          469  +.IP \fBpublic\fR 3
          470  +Only methods with \fIpublic\fR scope (i.e., callable from anywhere by any instance
          471  +of this class) are to be returned.
          472  +.IP \fBunexported\fR 3
          473  +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
          474  +be returned.
          475  +.IP \fBprivate\fR 3
          476  +Only methods with \fIprivate\fR scope (i.e., only callable from within this class's
          477  +methods) are to be returned.
   493    478   .RE
   494         -.VE 8.6
          479  +.VE TIP500
          480  +.RE
   495    481   .TP
   496    482   \fBinfo class methodtype\fI class method\fR
   497         -.VS 8.6
          483  +.
   498    484   This subcommand returns a description of the type of implementation used for
   499    485   the method named \fImethod\fR of class \fIclass\fR. When the result is
   500    486   \fBmethod\fR, further information can be discovered with \fBinfo class
   501    487   definition\fR, and when the result is \fBforward\fR, further information can
   502    488   be discovered with \fBinfo class forward\fR.
   503         -.VE 8.6
   504    489   .TP
   505    490   \fBinfo class mixins\fI class\fR
   506         -.VS 8.6
          491  +.
   507    492   This subcommand returns a list of all classes that have been mixed into the
   508    493   class named \fIclass\fR.
   509         -.VE 8.6
   510    494   .TP
   511    495   \fBinfo class subclasses\fI class\fR ?\fIpattern\fR?
   512         -.VS 8.6
          496  +.
   513    497   This subcommand returns a list of direct subclasses of class \fIclass\fR. If
   514    498   the optional \fIpattern\fR argument is present, it constrains the list of
   515    499   returned classes to those that match it according to the rules of
   516    500   \fBstring match\fR.
   517         -.VE 8.6
   518    501   .TP
   519    502   \fBinfo class superclasses\fI class\fR
   520         -.VS 8.6
          503  +.
   521    504   This subcommand returns a list of direct superclasses of class \fIclass\fR in
   522    505   inheritance precedence order.
   523         -.VE 8.6
   524    506   .TP
   525         -\fBinfo class variables\fI class\fR
   526         -.VS 8.6
          507  +\fBinfo class variables\fI class\fR ?\fB\-private\fR?
          508  +.
   527    509   This subcommand returns a list of all variables that have been declared for
   528    510   the class named \fIclass\fR (i.e. that are automatically present in the
   529    511   class's methods, constructor and destructor).
          512  +.VS TIP500
          513  +If the \fB\-private\fR option is given, this lists the private variables
          514  +declared instead.
          515  +.VE TIP500
   530    516   .SS "OBJECT INTROSPECTION"
   531    517   .PP
   532    518   The following \fIsubcommand\fR values are supported by \fBinfo object\fR:
   533         -.VE 8.6
   534    519   .TP
   535    520   \fBinfo object call\fI object method\fR
   536         -.VS 8.6
          521  +.
   537    522   Returns a description of the method implementations that are used to provide
   538    523   \fIobject\fR's implementation of \fImethod\fR.  This consists of a list of
   539    524   lists of four elements, where each sublist consists of a word that describes
   540    525   the general type of method implementation (being one of \fBmethod\fR for an
   541         -ordinary method, \fBfilter\fR for an applied filter, and \fBunknown\fR for a
          526  +ordinary method, \fBfilter\fR for an applied filter,
          527  +.VS TIP500
          528  +\fBprivate\fR for a private method,
          529  +.VE TIP500
          530  +and \fBunknown\fR for a
   542    531   method that is invoked as part of unknown method handling), a word giving the
   543    532   name of the particular method invoked (which is always the same as
   544    533   \fImethod\fR for the \fBmethod\fR type, and
   545    534   .QW \fBunknown\fR
   546    535   for the \fBunknown\fR type), a word giving what defined the method (the fully
   547    536   qualified name of the class, or the literal string \fBobject\fR if the method
   548    537   implementation is on an instance), and a word describing the type of method
   549    538   implementation (see \fBinfo object methodtype\fR).
   550    539   .RS
   551    540   .PP
   552    541   Note that there is no inspection of whether the method implementations
   553         -actually use \fBnext\fR to transfer control along the call chain.
          542  +actually use \fBnext\fR to transfer control along the call chain,
          543  +.VS TIP500
          544  +and the call chains that this command files do not actually contain private
          545  +methods.
          546  +.VE TIP500
   554    547   .RE
   555         -.VE 8.6
   556    548   .TP
   557    549   \fBinfo object class\fI object\fR ?\fIclassName\fR?
   558         -.VS 8.6
   559         -If \fIclassName\fR is unspecified, this subcommand returns class of the
          550  +.
          551  +If \fIclassName\fR is not given, this subcommand returns class of the
   560    552   \fIobject\fR object. If \fIclassName\fR is present, this subcommand returns a
   561    553   boolean value indicating whether the \fIobject\fR is of that class.
   562         -.VE 8.6
          554  +.TP
          555  +\fBinfo object creationid\fI object\fR
          556  +.VS TIP500
          557  +Returns the unique creation identifier for the \fIobject\fR object. This
          558  +creation identifier is unique to the object (within a Tcl interpreter) and
          559  +cannot be controlled at object creation time or altered afterwards.
          560  +.RS
          561  +.PP
          562  +\fIImplementation note:\fR the creation identifier is used to generate unique
          563  +identifiers associated with the object, especially for private variables.
          564  +.RE
          565  +.VE TIP500
   563    566   .TP
   564    567   \fBinfo object definition\fI object method\fR
   565         -.VS 8.6
          568  +.
   566    569   This subcommand returns a description of the definition of the method named
   567    570   \fImethod\fR of object \fIobject\fR. The definition is described as a two
   568    571   element list; the first element is the list of arguments to the method in a
   569    572   form suitable for passing to another call to \fBproc\fR or a method definition,
   570    573   and the second element is the body of the method.
   571         -.VE 8.6
   572    574   .TP
   573    575   \fBinfo object filters\fI object\fR
   574         -.VS 8.6
          576  +.
   575    577   This subcommand returns the list of filter methods set on the object.
   576         -.VE 8.6
   577    578   .TP
   578    579   \fBinfo object forward\fI object method\fR
   579         -.VS 8.6
          580  +.
   580    581   This subcommand returns the argument list for the method forwarding called
   581    582   \fImethod\fR that is set on the object called \fIobject\fR.
   582         -.VE 8.6
   583    583   .TP
   584    584   \fBinfo object isa\fI category object\fR ?\fIarg\fR?
   585         -.VS 8.6
          585  +.
   586    586   This subcommand tests whether an object belongs to a particular category,
   587    587   returning a boolean value that indicates whether the \fIobject\fR argument
   588    588   meets the criteria for the category. The supported categories are:
   589         -.VE 8.6
   590    589   .RS
   591    590   .TP
   592    591   \fBinfo object isa class\fI object\fR
   593         -.VS 8.6
          592  +.
   594    593   This returns whether \fIobject\fR is a class (i.e. an instance of
   595    594   \fBoo::class\fR or one of its subclasses).
   596         -.VE 8.6
   597    595   .TP
   598    596   \fBinfo object isa metaclass\fI object\fR
   599         -.VS 8.6
          597  +.
   600    598   This returns whether \fIobject\fR is a class that can manufacture classes
   601    599   (i.e. is \fBoo::class\fR or a subclass of it).
   602         -.VE 8.6
   603    600   .TP
   604    601   \fBinfo object isa mixin\fI object class\fR
   605         -.VS 8.6
          602  +.
   606    603   This returns whether \fIclass\fR is directly mixed into \fIobject\fR.
   607         -.VE 8.6
   608    604   .TP
   609    605   \fBinfo object isa object\fI object\fR
   610         -.VS 8.6
          606  +.
   611    607   This returns whether \fIobject\fR really is an object.
   612         -.VE 8.6
   613    608   .TP
   614    609   \fBinfo object isa typeof\fI object class\fR
   615         -.VS 8.6
          610  +.
   616    611   This returns whether \fIclass\fR is the type of \fIobject\fR (i.e. whether
   617    612   \fIobject\fR is an instance of \fIclass\fR or one of its subclasses, whether
   618    613   direct or indirect).
   619    614   .RE
   620         -.VE 8.6
   621    615   .TP
   622    616   \fBinfo object methods\fI object\fR ?\fIoption...\fR?
   623         -.VS 8.6
          617  +.
   624    618   This subcommand returns a list of all public (i.e. exported) methods of the
   625    619   object called \fIobject\fR. Any of the following \fIoption\fRs may be
   626         -specified, controlling exactly which method names are returned:
          620  +given, controlling exactly which method names are returned:
   627    621   .RS
   628         -.VE 8.6
   629    622   .TP
   630    623   \fB\-all\fR
   631         -.VS 8.6
   632         -If the \fB\-all\fR flag is given, the list of methods will include those
          624  +.
          625  +If the \fB\-all\fR flag is given,
          626  +.VS TIP500
          627  +and the \fB\-scope\fR flag is not given,
          628  +.VE TIP500
          629  +the list of methods will include those
   633    630   methods defined not just by the object, but also by the object's class and
   634    631   mixins, plus the superclasses of those classes.
   635         -.VE 8.6
   636    632   .TP
   637    633   \fB\-private\fR
   638         -.VS 8.6
   639         -If the \fB\-private\fR flag is given, the list of methods will also include
   640         -the private (i.e. non-exported) methods of the object (and classes, if
          634  +.
          635  +If the \fB\-private\fR flag is given,
          636  +.VS TIP500
          637  +and the \fB\-scope\fR flag is not given,
          638  +.VE TIP500
          639  +the list of methods will also include
          640  +the non-exported methods of the object (and classes, if
   641    641   \fB\-all\fR is also given).
          642  +.VS TIP500
          643  +Note that this naming is an unfortunate clash with true private methods; this
          644  +option name is retained for backward compatibility.
          645  +.VE TIP500
          646  +.TP
          647  +\fB\-scope\fI scope\fR
          648  +.VS TIP500
          649  +Returns a list of all methods on \fIobject\fR that have the given visibility
          650  +\fIscope\fR.  When this option is supplied, both the \fB\-all\fR and
          651  +\fB\-private\fR options are ignored. The valid values for \fIscope\fR are:
          652  +.RS
          653  +.IP \fBpublic\fR 3
          654  +Only methods with \fIpublic\fR scope (i.e., callable from anywhere) are to be
          655  +returned.
          656  +.IP \fBunexported\fR 3
          657  +Only methods with \fIunexported\fR scope (i.e., only callable via \fBmy\fR) are to
          658  +be returned.
          659  +.IP \fBprivate\fR 3
          660  +Only methods with \fIprivate\fR scope (i.e., only callable from within this object's
          661  +instance methods) are to be returned.
   642    662   .RE
   643         -.VE 8.6
          663  +.VE TIP500
          664  +.RE
   644    665   .TP
   645    666   \fBinfo object methodtype\fI object method\fR
   646         -.VS 8.6
          667  +.
   647    668   This subcommand returns a description of the type of implementation used for
   648    669   the method named \fImethod\fR of object \fIobject\fR. When the result is
   649    670   \fBmethod\fR, further information can be discovered with \fBinfo object
   650    671   definition\fR, and when the result is \fBforward\fR, further information can
   651    672   be discovered with \fBinfo object forward\fR.
   652         -.VE 8.6
   653    673   .TP
   654    674   \fBinfo object mixins\fI object\fR
   655         -.VS 8.6
          675  +.
   656    676   This subcommand returns a list of all classes that have been mixed into the
   657    677   object named \fIobject\fR.
   658         -.VE 8.6
   659    678   .TP
   660    679   \fBinfo object namespace\fI object\fR
   661         -.VS 8.6
          680  +.
   662    681   This subcommand returns the name of the internal namespace of the object named
   663    682   \fIobject\fR.
   664         -.VE 8.6
   665    683   .TP
   666         -\fBinfo object variables\fI object\fR
   667         -.VS 8.6
          684  +\fBinfo object variables\fI object\fRR ?\fB\-private\fR?
          685  +.
   668    686   This subcommand returns a list of all variables that have been declared for
   669    687   the object named \fIobject\fR (i.e. that are automatically present in the
   670    688   object's methods).
   671         -.VE 8.6
          689  +.VS TIP500
          690  +If the \fB\-private\fR option is given, this lists the private variables
          691  +declared instead.
          692  +.VE TIP500
   672    693   .TP
   673    694   \fBinfo object vars\fI object\fR ?\fIpattern\fR?
   674         -.VS 8.6
          695  +.
   675    696   This subcommand returns a list of all variables in the private namespace of
   676    697   the object named \fIobject\fR. If the optional \fIpattern\fR argument is
   677    698   given, it is a filter (in the syntax of a \fBstring match\fR glob pattern)
   678    699   that constrains the list of variables returned. Note that this is different
   679    700   from the list returned by \fBinfo object variables\fR; that can include
   680    701   variables that are currently unset, whereas this can include variables that
   681    702   are not automatically included by any of \fIobject\fR's methods (or those of
   682    703   its class, superclasses or mixins).
   683         -.VE 8.6
   684    704   .SH EXAMPLES
   685    705   .PP
   686    706   This command prints out a procedure suitable for saving in a Tcl
   687    707   script:
   688    708   .PP
   689    709   .CS
   690    710   proc printProc {procName} {
................................................................................
   699    719               lappend formals [list $var]
   700    720           }
   701    721       }
   702    722       puts [lappend result $formals [\fBinfo body\fR $procName]]
   703    723   }
   704    724   .CE
   705    725   .SS "EXAMPLES WITH OBJECTS"
   706         -.VS 8.6
   707    726   .PP
   708    727   Every object necessarily knows what its class is; this information is
   709    728   trivially extractable through introspection:
   710    729   .PP
   711    730   .CS
   712    731   oo::class create c
   713    732   c create o
................................................................................
   720    739   The introspection capabilities can be used to discover what class implements a
   721    740   method and get how it is defined. This procedure illustrates how:
   722    741   .PP
   723    742   .CS
   724    743   proc getDef {obj method} {
   725    744       foreach inf [\fBinfo object call\fR $obj $method] {
   726    745           lassign $inf calltype name locus methodtype
          746  +
   727    747           # Assume no forwards or filters, and hence no $calltype
   728    748           # or $methodtype checks...
          749  +
   729    750           if {$locus eq "object"} {
   730    751               return [\fBinfo object definition\fR $obj $name]
   731    752           } else {
   732    753               return [\fBinfo class definition\fR $locus $name]
   733    754           }
   734    755       }
   735    756       error "no definition for $method"
................................................................................
   744    765   .PP
   745    766   .CS
   746    767   proc getDef {obj method} {
   747    768       if {$method in [\fBinfo object methods\fR $obj]} {
   748    769           # Assume no forwards
   749    770           return [\fBinfo object definition\fR $obj $method]
   750    771       }
          772  +
   751    773       set cls [\fBinfo object class\fR $obj]
          774  +
   752    775       while {$method ni [\fBinfo class methods\fR $cls]} {
   753    776           # Assume the simple case
   754    777           set cls [lindex [\fBinfo class superclass\fR $cls] 0]
   755    778           if {$cls eq ""} {
   756    779               error "no definition for $method"
   757    780           }
   758    781       }
          782  +
   759    783       # Assume no forwards
   760    784       return [\fBinfo class definition\fR $cls $method]
   761    785   }
   762    786   .CE
   763         -.VE 8.6
   764    787   .SH "SEE ALSO"
   765         -.VS 8.6
   766    788   global(n), oo::class(n), oo::define(n), oo::object(n), proc(n), self(n),
   767         -.VE 8.6
   768    789   tcl_library(n), tcl_patchLevel(n), tcl_version(n)
   769    790   .SH KEYWORDS
   770    791   command, information, interpreter, introspection, level, namespace,
   771         -.VS 8.6
   772         -object,
   773         -.VE 8.6
   774         -procedure, variable
          792  +object, procedure, variable
   775    793   '\" Local Variables:
   776    794   '\" mode: nroff
   777    795   '\" fill-column: 78
   778    796   '\" End:

Changes to doc/interp.n.

   197    197   \fBinterp\fR \fBdebug \fIpath\fR ?\fB\-frame\fR ?\fIbool\fR??
   198    198   .
   199    199   Controls whether frame-level stack information is captured in the
   200    200   slave interpreter identified by \fIpath\fR.  If no arguments are
   201    201   given, option and current setting are returned.  If \fB\-frame\fR
   202    202   is given, the debug setting is set to the given boolean if provided
   203    203   and the current setting is returned.
   204         -This only effects the output of \fBinfo frame\fR, in that exact
          204  +This only affects the output of \fBinfo frame\fR, in that exact
   205    205   frame-level information for command invocation at the bytecode level
   206    206   is only captured with this setting on.
   207    207   .RS
   208    208   .PP
   209    209   For example, with code like
   210    210   .PP
   211    211   .CS
................................................................................
   232    232   execution of all commands.
   233    233   .PP
   234    234   Note that once it is on, this flag cannot be switched back off: such
   235    235   attempts are silently ignored. This is needed to maintain the
   236    236   consistency of the underlying interpreter's state.
   237    237   .RE
   238    238   .TP
   239         -\fBinterp\fR \fBdelete \fR?\fIpath ...?\fR
          239  +\fBinterp\fR \fBdelete \fR?\fIpath ...\fR?
   240    240   .
   241    241   Deletes zero or more interpreters given by the optional \fIpath\fR
   242    242   arguments, and for each interpreter, it also deletes its slaves. The
   243    243   command also deletes the slave command for each interpreter deleted.
   244    244   For each \fIpath\fR argument, if no interpreter by that name
   245    245   exists, the command raises an error.
   246    246   .TP

Changes to doc/join.n.

    38     38   \fBjoin\fR $data
    39     39        \fB\(-> 1 2 3 4 5 {6 7} 8\fR
    40     40   .CE
    41     41   .SH "SEE ALSO"
    42     42   list(n), lappend(n), split(n)
    43     43   .SH KEYWORDS
    44     44   element, join, list, separator
           45  +'\" Local Variables:
           46  +'\" mode: nroff
           47  +'\" fill-column: 78
           48  +'\" End:

Changes to doc/lappend.n.

    18     18   .SH DESCRIPTION
    19     19   .PP
    20     20   This command treats the variable given by \fIvarName\fR as a list
    21     21   and appends each of the \fIvalue\fR arguments to that list as a separate
    22     22   element, with spaces between elements.
    23     23   If \fIvarName\fR does not exist, it is created as a list with elements
    24     24   given by the \fIvalue\fR arguments.
           25  +.VS TIP508
           26  +If \fIvarName\fR indicate an element that does not exist of an array that has
           27  +a default value set, list that is comprised of the default value with all the
           28  +\fIvalue\fR arguments appended as elements will be stored in the array
           29  +element.
           30  +.VE TIP508
    25     31   \fBLappend\fR is similar to \fBappend\fR except that the \fIvalue\fRs
    26     32   are appended as list elements rather than raw text.
    27     33   This command provides a relatively efficient way to build up
    28     34   large lists.  For example,
    29     35   .QW "\fBlappend a $b\fR"
    30     36   is much more efficient than
    31     37   .QW "\fBset a [concat $a [list $b]]\fR"
................................................................................
    43     49   1 2 3 4 5
    44     50   .CE
    45     51   .SH "SEE ALSO"
    46     52   list(n), lindex(n), linsert(n), llength(n), lset(n),
    47     53   lsort(n), lrange(n)
    48     54   .SH KEYWORDS
    49     55   append, element, list, variable
           56  +.\" Local variables:
           57  +.\" mode: nroff
           58  +.\" fill-column: 78
           59  +.\" End:

Changes to doc/lindex.n.

     9      9   .TH lindex n 8.4 Tcl "Tcl Built-In Commands"
    10     10   .so man.macros
    11     11   .BS
    12     12   '\" Note:  do not modify the .SH NAME line immediately below!
    13     13   .SH NAME
    14     14   lindex \- Retrieve an element from a list
    15     15   .SH SYNOPSIS
    16         -\fBlindex \fIlist ?index ...?\fR
           16  +\fBlindex \fIlist\fR ?\fIindex ...\fR?
    17     17   .BE
    18     18   .SH DESCRIPTION
    19     19   .PP
    20     20   The \fBlindex\fR command accepts a parameter, \fIlist\fR, which
    21     21   it treats as a Tcl list. It also accepts zero or more \fIindices\fR into
    22     22   the list.  The indices may be presented either consecutively on the
    23     23   command line, or grouped in a

Added doc/link.n.

            1  +'\"
            2  +'\" Copyright (c) 2011-2015 Andreas Kupries
            3  +'\" Copyright (c) 2018 Donal K. Fellows
            4  +'\"
            5  +'\" See the file "license.terms" for information on usage and redistribution
            6  +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
            7  +'\"
            8  +.TH link n 0.3 TclOO "TclOO Commands"
            9  +.so man.macros
           10  +.BS
           11  +'\" Note:  do not modify the .SH NAME line immediately below!
           12  +.SH NAME
           13  +link \- create link from command to method of object
           14  +.SH SYNOPSIS
           15  +.nf
           16  +package require TclOO
           17  +
           18  +\fBlink\fR \fImethodName\fR ?\fI...\fR?
           19  +\fBlink\fR \fB{\fIcommandName methodName\fB}\fR ?\fI...\fR?
           20  +.fi
           21  +.BE
           22  +.SH DESCRIPTION
           23  +The \fBlink\fR command is available within methods. It takes a series of one
           24  +or more method names (\fImethodName ...\fR) and/or pairs of command- and
           25  +method-name (\fB{\fIcommandName methodName\fB}\fR) and makes the named methods
           26  +available as commands without requiring the explicit use of the name of the
           27  +object or the \fBmy\fR command. The method does not need to exist at the time
           28  +that the link is made; if the link command is invoked when the method does not
           29  +exist, the standard \fBunknown\fR method handling system is used.
           30  +.PP
           31  +The command name under which the method becomes available defaults to the
           32  +method name, except where explicitly specified through an alias/method pair.
           33  +Formally, every argument must be a list; if the list has two elements, the
           34  +first element is the name of the command to create and the second element is
           35  +the name of the method of the current object to which the command links;
           36  +otherwise, the name of the command and the name of the method are the same
           37  +string (the first element of the list).
           38  +.PP
           39  +If the name of the command is not a fully-qualified command name, it will be
           40  +resolved with respect to the current namespace (i.e., the object namespace).
           41  +.SH EXAMPLES
           42  +This demonstrates linking a single method in various ways. First it makes a
           43  +simple link, then a renamed link, then an external link. Note that the method
           44  +itself is unexported, but that it can still be called directly from outside
           45  +the class.
           46  +.PP
           47  +.CS
           48  +oo::class create ABC {
           49  +    method Foo {} {
           50  +        puts "This is Foo in [self]"
           51  +    }
           52  +
           53  +    constructor {} {
           54  +        \fBlink\fR Foo
           55  +        # The method foo is now directly accessible as foo here
           56  +        \fBlink\fR {bar Foo}
           57  +        # The method foo is now directly accessible as bar
           58  +        \fBlink\fR {::ExternalCall Foo}
           59  +        # The method foo is now directly accessible in the global
           60  +        # namespace as ExternalCall
           61  +    }
           62  +
           63  +    method grill {} {
           64  +        puts "Step 1:"
           65  +        Foo
           66  +        puts "Step 2:"
           67  +        bar
           68  +    }
           69  +}
           70  +
           71  +ABC create abc
           72  +abc grill
           73  +        \fI\(-> Step 1:\fR
           74  +        \fI\(-> This is foo in ::abc\fR
           75  +        \fI\(-> Step 2:\fR
           76  +        \fI\(-> This is foo in ::abc\fR
           77  +# Direct access via the linked command
           78  +puts "Step 3:"; ExternalCall
           79  +        \fI\(-> Step 3:\fR
           80  +        \fI\(-> This is foo in ::abc\fR
           81  +.CE
           82  +.PP
           83  +This example shows that multiple linked commands can be made in a call to
           84  +\fBlink\fR, and that they can handle arguments.
           85  +.PP
           86  +.CS
           87  +oo::class create Ex {
           88  +    constructor {} {
           89  +        \fBlink\fR a b c
           90  +        # The methods a, b, and c (defined below) are all now
           91  +        # directly acessible within methods under their own names.
           92  +    }
           93  +
           94  +    method a {} {
           95  +        puts "This is a"
           96  +    }
           97  +    method b {x} {
           98  +        puts "This is b($x)"
           99  +    }
          100  +    method c {y z} {
          101  +        puts "This is c($y,$z)"
          102  +    }
          103  +
          104  +    method call {p q r} {
          105  +        a
          106  +        b $p
          107  +        c $q $r
          108  +    }
          109  +}
          110  +
          111  +set o [Ex new]
          112  +$o 3 5 7
          113  +        \fI\(-> This is a\fR
          114  +        \fI\(-> This is b(3)\fR
          115  +        \fI\(-> This is c(5,7)\fR
          116  +.CE
          117  +.SH "SEE ALSO"
          118  +interp(n), my(n), oo::class(n), oo::define(n)
          119  +.SH KEYWORDS
          120  +command, method, object
          121  +.\" Local Variables:
          122  +.\" mode: nroff
          123  +.\" fill-column: 78
          124  +.\" End:

Changes to doc/llength.n.

    49     49   1,0
    50     50   .CE
    51     51   .SH "SEE ALSO"
    52     52   list(n), lappend(n), lindex(n), linsert(n), lsearch(n),
    53     53   lset(n), lsort(n), lrange(n), lreplace(n)
    54