Compare commits
1
Commits
gecode
...
rel-5-0-beta
| Author | SHA1 | Date | |
|---|---|---|---|
 cvs-fast-export
|
7e0143865e |
-551
@@ -1,551 +0,0 @@
|
||||
/*
|
||||
* P O L Y L I B . C
|
||||
*
|
||||
* Library for dealing with polynomials.
|
||||
*
|
||||
* Functions -
|
||||
* rt_poly_mul Multiply two polynomials
|
||||
* rt_poly_scale Scale a polynomial
|
||||
* rt_poly_add Add two polynomials
|
||||
* rt_poly_sub Subtract two polynomials
|
||||
* rt_poly_synthetic_division Divide 1 poly into another using Synthetic Division
|
||||
* quadratic Solve quadratic formula
|
||||
* cubic Solve cubic forumla
|
||||
* rt_pr_poly Print a polynomial
|
||||
*
|
||||
* Author -
|
||||
* Jeff Hanes
|
||||
*
|
||||
* Source -
|
||||
* SECAD/VLD Computing Consortium, Bldg 394
|
||||
* The U. S. Army Ballistic Research Laboratory
|
||||
* Aberdeen Proving Ground, Maryland 21005
|
||||
*
|
||||
* Copyright Notice -
|
||||
* This software is Copyright (C) 1985 by the United States Army.
|
||||
* All rights reserved.
|
||||
*/
|
||||
#ifndef lint
|
||||
static char RCSpolylib[] = "@(#)$Header$ (BRL)";
|
||||
#endif
|
||||
|
||||
#include "conf.h"
|
||||
|
||||
#include <stdio.h>
|
||||
#include <math.h>
|
||||
#include <signal.h>
|
||||
#include "machine.h"
|
||||
#include "externs.h"
|
||||
#include "vmath.h"
|
||||
#include "raytrace.h"
|
||||
#include "rtstring.h"
|
||||
#include "./polyno.h"
|
||||
#include "./complex.h"
|
||||
|
||||
extern void rt_pr_poly();
|
||||
|
||||
#ifndef M_PI
|
||||
#define M_PI 3.14159265358979323846
|
||||
#endif
|
||||
#define PI_DIV_3 (M_PI/3.0)
|
||||
static poly Zpoly = { 0, 0.0 };
|
||||
|
||||
/*
|
||||
* rt_poly_mul -- multiply two polynomials
|
||||
*/
|
||||
poly *
|
||||
rt_poly_mul(m1,m2,product)
|
||||
register poly *m1, *m2, *product;
|
||||
{
|
||||
if( m1->dgr == 1 && m2->dgr == 1 ) {
|
||||
product->dgr = 2;
|
||||
product->cf[0] = m1->cf[0] * m2->cf[0];
|
||||
product->cf[1] = m1->cf[0] * m2->cf[1] +
|
||||
m1->cf[1] * m2->cf[0];
|
||||
product->cf[2] = m1->cf[1] * m2->cf[1];
|
||||
return(product);
|
||||
}
|
||||
if( m1->dgr == 2 && m2->dgr == 2 ) {
|
||||
product->dgr = 4;
|
||||
product->cf[0] = m1->cf[0] * m2->cf[0];
|
||||
product->cf[1] = m1->cf[0] * m2->cf[1] +
|
||||
m1->cf[1] * m2->cf[0];
|
||||
product->cf[2] = m1->cf[0] * m2->cf[2] +
|
||||
m1->cf[1] * m2->cf[1] +
|
||||
m1->cf[2] * m2->cf[0];
|
||||
product->cf[3] = m1->cf[1] * m2->cf[2] +
|
||||
m1->cf[2] * m2->cf[1];
|
||||
product->cf[4] = m1->cf[2] * m2->cf[2];
|
||||
return(product);
|
||||
}
|
||||
|
||||
/* Not one of the common (or easy) cases. */
|
||||
{
|
||||
register int ct1, ct2;
|
||||
|
||||
*product = Zpoly;
|
||||
|
||||
/* If the degree of the product will be larger than the
|
||||
* maximum size allowed in "polyno.h", then return a null
|
||||
* pointer to indicate failure.
|
||||
*/
|
||||
if ( (product->dgr = m1->dgr + m2->dgr) > MAXP )
|
||||
return PM_NULL;
|
||||
|
||||
for ( ct1=0; ct1 <= m1->dgr; ++ct1 ){
|
||||
for ( ct2=0; ct2 <= m2->dgr; ++ct2 ){
|
||||
product->cf[ct1+ct2] +=
|
||||
m1->cf[ct1] * m2->cf[ct2];
|
||||
}
|
||||
}
|
||||
}
|
||||
return product;
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* rt_poly_scale -- scale a polynomial
|
||||
*/
|
||||
poly *
|
||||
rt_poly_scale(eqn,factor)
|
||||
register poly *eqn;
|
||||
double factor;
|
||||
{
|
||||
register int cnt;
|
||||
|
||||
for ( cnt=0; cnt <= eqn->dgr; ++cnt ){
|
||||
eqn->cf[cnt] *= factor;
|
||||
}
|
||||
return eqn;
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* rt_poly_add -- add two polynomials
|
||||
*/
|
||||
poly *
|
||||
rt_poly_add(poly1,poly2,sum)
|
||||
register poly *poly1, *poly2, *sum;
|
||||
{
|
||||
LOCAL poly tmp;
|
||||
register int i, offset;
|
||||
|
||||
offset = Abs(poly1->dgr - poly2->dgr);
|
||||
|
||||
tmp = Zpoly;
|
||||
|
||||
if ( poly1->dgr >= poly2->dgr ){
|
||||
*sum = *poly1;
|
||||
for ( i=0; i <= poly2->dgr; ++i ){
|
||||
tmp.cf[i+offset] = poly2->cf[i];
|
||||
}
|
||||
} else {
|
||||
*sum = *poly2;
|
||||
for ( i=0; i <= poly1->dgr; ++i ){
|
||||
tmp.cf[i+offset] = poly1->cf[i];
|
||||
}
|
||||
}
|
||||
|
||||
for ( i=0; i <= sum->dgr; ++i ){
|
||||
sum->cf[i] += tmp.cf[i];
|
||||
}
|
||||
return sum;
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* rt_poly_sub -- subtract two polynomials
|
||||
*/
|
||||
poly *
|
||||
rt_poly_sub(poly1,poly2,diff)
|
||||
register poly *poly1, *poly2, *diff;
|
||||
{
|
||||
LOCAL poly tmp;
|
||||
register int i, offset;
|
||||
|
||||
offset = Abs(poly1->dgr - poly2->dgr);
|
||||
|
||||
*diff = Zpoly;
|
||||
tmp = Zpoly;
|
||||
|
||||
if ( poly1->dgr >= poly2->dgr ){
|
||||
*diff = *poly1;
|
||||
for ( i=0; i <= poly2->dgr; ++i ){
|
||||
tmp.cf[i+offset] = poly2->cf[i];
|
||||
}
|
||||
} else {
|
||||
diff->dgr = poly2->dgr;
|
||||
for ( i=0; i <= poly1->dgr; ++i ){
|
||||
diff->cf[i+offset] = poly1->cf[i];
|
||||
}
|
||||
tmp = *poly2;
|
||||
}
|
||||
|
||||
for ( i=0; i <= diff->dgr; ++i ){
|
||||
diff->cf[i] -= tmp.cf[i];
|
||||
}
|
||||
return diff;
|
||||
}
|
||||
|
||||
|
||||
/* >>> s y n D i v ( ) <<<
|
||||
* Divides any polynomial into any other polynomial using synthetic
|
||||
* division. Both polynomials must have real coefficients.
|
||||
*/
|
||||
void
|
||||
rt_poly_synthetic_division(dvdend,dvsor,quo,rem)
|
||||
register poly *dvdend, *dvsor, *quo, *rem;
|
||||
{
|
||||
register int div;
|
||||
register int n;
|
||||
|
||||
*quo = *dvdend;
|
||||
*rem = Zpoly;
|
||||
|
||||
if ((quo->dgr = dvdend->dgr - dvsor->dgr) < 0)
|
||||
quo->dgr = -1;
|
||||
if ((rem->dgr = dvsor->dgr - 1) > dvdend->dgr)
|
||||
rem->dgr = dvdend->dgr;
|
||||
|
||||
for ( n=0; n <= quo->dgr; ++n){
|
||||
quo->cf[n] /= dvsor->cf[0];
|
||||
for ( div=1; div <= dvsor->dgr; ++div){
|
||||
quo->cf[n+div] -= quo->cf[n] * dvsor->cf[div];
|
||||
}
|
||||
}
|
||||
for ( n=1; n<=(rem->dgr+1); ++n){
|
||||
rem->cf[n-1] = quo->cf[quo->dgr+n];
|
||||
quo->cf[quo->dgr+n] = 0;
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
/* >>> q u a d r a t i c ( ) <<<
|
||||
*
|
||||
* Uses the quadratic formula to find the roots (in `complex' form)
|
||||
* of any quadratic equation with real coefficients.
|
||||
*/
|
||||
void
|
||||
rt_poly_quadratic_roots( quadrat, root )
|
||||
register poly *quadrat;
|
||||
register complex root[];
|
||||
{
|
||||
LOCAL fastf_t discrim, denom, rad;
|
||||
|
||||
if( NEAR_ZERO( quadrat->cf[0], SMALL ) ) {
|
||||
/* root = -cf[2] / cf[1] */
|
||||
if( NEAR_ZERO( quadrat->cf[1], SMALL ) ) {
|
||||
/* No solution. Now what? */
|
||||
rt_log("rt_poly_quadratic_roots(): ERROR, no solution\n");
|
||||
return;
|
||||
}
|
||||
/* Fake it as a repeated root. */
|
||||
root[0].re = root[1].re = -quadrat->cf[2]/quadrat->cf[1];
|
||||
root[0].im = root[1].im = 0.0;
|
||||
return;
|
||||
}
|
||||
/* What to do if cf[1] > SQRT_MAX_FASTF ? */
|
||||
|
||||
discrim = quadrat->cf[1]*quadrat->cf[1] - 4.0* quadrat->cf[0]*quadrat->cf[2];
|
||||
denom = 0.5 / quadrat->cf[0];
|
||||
if ( discrim >= 0.0 ){
|
||||
rad = sqrt( discrim );
|
||||
root[0].re = ( -quadrat->cf[1] + rad ) * denom;
|
||||
root[1].re = ( -quadrat->cf[1] - rad ) * denom;
|
||||
root[1].im = root[0].im = 0.0;
|
||||
} else {
|
||||
root[1].re = root[0].re = -quadrat->cf[1] * denom;
|
||||
root[1].im = -(root[0].im = sqrt( -discrim ) * denom);
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
#define SQRT3 1.732050808
|
||||
#define THIRD 0.333333333333333333333333333
|
||||
#define INV_TWENTYSEVEN 0.037037037037037037037037037
|
||||
#define CUBEROOT( a ) (( (a) >= 0.0 ) ? pow( a, THIRD ) : -pow( -(a), THIRD ))
|
||||
|
||||
/* >>> c u b i c ( ) <<<
|
||||
*
|
||||
* Uses the cubic formula to find the roots ( in `complex' form )
|
||||
* of any cubic equation with real coefficients.
|
||||
*
|
||||
* to solve a polynomial of the form:
|
||||
*
|
||||
* X**3 + c1*X**2 + c2*X + c3 = 0,
|
||||
*
|
||||
* first reduce it to the form:
|
||||
*
|
||||
* Y**3 + a*Y + b = 0,
|
||||
*
|
||||
* where
|
||||
* Y = X + c1/3,
|
||||
* and
|
||||
* a = c2 - c1**2/3,
|
||||
* b = ( 2*c1**3 - 9*c1*c2 + 27*c3 )/27.
|
||||
*
|
||||
* Then we define the value delta, D = b**2/4 + a**3/27.
|
||||
*
|
||||
* If D > 0, there will be one real root and two conjugate
|
||||
* complex roots.
|
||||
* If D = 0, there will be three real roots at least two of
|
||||
* which are equal.
|
||||
* If D < 0, there will be three unequal real roots.
|
||||
*
|
||||
* Returns 1 for success, 0 for fail.
|
||||
*/
|
||||
static int expecting_fpe = 0;
|
||||
static jmp_buf abort_buf;
|
||||
HIDDEN void rt_catch_FPE(sig)
|
||||
int sig;
|
||||
{
|
||||
if( !expecting_fpe )
|
||||
rt_bomb("unexpected SIGFPE!");
|
||||
if( !rt_g.rtg_parallel )
|
||||
(void)signal(SIGFPE, rt_catch_FPE); /* Renew handler */
|
||||
longjmp(abort_buf, 1); /* return error code */
|
||||
}
|
||||
|
||||
int
|
||||
rt_poly_cubic_roots( eqn, root )
|
||||
register poly *eqn;
|
||||
register complex root[];
|
||||
{
|
||||
LOCAL fastf_t a, b, c1, c1_3rd, delta;
|
||||
register int i;
|
||||
static int first_time = 1;
|
||||
|
||||
if( !rt_g.rtg_parallel ) {
|
||||
/* abort_buf is NOT parallel! */
|
||||
if( first_time ) {
|
||||
first_time = 0;
|
||||
(void)signal(SIGFPE, rt_catch_FPE);
|
||||
}
|
||||
expecting_fpe = 1;
|
||||
if( setjmp( abort_buf ) ) {
|
||||
(void)signal(SIGFPE, rt_catch_FPE);
|
||||
rt_log("rt: rt_poly_cubic_roots() Floating Point Error\n");
|
||||
return(0); /* FAIL */
|
||||
}
|
||||
}
|
||||
|
||||
c1 = eqn->cf[1];
|
||||
if( Abs(c1) > SQRT_MAX_FASTF ) return(0); /* FAIL */
|
||||
c1_3rd = c1 * THIRD;
|
||||
a = eqn->cf[2] - c1*c1_3rd;
|
||||
if( Abs(a) > SQRT_MAX_FASTF ) return(0); /* FAIL */
|
||||
b = (2.0*c1*c1*c1 - 9.0*c1*eqn->cf[2] + 27.0*eqn->cf[3])*INV_TWENTYSEVEN;
|
||||
if( Abs(b) > SQRT_MAX_FASTF ) return(0); /* FAIL */
|
||||
|
||||
if( (delta = a*a) > SQRT_MAX_FASTF ) return(0); /* FAIL */
|
||||
delta = b*b*0.25 + delta*a*INV_TWENTYSEVEN;
|
||||
|
||||
if ( delta > 0.0 ){
|
||||
LOCAL fastf_t r_delta, A, B;
|
||||
|
||||
r_delta = sqrt( delta );
|
||||
A = B = -0.5 * b;
|
||||
A += r_delta;
|
||||
B -= r_delta;
|
||||
|
||||
A = CUBEROOT( A );
|
||||
B = CUBEROOT( B );
|
||||
|
||||
root[2].re = root[1].re = -0.5 * ( root[0].re = A + B );
|
||||
|
||||
root[0].im = 0.0;
|
||||
root[2].im = -( root[1].im = (A - B)*SQRT3*0.5 );
|
||||
} else if ( delta == 0.0 ){
|
||||
LOCAL fastf_t b_2;
|
||||
b_2 = -0.5 * b;
|
||||
|
||||
root[0].re = 2.0* CUBEROOT( b_2 );
|
||||
root[2].re = root[1].re = -0.5 * root[0].re;
|
||||
root[2].im = root[1].im = root[0].im = 0.0;
|
||||
} else {
|
||||
LOCAL fastf_t phi, fact;
|
||||
LOCAL fastf_t cs_phi, sn_phi_s3;
|
||||
|
||||
if( a >= 0.0 ) {
|
||||
fact = 0.0;
|
||||
phi = 0.0;
|
||||
cs_phi = 1.0; /* cos( phi ); */
|
||||
sn_phi_s3 = 0.0; /* sin( phi ) * SQRT3; */
|
||||
} else {
|
||||
FAST fastf_t f;
|
||||
a *= -THIRD;
|
||||
fact = sqrt( a );
|
||||
if( (f = b * (-0.5) / (a*fact)) >= 1.0 ) {
|
||||
phi = 0.0;
|
||||
cs_phi = 1.0; /* cos( phi ); */
|
||||
sn_phi_s3 = 0.0; /* sin( phi ) * SQRT3; */
|
||||
} else if( f <= -1.0 ) {
|
||||
phi = PI_DIV_3;
|
||||
cs_phi = cos( phi );
|
||||
sn_phi_s3 = sin( phi ) * SQRT3;
|
||||
} else {
|
||||
phi = acos( f ) * THIRD;
|
||||
cs_phi = cos( phi );
|
||||
sn_phi_s3 = sin( phi ) * SQRT3;
|
||||
}
|
||||
}
|
||||
|
||||
root[0].re = 2.0*fact*cs_phi;
|
||||
root[1].re = fact*( sn_phi_s3 - cs_phi);
|
||||
root[2].re = fact*( -sn_phi_s3 - cs_phi);
|
||||
root[2].im = root[1].im = root[0].im = 0.0;
|
||||
}
|
||||
for ( i=0; i < 3; ++i )
|
||||
root[i].re -= c1_3rd;
|
||||
expecting_fpe = 0;
|
||||
return(1); /* OK */
|
||||
}
|
||||
|
||||
|
||||
/* >>> q u a r t i c ( ) <<<
|
||||
*
|
||||
* Uses the quartic formula to find the roots ( in `complex' form )
|
||||
* of any quartic equation with real coefficients.
|
||||
*
|
||||
* Returns 1 for success, 0 for fail.
|
||||
*/
|
||||
int
|
||||
rt_poly_quartic_roots( eqn, root )
|
||||
register poly *eqn;
|
||||
register complex root[];
|
||||
{
|
||||
LOCAL poly cube, quad1, quad2;
|
||||
LOCAL complex u[3];
|
||||
LOCAL fastf_t U, p, q, q1, q2;
|
||||
#define Max3(a,b,c) ((c)>((a)>(b)?(a):(b)) ? (c) : ((a)>(b)?(a):(b)))
|
||||
|
||||
cube.dgr = 3;
|
||||
cube.cf[0] = 1.0;
|
||||
cube.cf[1] = -eqn->cf[2];
|
||||
cube.cf[2] = eqn->cf[3]*eqn->cf[1]
|
||||
- 4*eqn->cf[4];
|
||||
cube.cf[3] = -eqn->cf[3]*eqn->cf[3]
|
||||
- eqn->cf[4]*eqn->cf[1]*eqn->cf[1]
|
||||
+ 4*eqn->cf[4]*eqn->cf[2];
|
||||
|
||||
if( !rt_poly_cubic_roots( &cube, u ) ) {
|
||||
return( 0 ); /* FAIL */
|
||||
}
|
||||
if ( u[1].im != 0.0 ){
|
||||
U = u[0].re;
|
||||
} else {
|
||||
U = Max3( u[0].re, u[1].re, u[2].re );
|
||||
}
|
||||
|
||||
p = eqn->cf[1]*eqn->cf[1]*0.25 + U - eqn->cf[2];
|
||||
U *= 0.5;
|
||||
q = U*U - eqn->cf[4];
|
||||
if( p < 0 ) {
|
||||
if( p < -1.0e-8 ) {
|
||||
return(0); /* FAIL */
|
||||
}
|
||||
p = 0;
|
||||
} else {
|
||||
p = sqrt( p );
|
||||
}
|
||||
if( q < 0 ) {
|
||||
if( q < -1.0e-8 ) {
|
||||
return(0); /* FAIL */
|
||||
}
|
||||
q = 0;
|
||||
} else {
|
||||
q = sqrt( q );
|
||||
}
|
||||
|
||||
quad1.dgr = quad2.dgr = 2;
|
||||
quad1.cf[0] = quad2.cf[0] = 1.0;
|
||||
quad1.cf[1] = eqn->cf[1]*0.5;
|
||||
quad2.cf[1] = quad1.cf[1] + p;
|
||||
quad1.cf[1] -= p;
|
||||
|
||||
q1 = U - q;
|
||||
q2 = U + q;
|
||||
|
||||
p = quad1.cf[1]*q2 + quad2.cf[1]*q1 - eqn->cf[3];
|
||||
if( Abs( p ) < 1.0e-8){
|
||||
quad1.cf[2] = q1;
|
||||
quad2.cf[2] = q2;
|
||||
} else {
|
||||
q = quad1.cf[1]*q1 + quad2.cf[1]*q2 - eqn->cf[3];
|
||||
if( Abs( q ) < 1.0e-8 ){
|
||||
quad1.cf[2] = q2;
|
||||
quad2.cf[2] = q1;
|
||||
} else {
|
||||
return(0); /* FAIL */
|
||||
}
|
||||
}
|
||||
|
||||
rt_poly_quadratic_roots( &quad1, root );
|
||||
rt_poly_quadratic_roots( &quad2, &root[2] );
|
||||
return(1); /* SUCCESS */
|
||||
}
|
||||
|
||||
|
||||
/*
|
||||
* R T _ P R _ P O L Y
|
||||
*/
|
||||
void
|
||||
rt_pr_poly(title, eqn)
|
||||
char *title;
|
||||
register poly *eqn;
|
||||
{
|
||||
register int n;
|
||||
register int exp;
|
||||
struct rt_vls str;
|
||||
char buf[48];
|
||||
|
||||
rt_vls_init( &str );
|
||||
rt_vls_extend( &str, 196 );
|
||||
rt_vls_strcat( &str, title );
|
||||
sprintf(buf, " polynomial, degree = %d\n", eqn->dgr);
|
||||
rt_vls_strcat( &str, buf );
|
||||
|
||||
exp = eqn->dgr;
|
||||
for ( n=0; n<=eqn->dgr; n++,exp-- ) {
|
||||
register double coeff = eqn->cf[n];
|
||||
if( n > 0 ) {
|
||||
if( coeff < 0 ) {
|
||||
rt_vls_strcat( &str, " - " );
|
||||
coeff = -coeff;
|
||||
} else {
|
||||
rt_vls_strcat( &str, " + " );
|
||||
}
|
||||
}
|
||||
sprintf( buf, "%g", coeff );
|
||||
rt_vls_strcat( &str, buf );
|
||||
if( exp > 1 ) {
|
||||
sprintf( buf, " *X^%d", exp );
|
||||
rt_vls_strcat( &str, buf );
|
||||
} else if( exp == 1 ) {
|
||||
|
||||
rt_vls_strcat( &str, " *X" );
|
||||
} else {
|
||||
/* For constant term, add nothing */
|
||||
}
|
||||
}
|
||||
rt_vls_strcat( &str, "\n" );
|
||||
rt_log( "%s", rt_vls_addr(&str) );
|
||||
rt_vls_free( &str );
|
||||
}
|
||||
|
||||
/*
|
||||
* R T _ P R _ R O O T S
|
||||
*/
|
||||
void
|
||||
rt_pr_roots( title, roots, n )
|
||||
char *title;
|
||||
complex roots[];
|
||||
int n;
|
||||
{
|
||||
register int i;
|
||||
|
||||
rt_log("%s: %d roots:\n", title, n );
|
||||
for( i=0; i<n; i++ ) {
|
||||
rt_log("%4d %e + i * %e\n", i, roots[i].re, roots[i].im );
|
||||
}
|
||||
}
|
||||
@@ -1,43 +0,0 @@
|
||||
/*
|
||||
* P O L Y N O . H
|
||||
*
|
||||
* Definitions for handling polynomial equations
|
||||
*
|
||||
* Author -
|
||||
* Jeff Hanes
|
||||
*
|
||||
* Source -
|
||||
* SECAD/VLD Computing Consortium, Bldg 394
|
||||
* The U. S. Army Ballistic Research Laboratory
|
||||
* Aberdeen Proving Ground, Maryland 21005
|
||||
*
|
||||
* Copyright Notice -
|
||||
* This software is Copyright (C) 1985 by the United States Army.
|
||||
* All rights reserved.
|
||||
*
|
||||
* $Header$
|
||||
*/
|
||||
#ifndef POLYNO_H
|
||||
#define POLYNO_H seen
|
||||
|
||||
#define MAXP 4 /* Maximum Poly Order */
|
||||
|
||||
#define Abs( a ) ((a) >= 0 ? (a) : -(a))
|
||||
#define Max( a, b ) ((a) > (b) ? (a) : (b))
|
||||
|
||||
/* error return value for 'polyMul' */
|
||||
#define PM_NULL ((poly *)0)
|
||||
|
||||
/* polynomial data type */
|
||||
typedef struct {
|
||||
int dgr;
|
||||
double cf[MAXP+1];
|
||||
} poly;
|
||||
|
||||
|
||||
/* library functions in polylib.c */
|
||||
extern poly *polyAdd(), *polySub(), *polyMul(), *polyScal();
|
||||
extern void quadratic(), synDiv(), prntpoly(), pr_poly();
|
||||
extern int quartic(), cubic();
|
||||
|
||||
#endif /* POLYNO_H */
|
||||
@@ -1,64 +0,0 @@
|
||||
/*
|
||||
* libtcl/Cakefile
|
||||
*/
|
||||
#define SRCDIR libtcl
|
||||
#define SRCSUFF .c
|
||||
#define MANSECTION 3
|
||||
|
||||
#include "../Cakefile.defs"
|
||||
|
||||
#if !defined(BUILD_LIBRARY)
|
||||
#define TCL_OPTS --srcdir=[[pwd]]/../SRCDIR/"unix" --quiet --cache-file cache.MTYPE \
|
||||
--exec-prefix=BASEDIR --prefix=BASEDIR
|
||||
#define PRODUCTS libtcl.a tclsh
|
||||
#define AFTER_MAKE /**/
|
||||
#else
|
||||
#define TCL_OPTS --srcdir=[[pwd]]/../SRCDIR/"unix" --quiet --enable-shared \
|
||||
--cache-file cache.MTYPE --exec-prefix=BASEDIR --prefix=BASEDIR
|
||||
#define PRODUCTS libtcl.so tclsh
|
||||
#define SHARED_PRODUCT libtcl.so''[[LIBVERS]]
|
||||
#define AFTER_MAKE mv -f libtcl.so SHARED_PRODUCT ; sharedliblink.sh SHARED_PRODUCT
|
||||
#endif
|
||||
|
||||
PRODUCTS: Makefile.MTYPE cache.MTYPE
|
||||
make `echo CAKEFLAGS | tr '\040' '\012' | grep -- -s` -f Makefile.MTYPE CAKEFLAGS
|
||||
|
||||
Makefile.MTYPE cache.MTYPE: if not exist Makefile.MTYPE or not exist cache.MTYPE
|
||||
( \C\F\L\A\G\S=\"GFLAG OPTIMIZER PROFILER\"; \
|
||||
\A\F\T\E\R\_\M\A\K\E=\"AFTER_MAKE\"; \
|
||||
\R\A\N\L\I\B=\"RANLIB\"; \
|
||||
\L\D\F\L\A\G\S=\"LDFLAGS\"; \
|
||||
export \C\F\L\A\G\S \R\A\N\L\I\B \L\D\F\L\A\G\S \A\F\T\E\R\_\M\A\K\E; \
|
||||
../SRCDIR/"unix"/configure TCL_OPTS; \
|
||||
../SRCDIR/fix_makefile.sh > Makefile.MTYPE)
|
||||
|
||||
|
||||
clean&:
|
||||
make -f Makefile clean
|
||||
|
||||
noprod&:
|
||||
rm -rf libtcl.*
|
||||
|
||||
clobber&:
|
||||
rm -f *.MTYPE *.o libtcl.* config.log config.status tclConfig.sh tclsh Makefile
|
||||
|
||||
install&: Makefile.MTYPE
|
||||
make -f Makefile.MTYPE install
|
||||
( cd BASEDIR/lib; AFTER_MAKE )
|
||||
|
||||
install-nobak&: Makefile.MTYPE
|
||||
make -f Makefile.MTYPE install
|
||||
( cd BASEDIR/lib; AFTER_MAKE )
|
||||
|
||||
tclsh: Makefile.MTYPE
|
||||
make -f Makefile.MTYPE tclsh
|
||||
|
||||
tcltest: Makefile.MTYPE
|
||||
make -f Makefile.MTYPE tcltest
|
||||
|
||||
test&: Makefile.MTYPE
|
||||
make -f Makefile.MTYPE test
|
||||
|
||||
/* dltest: if not exist dltest
|
||||
cp -r ../SRCDIR/"unix"/dltest .
|
||||
*/
|
||||
-381
@@ -1,381 +0,0 @@
|
||||
Tcl
|
||||
|
||||
SCCS: @(#) README 1.52 97/11/20 12:43:16
|
||||
|
||||
1. Introduction
|
||||
---------------
|
||||
|
||||
This directory and its descendants contain the sources and documentation
|
||||
for Tcl, an embeddable scripting language. The information here
|
||||
corresponds to release 8.0p2, which is the second patch update for Tcl
|
||||
8.0. Tcl 8.0 is a major new release that replaces the core of the
|
||||
interpreter with an on-the-fly bytecode compiler to improve execution
|
||||
speed. It also includes several other new features such as namespaces
|
||||
and binary I/O, plus many bug fixes. The compiler introduces a few
|
||||
incompatibilities that may affect existing Tcl scripts; the
|
||||
incompatibilities are relatively obscure but may require modifications
|
||||
to some old scripts before they can run with this version. The compiler
|
||||
introduces many new C-level APIs, but the old APIs are still supported.
|
||||
See below for more details. This patch release fixes various bugs in
|
||||
Tcl 8.0; there are no feature changes relative to Tcl 8.0.
|
||||
|
||||
2. Documentation
|
||||
----------------
|
||||
|
||||
The best way to get started with Tcl is to read one of the introductory
|
||||
books on Tcl:
|
||||
|
||||
Practical Programming in Tcl and Tk, 2nd Edition, by Brent Welch,
|
||||
Prentice-Hall, 1997, ISBN 0-13-616830-2
|
||||
|
||||
Tcl and the Tk Toolkit, by John Ousterhout,
|
||||
Addison-Wesley, 1994, ISBN 0-201-63337-X
|
||||
|
||||
Exploring Expect, by Don Libes,
|
||||
O'Reilly and Associates, 1995, ISBN 1-56592-090-2
|
||||
|
||||
The "doc" subdirectory in this release contains a complete set of reference
|
||||
manual entries for Tcl. Files with extension ".1" are for programs (for
|
||||
example, tclsh.1); files with extension ".3" are for C library procedures;
|
||||
and files with extension ".n" describe Tcl commands. The file "doc/Tcl.n"
|
||||
gives a quick summary of the Tcl language syntax. To print any of the man
|
||||
pages, cd to the "doc" directory and invoke your favorite variant of
|
||||
troff using the normal -man macros, for example
|
||||
|
||||
ditroff -man Tcl.n
|
||||
|
||||
to print Tcl.n. If Tcl has been installed correctly and your "man"
|
||||
program supports it, you should be able to access the Tcl manual entries
|
||||
using the normal "man" mechanisms, such as
|
||||
|
||||
man Tcl
|
||||
|
||||
There is also an official home for Tcl and Tk on the Web:
|
||||
http://sunscript.sun.com
|
||||
These Web pages include information about the latest releases, products
|
||||
related to Tcl and Tk, reports on bug fixes and porting issues, HTML
|
||||
versions of the manual pages, and pointers to many other Tcl/Tk Web
|
||||
pages at other sites. Check them out!
|
||||
|
||||
3. Compiling and installing Tcl
|
||||
-------------------------------
|
||||
|
||||
This release contains everything you should need to compile and run
|
||||
Tcl under UNIX, Macintoshes, and PCs (either Windows NT, Windows 95,
|
||||
or Win 3.1 with Win32s).
|
||||
|
||||
Before trying to compile Tcl you should do the following things:
|
||||
|
||||
(a) Check for a binary release. Pre-compiled binary releases are
|
||||
available now for PCs, Macintoshes, and several flavors of UNIX.
|
||||
Binary releases are much easier to install than source releases.
|
||||
To find out whether a binary release is available for your
|
||||
platform, check the home page for SunScript
|
||||
(http://sunscript.sun.com) under "Tech Corner". Also, check in
|
||||
the FTP directory from which you retrieved the base
|
||||
distribution. Some of the binary releases are available freely,
|
||||
while others are for sale.
|
||||
|
||||
(b) Make sure you have the most recent patch release. Look in the
|
||||
FTP directory from which you retrieved this distribution to see
|
||||
if it has been updated with patches. Patch releases fix bugs
|
||||
without changing any features, so you should normally use the
|
||||
latest patch release for the version of Tcl that you want.
|
||||
Patch releases are available in two forms. A file like
|
||||
tcl8.0p2.tar.Z is a complete release for patch level 2 of Tcl
|
||||
version 8.0. If there is a file with a higher patch level than
|
||||
this release, just fetch the file with the highest patch level
|
||||
and use it.
|
||||
|
||||
Patches are also available in the form of patch files that just
|
||||
contain the changes from one patch level to another. These
|
||||
files will have names like tcl8.0p1.patch, tcl8.0p2.patch, etc. They
|
||||
may also have .gz or .Z extensions to indicate compression. To
|
||||
use one of these files, you apply it to an existing release with
|
||||
the "patch" program. Patches must be applied in order:
|
||||
tcl8.0p1.patch must be applied to an unpatched Tcl 8.0 release
|
||||
to produce a Tcl 8.0p1 release; tcl8.0p2.patch can then be
|
||||
applied to Tcl8.0p1 to produce Tcl 8.0p2, and so on. To apply an
|
||||
uncompressed patch file such as tcl8.0p1.patch, invoke a shell
|
||||
command like the following from the directory containing this
|
||||
file:
|
||||
patch -p < tcl8.0p1.patch
|
||||
If the patch file has a .gz extension, invoke a command like the
|
||||
following:
|
||||
gunzip -c tcl8.0p1.patch.gz | patch -p
|
||||
If the patch file has a .Z extension, it was compressed with
|
||||
compress. To apply it, invoke a command like the following:
|
||||
zcat tcl8.0p1.patch.Z | patch -p
|
||||
If you're applying a patch to a release that has already been
|
||||
compiled, then before applying the patch you should cd to the
|
||||
"unix" subdirectory and type "make distclean" to restore the
|
||||
directory to a pristine state.
|
||||
|
||||
Once you've done this, change to the "unix" subdirectory if you're
|
||||
compiling under UNIX, "win" if you're compiling under Windows, or
|
||||
"mac" if you're compiling on a Macintosh. Then follow the instructions
|
||||
in the README file in that directory for compiling Tcl, installing it,
|
||||
and running the test suite.
|
||||
|
||||
4. Summary of changes in Tcl 8.0
|
||||
--------------------------------
|
||||
|
||||
Here are the most significant changes in Tcl 8.0. In addition to these
|
||||
changes, there are several smaller changes and bug fixes. See the file
|
||||
"changes" for a complete list of all changes.
|
||||
|
||||
1. Bytecode compiler. The core of the Tcl interpreter has been
|
||||
replaced with an on-the-fly compiler that translates Tcl scripts to
|
||||
byte codes; a new interpreter then executes the byte codes. In
|
||||
earlier versions of Tcl, strings were used as a universal
|
||||
representation; in Tcl 8.0 strings are replaced with Tcl_Obj
|
||||
structures ("objects") that can hold both a string value and an
|
||||
internal form such as a binary integer or compiled bytecodes. The
|
||||
new objects make it possible to store information in efficient
|
||||
internal forms and avoid the constant translations to and from
|
||||
strings that occurred with the old interpreter. We have not yet
|
||||
converted all of Tcl to take full advantage of the compiler and
|
||||
objects and have not converted any of Tk yet, but even so you
|
||||
should see speedups of 2-3x on many programs and you may see
|
||||
speedups as much as 10-20x in some cases (such as code that
|
||||
manipulates long lists). Future releases should achieve even
|
||||
greater speedups. The compiler introduces only a few minor changes
|
||||
at the level of Tcl scripts, but it introduces many new C APIs for
|
||||
managing objects. See, for example, the manual entries doc/*Obj*.3.
|
||||
|
||||
2. Namespaces. There is a new namespace mechanism based on the
|
||||
namespace implementation by Michael McLennan of Lucent Technologies.
|
||||
This includes new "namespace" and "variable" commands. There are
|
||||
many new C APIs associated with namespaces, but they will not be
|
||||
exported until Tcl 8.1. Note: the syntax of the namespace command
|
||||
has been changed slightly since the b1 release. See the changes
|
||||
file for details.
|
||||
|
||||
3. Binary I/O. The new object system in Tcl 8.0 supports binary
|
||||
strings (internally, strings are counted in addition to being null
|
||||
terminated). There is a new "binary" command for inserting and
|
||||
extracting data to/from binary strings. Commands such as "puts",
|
||||
"gets", and "read" commands now operate correctly on binary data.
|
||||
There is a new variable tcl_platform(byteOrder) to identify the
|
||||
native byte order for the current host.
|
||||
|
||||
4. Random numbers. The "expr" command now contains a random number
|
||||
generator, which can be accessed via the "rand()" and "srand()" math
|
||||
functions.
|
||||
|
||||
5. Safe-Tcl enhancements. There is a new "hidden command"
|
||||
mechanism, implemented with the Tcl commands "interp hide", "interp
|
||||
expose", "interp invokehidden", and "interp hidden" and the C APIs
|
||||
Tcl_HideCommand and Tcl_ExposeCommand. There is now support for
|
||||
safe packages and extension loading, including new library
|
||||
procedures such as safe::interpCreate (see the manual entry safe.n
|
||||
for details).
|
||||
|
||||
6. There is a new package "registry" available under Windows for
|
||||
accessing the Windows registry.
|
||||
|
||||
7. There is a new command "file attributes" for getting and setting
|
||||
things like permissions and owner. There is also a new command
|
||||
"file nativename" for getting back the platform-specific name for a
|
||||
particular file.
|
||||
|
||||
8. There is a new "fcopy" command to copy data between channels.
|
||||
This replaces and improves upon the not-so-secret unsupported old
|
||||
command "unsupported0".
|
||||
|
||||
9. There is a new package "http" for doing GET, POST, and HEAD
|
||||
requests via the HTTP/1.0 protocol. See the manual entry http.n
|
||||
for details.
|
||||
|
||||
10. There are new library procedures for finding word breaks in
|
||||
strings. See the manual entry library.n for details.
|
||||
|
||||
11. There are new C APIs Tcl_Finalize (for cleaning up before
|
||||
unloading the Tcl DLL) and Tcl_Ungets for pushing bytes back into a
|
||||
channel's input buffer.
|
||||
|
||||
12. Tcl now supports serial I/O devices on Windows and Unix, with a
|
||||
new fconfigure -mode option. The Windows driver does not yet
|
||||
support event-driven I/O.
|
||||
|
||||
13. The lsort command has new options -dictionary and -index. The
|
||||
-index option allows for very rapid sorting based on an element
|
||||
of a list.
|
||||
|
||||
14. The event notifier has been completely rewritten (again). It
|
||||
should now allow Tcl to use an external event loop (like Motif's)
|
||||
when it is embedded in other applications. No script-level
|
||||
interfaces have changed, but many of the C APIs have.
|
||||
|
||||
Tcl 8.0 introduces the following incompatibilities that may affect Tcl
|
||||
scripts that worked under Tcl 7.6 and earlier releases:
|
||||
|
||||
1. Variable and command names may not include the character sequence
|
||||
"::" anymore: this sequence is now used as a namespace separator.
|
||||
|
||||
2. The semantics of some Tcl commands have been changed slightly to
|
||||
maximize performance under the compiler. These incompatibilities
|
||||
are documented on the Web so that we can keep the list up-to-date.
|
||||
See the URL http://www.sunlabs.com/research/tcl/compiler.html.
|
||||
|
||||
3. 2-digit years are now parsed differently by the "clock" command
|
||||
to handle year 2000 issues better (years 00-38 are treated as
|
||||
2000-2038 instead of 1900-1938).
|
||||
|
||||
4. The old Macintosh commands "cp", "mkdir", "mv", "rm", and "rmdir"
|
||||
are no longer supported; all of these features are now available on
|
||||
all platforms via the "file" command.
|
||||
|
||||
5. The variable tcl_precision is now shared between interpreters
|
||||
and defaults to 12 digits instead of 6; safe interpreters cannot
|
||||
modify tcl_precision. The new object system in Tcl 8.0 causes
|
||||
floating-to-string conversions (and the associated rounding) to
|
||||
occur much less often than in Tcl 7.6, which can sometimes cause
|
||||
behavioral changes.
|
||||
|
||||
6. The C APIs associated with the notifier have changed substantially.
|
||||
|
||||
7. The procedures Tcl_CreateModalTimeout and Tcl_DeleteModalTimeout
|
||||
have been removed.
|
||||
|
||||
8. Tcl_CreateFileHandler and Tcl_DeleteFileHandler now take Unix
|
||||
fd's and are only supported on the Unix platform
|
||||
|
||||
9. The C APIs for creating channel drivers have changed as part of
|
||||
the new notifier implementation. The Tcl_File interfaces have been
|
||||
removed. Tcl_GetChannelFile has been replaced with
|
||||
Tcl_GetChannelHandle. Tcl_MakeFileChannel now takes a platform-
|
||||
specific file handle. Tcl_DriverGetOptionProc procedures now take
|
||||
an additional interp argument.
|
||||
|
||||
5. Tcl newsgroup
|
||||
-----------------
|
||||
|
||||
There is a network news group "comp.lang.tcl" intended for the exchange
|
||||
of information about Tcl, Tk, and related applications. Feel free to use
|
||||
the newsgroup both for general information questions and for bug reports.
|
||||
We read the newsgroup and will attempt to fix bugs and problems reported
|
||||
to it.
|
||||
|
||||
When using comp.lang.tcl, please be sure that your e-mail return address
|
||||
is correctly set in your postings. This allows people to respond directly
|
||||
to you, rather than the entire newsgroup, for answers that are not of
|
||||
general interest. A bad e-mail return address may prevent you from
|
||||
getting answers to your questions. You may have to reconfigure your news
|
||||
reading software to ensure that it is supplying valid e-mail addresses.
|
||||
|
||||
6. Tcl contributed archive
|
||||
--------------------------
|
||||
|
||||
Many people have created exciting packages and applications based on Tcl
|
||||
and/or Tk and made them freely available to the Tcl community. An archive
|
||||
of these contributions is kept on the machine ftp.neosoft.com. You
|
||||
can access the archive using anonymous FTP; the Tcl contributed archive is
|
||||
in the directory "/pub/tcl". The archive also contains several FAQ
|
||||
("frequently asked questions") documents that provide solutions to problems
|
||||
that are commonly encountered by TCL newcomers.
|
||||
|
||||
7. Mailing lists
|
||||
----------------
|
||||
|
||||
A couple of Mailing List have been set up to discuss Macintosh or
|
||||
Windows related Tcl issues. In order to use these Mailing Lists you
|
||||
must have access to the internet. If you have access to the WWW the
|
||||
home pages for these mailing lists are located at the following URLs:
|
||||
|
||||
http://www.sunlabs.com/research/tcl/lists/mactcl-list.html
|
||||
|
||||
-and-
|
||||
|
||||
http://www.sunlabs.com/research/tcl/lists/wintcl-list.html
|
||||
|
||||
The home pages contain information about the lists and an HTML archive
|
||||
of all the past messages on the list. To subscribe send a message to:
|
||||
|
||||
listserv@sunlabs.sun.com
|
||||
|
||||
In the body of the message (the subject will be ignored) put:
|
||||
|
||||
subscribe mactcl Joe Blow
|
||||
|
||||
Replacing Joe Blow with your real name, of course. (Use wintcl
|
||||
instead of mactcl if your interested in the Windows list.) If you
|
||||
would just like to receive more information about the list without
|
||||
subscribing put the line:
|
||||
|
||||
information mactcl
|
||||
|
||||
in the body instead (or wintcl).
|
||||
|
||||
8. Support and bug fixes
|
||||
------------------------
|
||||
|
||||
We're very interested in receiving bug reports and suggestions for
|
||||
improvements. We prefer that you send this information to the
|
||||
comp.lang.tcl newsgroup rather than to any of us at Sun. We'll see
|
||||
anything on comp.lang.tcl, and in addition someone else who reads
|
||||
comp.lang.tcl may be able to offer a solution. The normal turn-around
|
||||
time for bugs is 3-6 weeks. Enhancements may take longer and may not
|
||||
happen at all unless there is widespread support for them (we're
|
||||
trying to slow the rate at which Tcl turns into a kitchen sink). It's
|
||||
very difficult to make incompatible changes to Tcl at this point, due
|
||||
to the size of the installed base.
|
||||
|
||||
When reporting bugs, please provide a short tclsh script that we can
|
||||
use to reproduce the bug. Make sure that the script runs with a
|
||||
bare-bones tclsh and doesn't depend on any extensions or other
|
||||
programs, particularly those that exist only at your site. Also,
|
||||
please include three additional pieces of information with the
|
||||
script:
|
||||
(a) how do we use the script to make the problem happen (e.g.
|
||||
what things do we click on, in what order)?
|
||||
(b) what happens when you do these things (presumably this is
|
||||
undesirable)?
|
||||
(c) what did you expect to happen instead?
|
||||
|
||||
The Tcl community is too large for us to provide much individual
|
||||
support for users. If you need help we suggest that you post questions
|
||||
to comp.lang.tcl. We read the newsgroup and will attempt to answer
|
||||
esoteric questions for which no-one else is likely to know the answer.
|
||||
In addition, Tcl support and training are available commercially from
|
||||
NeoSoft (info@neosoft.com), Computerized Processes Unlimited
|
||||
(gwl@cpu.com), and Data Kinetics (education@dkl.com).
|
||||
|
||||
9. Tcl version numbers
|
||||
----------------------
|
||||
|
||||
Each Tcl release is identified by two numbers separated by a dot, e.g.
|
||||
6.7 or 7.0. If a new release contains changes that are likely to break
|
||||
existing C code or Tcl scripts then the major release number increments
|
||||
and the minor number resets to zero: 6.0, 7.0, etc. If a new release
|
||||
contains only bug fixes and compatible changes, then the minor number
|
||||
increments without changing the major number, e.g. 7.1, 7.2, etc. If
|
||||
you have C code or Tcl scripts that work with release X.Y, then they
|
||||
should also work with any release X.Z as long as Z > Y.
|
||||
|
||||
Alpha and beta releases have an additional suffix of the form a2 or b1.
|
||||
For example, Tcl 7.0b1 is the first beta release of Tcl version 7.0,
|
||||
Tcl 7.0b2 is the second beta release, and so on. A beta release is an
|
||||
initial version of a new release, used to fix bugs and bad features before
|
||||
declaring the release stable. An alpha release is like a beta release,
|
||||
except it's likely to need even more work before it's "ready for prime
|
||||
time". New releases are normally preceded by one or more alpha and beta
|
||||
releases. We hope that lots of people will try out the alpha and beta
|
||||
releases and report problems. We'll make new alpha/beta releases to fix
|
||||
the problems, until eventually there is a beta release that appears to
|
||||
be stable. Once this occurs we'll make the final release.
|
||||
|
||||
We can't promise to maintain compatibility among alpha and beta releases.
|
||||
For example, release 7.1b2 may not be backward compatible with 7.1b1, even
|
||||
though the final 7.1 release will be backward compatible with 7.0. This
|
||||
allows us to change new features as we find problems during beta testing.
|
||||
We'll try to minimize incompatibilities between beta releases, but if
|
||||
a major problem turns up then we'll fix it even if it introduces an
|
||||
incompatibility. Once the official release is made then there won't
|
||||
be any more incompatibilities until the next release with a new major
|
||||
version number.
|
||||
|
||||
Patch releases have a suffix such as p1 or p2. These releases contain
|
||||
bug fixes only. A patch release (e.g Tcl 7.6p2) should be completely
|
||||
compatible with the base release from which it is derived (e.g. Tcl
|
||||
7.6), and you should normally use the highest available patch release.
|
||||
-3453
File diff suppressed because it is too large
Load Diff
@@ -1,8 +0,0 @@
|
||||
This directory contains various header and code files that are
|
||||
used make Tcl compatible with various releases of UNIX and UNIX-like
|
||||
systems. Typically, files from this directory are used to compile
|
||||
Tcl when a system doesn't contain the corresponding files or when
|
||||
they are known to be incorrect. When the whole world becomes POSIX-
|
||||
compliant this directory should be unnecessary.
|
||||
|
||||
sccsid = SCCS: @(#) README 1.3 96/02/16 08:56:51
|
||||
@@ -1,23 +0,0 @@
|
||||
/*
|
||||
* dirent.h --
|
||||
*
|
||||
* This file is a replacement for <dirent.h> in systems that
|
||||
* support the old BSD-style <sys/dir.h> with a "struct direct".
|
||||
*
|
||||
* Copyright (c) 1991 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) dirent.h 1.4 96/02/15 14:43:50
|
||||
*/
|
||||
|
||||
#ifndef _DIRENT
|
||||
#define _DIRENT
|
||||
|
||||
#include <sys/dir.h>
|
||||
|
||||
#define dirent direct
|
||||
|
||||
#endif /* _DIRENT */
|
||||
@@ -1,59 +0,0 @@
|
||||
/*
|
||||
* dirent.h --
|
||||
*
|
||||
* Declarations of a library of directory-reading procedures
|
||||
* in the POSIX style ("struct dirent").
|
||||
*
|
||||
* Copyright (c) 1991 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) dirent2.h 1.4 96/02/15 14:43:51
|
||||
*/
|
||||
|
||||
#ifndef _DIRENT
|
||||
#define _DIRENT
|
||||
|
||||
#ifndef _TCL
|
||||
#include <tcl.h>
|
||||
#endif
|
||||
|
||||
/*
|
||||
* Dirent structure, which holds information about a single
|
||||
* directory entry.
|
||||
*/
|
||||
|
||||
#define MAXNAMLEN 255
|
||||
#define DIRBLKSIZ 512
|
||||
|
||||
struct dirent {
|
||||
long d_ino; /* Inode number of entry */
|
||||
short d_reclen; /* Length of this record */
|
||||
short d_namlen; /* Length of string in d_name */
|
||||
char d_name[MAXNAMLEN + 1]; /* Name must be no longer than this */
|
||||
};
|
||||
|
||||
/*
|
||||
* State that keeps track of the reading of a directory (clients
|
||||
* should never look inside this structure; the fields should
|
||||
* only be accessed by the library procedures).
|
||||
*/
|
||||
|
||||
typedef struct _dirdesc {
|
||||
int dd_fd;
|
||||
long dd_loc;
|
||||
long dd_size;
|
||||
char dd_buf[DIRBLKSIZ];
|
||||
} DIR;
|
||||
|
||||
/*
|
||||
* Procedures defined for reading directories:
|
||||
*/
|
||||
|
||||
extern void closedir _ANSI_ARGS_((DIR *dirp));
|
||||
extern DIR * opendir _ANSI_ARGS_((char *name));
|
||||
extern struct dirent * readdir _ANSI_ARGS_((DIR *dirp));
|
||||
|
||||
#endif /* _DIRENT */
|
||||
@@ -1,65 +0,0 @@
|
||||
/*
|
||||
* dlfcn.h --
|
||||
*
|
||||
* This file provides a replacement for the header file "dlfcn.h"
|
||||
* on systems where dlfcn.h is missing. It's primary use is for
|
||||
* AIX, where Tcl emulates the dl library.
|
||||
*
|
||||
* This file is subject to the following copyright notice, which is
|
||||
* different from the notice used elsewhere in Tcl but rougly
|
||||
* equivalent in meaning.
|
||||
*
|
||||
* Copyright (c) 1992,1993,1995,1996, Jens-Uwe Mager, Helios Software GmbH
|
||||
* Not derived from licensed software.
|
||||
*
|
||||
* Permission is granted to freely use, copy, modify, and redistribute
|
||||
* this software, provided that the author is not construed to be liable
|
||||
* for any results of using the software, alterations are clearly marked
|
||||
* as such, and this notice is not modified.
|
||||
*
|
||||
* SCCS: @(#) dlfcn.h 1.4 96/09/17 09:05:59
|
||||
*/
|
||||
|
||||
/*
|
||||
* @(#)dlfcn.h 1.4 revision of 95/04/25 09:36:52
|
||||
* This is an unpublished work copyright (c) 1992 HELIOS Software GmbH
|
||||
* 30159 Hannover, Germany
|
||||
*/
|
||||
|
||||
#ifndef __dlfcn_h__
|
||||
#define __dlfcn_h__
|
||||
|
||||
#ifndef _TCL
|
||||
#include <tcl.h>
|
||||
#endif
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
/*
|
||||
* Mode flags for the dlopen routine.
|
||||
*/
|
||||
#define RTLD_LAZY 1 /* lazy function call binding */
|
||||
#define RTLD_NOW 2 /* immediate function call binding */
|
||||
#define RTLD_GLOBAL 0x100 /* allow symbols to be global */
|
||||
|
||||
/*
|
||||
* To be able to intialize, a library may provide a dl_info structure
|
||||
* that contains functions to be called to initialize and terminate.
|
||||
*/
|
||||
struct dl_info {
|
||||
void (*init) _ANSI_ARGS_((void));
|
||||
void (*fini) _ANSI_ARGS_((void));
|
||||
};
|
||||
|
||||
VOID *dlopen _ANSI_ARGS_((const char *path, int mode));
|
||||
VOID *dlsym _ANSI_ARGS_((void *handle, const char *symbol));
|
||||
char *dlerror _ANSI_ARGS_((void));
|
||||
int dlclose _ANSI_ARGS_((void *handle));
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* __dlfcn_h__ */
|
||||
@@ -1,38 +0,0 @@
|
||||
/*
|
||||
* fixstrtod.c --
|
||||
*
|
||||
* Source code for the "fixstrtod" procedure. This procedure is
|
||||
* used in place of strtod under Solaris 2.4, in order to fix
|
||||
* a bug where the "end" pointer gets set incorrectly.
|
||||
*
|
||||
* Copyright (c) 1995 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) fixstrtod.c 1.5 96/02/15 12:08:21
|
||||
*/
|
||||
|
||||
#include <stdio.h>
|
||||
|
||||
#undef strtod
|
||||
|
||||
/*
|
||||
* Declare strtod explicitly rather than including stdlib.h, since in
|
||||
* somes systems (e.g. SunOS 4.1.4) stdlib.h doesn't declare strtod.
|
||||
*/
|
||||
|
||||
extern double strtod();
|
||||
|
||||
double
|
||||
fixstrtod(string, endPtr)
|
||||
char *string;
|
||||
char **endPtr;
|
||||
{
|
||||
double d;
|
||||
d = strtod(string, endPtr);
|
||||
if ((endPtr != NULL) && (*endPtr != string) && ((*endPtr)[-1] == 0)) {
|
||||
*endPtr -= 1;
|
||||
}
|
||||
return d;
|
||||
}
|
||||
@@ -1,16 +0,0 @@
|
||||
/*
|
||||
* float.h --
|
||||
*
|
||||
* This is a dummy header file to #include in Tcl when there
|
||||
* is no float.h in /usr/include. Right now this file is empty:
|
||||
* Tcl contains #ifdefs to deal with the lack of definitions;
|
||||
* all it needs is for the #include statement to work.
|
||||
*
|
||||
* Copyright (c) 1993 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) float.h 1.3 96/02/15 14:43:52
|
||||
*/
|
||||
@@ -1,32 +0,0 @@
|
||||
/*
|
||||
* gettod.c --
|
||||
*
|
||||
* This file provides the gettimeofday function on systems
|
||||
* that only have the System V ftime function.
|
||||
*
|
||||
* Copyright (c) 1995 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) gettod.c 1.2 96/02/15 12:08:26
|
||||
*/
|
||||
|
||||
#include "tcl.h"
|
||||
#include "tclPort.h"
|
||||
#include <sys/timeb.h>
|
||||
|
||||
#undef timezone
|
||||
|
||||
int
|
||||
gettimeofday(tp, tz)
|
||||
struct timeval *tp;
|
||||
struct timezone *tz;
|
||||
{
|
||||
struct timeb t;
|
||||
ftime(&t);
|
||||
tp->tv_sec = t.time;
|
||||
tp->tv_usec = t. millitm * 1000;
|
||||
return 0;
|
||||
}
|
||||
|
||||
@@ -1,39 +0,0 @@
|
||||
This software is copyrighted by the Regents of the University of
|
||||
California, Sun Microsystems, Inc., and other parties. The following
|
||||
terms apply to all files associated with the software unless explicitly
|
||||
disclaimed in individual files.
|
||||
|
||||
The authors hereby grant permission to use, copy, modify, distribute,
|
||||
and license this software and its documentation for any purpose, provided
|
||||
that existing copyright notices are retained in all copies and that this
|
||||
notice is included verbatim in any distributions. No written agreement,
|
||||
license, or royalty fee is required for any of the authorized uses.
|
||||
Modifications to this software may be copyrighted by their authors
|
||||
and need not follow the licensing terms described here, provided that
|
||||
the new terms are clearly indicated on the first page of each file where
|
||||
they apply.
|
||||
|
||||
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY
|
||||
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
|
||||
ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY
|
||||
DERIVATIVES THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE
|
||||
POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES,
|
||||
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE
|
||||
IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE
|
||||
NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR
|
||||
MODIFICATIONS.
|
||||
|
||||
GOVERNMENT USE: If you are acquiring this software on behalf of the
|
||||
U.S. government, the Government shall have only "Restricted Rights"
|
||||
in the software and related documentation as defined in the Federal
|
||||
Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you
|
||||
are acquiring the software on behalf of the Department of Defense, the
|
||||
software shall be classified as "Commercial Computer Software" and the
|
||||
Government shall have only "Restricted Rights" as defined in Clause
|
||||
252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the
|
||||
authors grant the U.S. Government and others acting in its behalf
|
||||
permission to use and distribute the software in accordance with the
|
||||
terms specified in this license.
|
||||
@@ -1,24 +0,0 @@
|
||||
/*
|
||||
* limits.h --
|
||||
*
|
||||
* This is a dummy header file to #include in Tcl when there
|
||||
* is no limits.h in /usr/include. There are only a few
|
||||
* definitions here; also see tclPort.h, which already
|
||||
* #defines some of the things here if they're not arleady
|
||||
* defined.
|
||||
*
|
||||
* Copyright (c) 1991 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) limits.h 1.8 96/07/08 18:00:13
|
||||
*/
|
||||
|
||||
#define LONG_MIN 0x80000000
|
||||
#define LONG_MAX 0x7fffffff
|
||||
#define INT_MIN 0x80000000
|
||||
#define INT_MAX 0x7fffffff
|
||||
#define SHRT_MIN 0x8000
|
||||
#define SHRT_MAX 0x7fff
|
||||
@@ -1,108 +0,0 @@
|
||||
/*
|
||||
* opendir.c --
|
||||
*
|
||||
* This file provides dirent-style directory-reading procedures
|
||||
* for V7 Unix systems that don't have such procedures. The
|
||||
* origin of this code is unclear, but it seems to have come
|
||||
* originally from Larry Wall.
|
||||
*
|
||||
*
|
||||
* SCCS: @(#) opendir.c 1.3 96/02/15 12:08:21
|
||||
*/
|
||||
|
||||
#include "tclInt.h"
|
||||
#include "tclPort.h"
|
||||
|
||||
#undef DIRSIZ
|
||||
#define DIRSIZ(dp) \
|
||||
((sizeof (struct dirent) - (MAXNAMLEN+1)) + (((dp)->d_namlen+1 + 3) &~ 3))
|
||||
|
||||
/*
|
||||
* open a directory.
|
||||
*/
|
||||
DIR *
|
||||
opendir(name)
|
||||
char *name;
|
||||
{
|
||||
register DIR *dirp;
|
||||
register int fd;
|
||||
char *myname;
|
||||
|
||||
myname = ((*name == '\0') ? "." : name);
|
||||
if ((fd = open(myname, 0, 0)) == -1)
|
||||
return NULL;
|
||||
if ((dirp = (DIR *)ckalloc(sizeof(DIR))) == NULL) {
|
||||
close (fd);
|
||||
return NULL;
|
||||
}
|
||||
dirp->dd_fd = fd;
|
||||
dirp->dd_loc = 0;
|
||||
return dirp;
|
||||
}
|
||||
|
||||
/*
|
||||
* read an old style directory entry and present it as a new one
|
||||
*/
|
||||
#ifndef pyr
|
||||
#define ODIRSIZ 14
|
||||
|
||||
struct olddirect {
|
||||
ino_t od_ino;
|
||||
char od_name[ODIRSIZ];
|
||||
};
|
||||
#else /* a Pyramid in the ATT universe */
|
||||
#define ODIRSIZ 248
|
||||
|
||||
struct olddirect {
|
||||
long od_ino;
|
||||
short od_fill1, od_fill2;
|
||||
char od_name[ODIRSIZ];
|
||||
};
|
||||
#endif
|
||||
|
||||
/*
|
||||
* get next entry in a directory.
|
||||
*/
|
||||
struct dirent *
|
||||
readdir(dirp)
|
||||
register DIR *dirp;
|
||||
{
|
||||
register struct olddirect *dp;
|
||||
static struct dirent dir;
|
||||
|
||||
for (;;) {
|
||||
if (dirp->dd_loc == 0) {
|
||||
dirp->dd_size = read(dirp->dd_fd, dirp->dd_buf,
|
||||
DIRBLKSIZ);
|
||||
if (dirp->dd_size <= 0)
|
||||
return NULL;
|
||||
}
|
||||
if (dirp->dd_loc >= dirp->dd_size) {
|
||||
dirp->dd_loc = 0;
|
||||
continue;
|
||||
}
|
||||
dp = (struct olddirect *)(dirp->dd_buf + dirp->dd_loc);
|
||||
dirp->dd_loc += sizeof(struct olddirect);
|
||||
if (dp->od_ino == 0)
|
||||
continue;
|
||||
dir.d_ino = dp->od_ino;
|
||||
strncpy(dir.d_name, dp->od_name, ODIRSIZ);
|
||||
dir.d_name[ODIRSIZ] = '\0'; /* insure null termination */
|
||||
dir.d_namlen = strlen(dir.d_name);
|
||||
dir.d_reclen = DIRSIZ(&dir);
|
||||
return (&dir);
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* close a directory.
|
||||
*/
|
||||
void
|
||||
closedir(dirp)
|
||||
register DIR *dirp;
|
||||
{
|
||||
close(dirp->dd_fd);
|
||||
dirp->dd_fd = -1;
|
||||
dirp->dd_loc = 0;
|
||||
ckfree((char *) dirp);
|
||||
}
|
||||
@@ -1,45 +0,0 @@
|
||||
/*
|
||||
* stdlib.h --
|
||||
*
|
||||
* Declares facilities exported by the "stdlib" portion of
|
||||
* the C library. This file isn't complete in the ANSI-C
|
||||
* sense; it only declares things that are needed by Tcl.
|
||||
* This file is needed even on many systems with their own
|
||||
* stdlib.h (e.g. SunOS) because not all stdlib.h files
|
||||
* declare all the procedures needed here (such as strtod).
|
||||
*
|
||||
* Copyright (c) 1991 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) stdlib.h 1.10 96/02/15 14:43:54
|
||||
*/
|
||||
|
||||
#ifndef _STDLIB
|
||||
#define _STDLIB
|
||||
|
||||
#include <tcl.h>
|
||||
|
||||
extern void abort _ANSI_ARGS_((void));
|
||||
extern double atof _ANSI_ARGS_((CONST char *string));
|
||||
extern int atoi _ANSI_ARGS_((CONST char *string));
|
||||
extern long atol _ANSI_ARGS_((CONST char *string));
|
||||
extern char * calloc _ANSI_ARGS_((unsigned int numElements,
|
||||
unsigned int size));
|
||||
extern void exit _ANSI_ARGS_((int status));
|
||||
extern int free _ANSI_ARGS_((char *blockPtr));
|
||||
extern char * getenv _ANSI_ARGS_((CONST char *name));
|
||||
extern char * malloc _ANSI_ARGS_((unsigned int numBytes));
|
||||
extern void qsort _ANSI_ARGS_((VOID *base, int n, int size,
|
||||
int (*compar)(CONST VOID *element1, CONST VOID
|
||||
*element2)));
|
||||
extern char * realloc _ANSI_ARGS_((char *ptr, unsigned int numBytes));
|
||||
extern double strtod _ANSI_ARGS_((CONST char *string, char **endPtr));
|
||||
extern long strtol _ANSI_ARGS_((CONST char *string, char **endPtr,
|
||||
int base));
|
||||
extern unsigned long strtoul _ANSI_ARGS_((CONST char *string,
|
||||
char **endPtr, int base));
|
||||
|
||||
#endif /* _STDLIB */
|
||||
@@ -1,385 +0,0 @@
|
||||
/*
|
||||
* strftime.c --
|
||||
*
|
||||
* This file contains a modified version of the BSD 4.4 strftime
|
||||
* function.
|
||||
*
|
||||
* This file is a modified version of the strftime.c file from the BSD 4.4
|
||||
* source. See the copyright notice below for details on redistribution
|
||||
* restrictions. The "license.terms" file does not apply to this file.
|
||||
*
|
||||
* SCCS: @(#) strftime.c 1.4 97/08/07 17:17:02
|
||||
*/
|
||||
|
||||
/*
|
||||
* Copyright (c) 1989 The Regents of the University of California.
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms, with or without
|
||||
* modification, are permitted provided that the following conditions
|
||||
* are met:
|
||||
* 1. Redistributions of source code must retain the above copyright
|
||||
* notice, this list of conditions and the following disclaimer.
|
||||
* 2. Redistributions in binary form must reproduce the above copyright
|
||||
* notice, this list of conditions and the following disclaimer in the
|
||||
* documentation and/or other materials provided with the distribution.
|
||||
* 3. All advertising materials mentioning features or use of this software
|
||||
* must display the following acknowledgement:
|
||||
* This product includes software developed by the University of
|
||||
* California, Berkeley and its contributors.
|
||||
* 4. Neither the name of the University nor the names of its contributors
|
||||
* may be used to endorse or promote products derived from this software
|
||||
* without specific prior written permission.
|
||||
*
|
||||
* THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
||||
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
* IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
* ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
||||
* FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
* DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
* OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
* HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
* LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
* OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
* SUCH DAMAGE.
|
||||
*/
|
||||
|
||||
#if defined(LIBC_SCCS) && !defined(lint)
|
||||
/*static char *sccsid = "from: @(#)strftime.c 5.11 (Berkeley) 2/24/91";*/
|
||||
static char *rcsid = "$Id$";
|
||||
#endif /* LIBC_SCCS and not lint */
|
||||
|
||||
#include <time.h>
|
||||
#include <string.h>
|
||||
#include <locale.h>
|
||||
#include "tclInt.h"
|
||||
#include "tclPort.h"
|
||||
|
||||
#define TM_YEAR_BASE 1900
|
||||
|
||||
typedef struct {
|
||||
const char *abday[7];
|
||||
const char *day[7];
|
||||
const char *abmon[12];
|
||||
const char *mon[12];
|
||||
const char *am_pm[2];
|
||||
const char *d_t_fmt;
|
||||
const char *d_fmt;
|
||||
const char *t_fmt;
|
||||
const char *t_fmt_ampm;
|
||||
} _TimeLocale;
|
||||
|
||||
static const _TimeLocale _DefaultTimeLocale =
|
||||
{
|
||||
{
|
||||
"Sun","Mon","Tue","Wed","Thu","Fri","Sat",
|
||||
},
|
||||
{
|
||||
"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday",
|
||||
"Friday", "Saturday"
|
||||
},
|
||||
{
|
||||
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
|
||||
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
|
||||
},
|
||||
{
|
||||
"January", "February", "March", "April", "May", "June", "July",
|
||||
"August", "September", "October", "November", "December"
|
||||
},
|
||||
{
|
||||
"AM", "PM"
|
||||
},
|
||||
"%a %b %d %H:%M:%S %Y",
|
||||
"%m/%d/%y",
|
||||
"%H:%M:%S",
|
||||
"%I:%M:%S %p"
|
||||
};
|
||||
|
||||
static const _TimeLocale *_CurrentTimeLocale = &_DefaultTimeLocale;
|
||||
|
||||
static size_t gsize;
|
||||
static char *pt;
|
||||
static int _add _ANSI_ARGS_((const char* str));
|
||||
static int _conv _ANSI_ARGS_((int n, int digits, int pad));
|
||||
static int _secs _ANSI_ARGS_((const struct tm *t));
|
||||
static size_t _fmt _ANSI_ARGS_((const char *format,
|
||||
const struct tm *t));
|
||||
|
||||
size_t
|
||||
TclStrftime(s, maxsize, format, t)
|
||||
char *s;
|
||||
size_t maxsize;
|
||||
const char *format;
|
||||
const struct tm *t;
|
||||
{
|
||||
tzset();
|
||||
|
||||
pt = s;
|
||||
if ((gsize = maxsize) < 1)
|
||||
return(0);
|
||||
if (_fmt(format, t)) {
|
||||
*pt = '\0';
|
||||
return(maxsize - gsize);
|
||||
}
|
||||
return(0);
|
||||
}
|
||||
|
||||
#define SUN_WEEK(t) (((t)->tm_yday + 7 - \
|
||||
((t)->tm_wday)) / 7)
|
||||
#define MON_WEEK(t) (((t)->tm_yday + 7 - \
|
||||
((t)->tm_wday ? (t)->tm_wday - 1 : 6)) / 7)
|
||||
|
||||
static size_t
|
||||
_fmt(format, t)
|
||||
const char *format;
|
||||
const struct tm *t;
|
||||
{
|
||||
for (; *format; ++format) {
|
||||
if (*format == '%') {
|
||||
++format;
|
||||
if (*format == 'E') {
|
||||
/* Alternate Era */
|
||||
++format;
|
||||
} else if (*format == 'O') {
|
||||
/* Alternate numeric symbols */
|
||||
++format;
|
||||
}
|
||||
switch(*format) {
|
||||
case '\0':
|
||||
--format;
|
||||
break;
|
||||
case 'A':
|
||||
if (t->tm_wday < 0 || t->tm_wday > 6)
|
||||
return(0);
|
||||
if (!_add(_CurrentTimeLocale->day[t->tm_wday]))
|
||||
return(0);
|
||||
continue;
|
||||
case 'a':
|
||||
if (t->tm_wday < 0 || t->tm_wday > 6)
|
||||
return(0);
|
||||
if (!_add(_CurrentTimeLocale->abday[t->tm_wday]))
|
||||
return(0);
|
||||
continue;
|
||||
case 'B':
|
||||
if (t->tm_mon < 0 || t->tm_mon > 11)
|
||||
return(0);
|
||||
if (!_add(_CurrentTimeLocale->mon[t->tm_mon]))
|
||||
return(0);
|
||||
continue;
|
||||
case 'b':
|
||||
case 'h':
|
||||
if (t->tm_mon < 0 || t->tm_mon > 11)
|
||||
return(0);
|
||||
if (!_add(_CurrentTimeLocale->abmon[t->tm_mon]))
|
||||
return(0);
|
||||
continue;
|
||||
case 'C':
|
||||
if (!_conv((t->tm_year + TM_YEAR_BASE) / 100,
|
||||
2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'c':
|
||||
if (!_fmt(_CurrentTimeLocale->d_t_fmt, t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'D':
|
||||
if (!_fmt("%m/%d/%y", t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'd':
|
||||
if (!_conv(t->tm_mday, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'e':
|
||||
if (!_conv(t->tm_mday, 2, ' '))
|
||||
return(0);
|
||||
continue;
|
||||
case 'H':
|
||||
if (!_conv(t->tm_hour, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'I':
|
||||
if (!_conv(t->tm_hour % 12 ?
|
||||
t->tm_hour % 12 : 12, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'j':
|
||||
if (!_conv(t->tm_yday + 1, 3, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'k':
|
||||
if (!_conv(t->tm_hour, 2, ' '))
|
||||
return(0);
|
||||
continue;
|
||||
case 'l':
|
||||
if (!_conv(t->tm_hour % 12 ?
|
||||
t->tm_hour % 12: 12, 2, ' '))
|
||||
return(0);
|
||||
continue;
|
||||
case 'M':
|
||||
if (!_conv(t->tm_min, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'm':
|
||||
if (!_conv(t->tm_mon + 1, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'n':
|
||||
if (!_add("\n"))
|
||||
return(0);
|
||||
continue;
|
||||
case 'p':
|
||||
if (!_add(_CurrentTimeLocale->am_pm[t->tm_hour >= 12]))
|
||||
return(0);
|
||||
continue;
|
||||
case 'R':
|
||||
if (!_fmt("%H:%M", t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'r':
|
||||
if (!_fmt(_CurrentTimeLocale->t_fmt_ampm, t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'S':
|
||||
if (!_conv(t->tm_sec, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 's':
|
||||
if (!_secs(t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'T':
|
||||
if (!_fmt("%H:%M:%S", t))
|
||||
return(0);
|
||||
continue;
|
||||
case 't':
|
||||
if (!_add("\t"))
|
||||
return(0);
|
||||
continue;
|
||||
case 'U':
|
||||
if (!_conv(SUN_WEEK(t), 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'u':
|
||||
if (!_conv(t->tm_wday ? t->tm_wday : 7, 1, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'V':
|
||||
{
|
||||
/* ISO 8601 Week Of Year:
|
||||
If the week (Monday - Sunday) containing
|
||||
January 1 has four or more days in the new
|
||||
year, then it is week 1; otherwise it is
|
||||
week 53 of the previous year and the next
|
||||
week is week one. */
|
||||
|
||||
int week = MON_WEEK(t);
|
||||
|
||||
int days = (((t)->tm_yday + 7 - \
|
||||
((t)->tm_wday ? (t)->tm_wday - 1 : 6)) % 7);
|
||||
|
||||
|
||||
if (days >= 4) {
|
||||
week++;
|
||||
} else if (week == 0) {
|
||||
week = 53;
|
||||
}
|
||||
|
||||
if (!_conv(week, 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
}
|
||||
case 'W':
|
||||
if (!_conv(MON_WEEK(t), 2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'w':
|
||||
if (!_conv(t->tm_wday, 1, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'x':
|
||||
if (!_fmt(_CurrentTimeLocale->d_fmt, t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'X':
|
||||
if (!_fmt(_CurrentTimeLocale->t_fmt, t))
|
||||
return(0);
|
||||
continue;
|
||||
case 'y':
|
||||
if (!_conv((t->tm_year + TM_YEAR_BASE) % 100,
|
||||
2, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
case 'Y':
|
||||
if (!_conv((t->tm_year + TM_YEAR_BASE), 4, '0'))
|
||||
return(0);
|
||||
continue;
|
||||
#ifndef MAC_TCL
|
||||
case 'Z': {
|
||||
char *name = TclpGetTZName();
|
||||
if (name && !_add(name)) {
|
||||
return 0;
|
||||
}
|
||||
continue;
|
||||
}
|
||||
#endif
|
||||
case '%':
|
||||
/*
|
||||
* X311J/88-090 (4.12.3.5): if conversion char is
|
||||
* undefined, behavior is undefined. Print out the
|
||||
* character itself as printf(3) does.
|
||||
*/
|
||||
default:
|
||||
break;
|
||||
}
|
||||
}
|
||||
if (!gsize--)
|
||||
return(0);
|
||||
*pt++ = *format;
|
||||
}
|
||||
return(gsize);
|
||||
}
|
||||
|
||||
static int
|
||||
_secs(t)
|
||||
const struct tm *t;
|
||||
{
|
||||
static char buf[15];
|
||||
register time_t s;
|
||||
register char *p;
|
||||
struct tm tmp;
|
||||
|
||||
/* Make a copy, mktime(3) modifies the tm struct. */
|
||||
tmp = *t;
|
||||
s = mktime(&tmp);
|
||||
for (p = buf + sizeof(buf) - 2; s > 0 && p > buf; s /= 10)
|
||||
*p-- = (char)(s % 10 + '0');
|
||||
return(_add(++p));
|
||||
}
|
||||
|
||||
static int
|
||||
_conv(n, digits, pad)
|
||||
int n, digits;
|
||||
int pad;
|
||||
{
|
||||
static char buf[10];
|
||||
register char *p;
|
||||
|
||||
for (p = buf + sizeof(buf) - 2; n > 0 && p > buf; n /= 10, --digits)
|
||||
*p-- = (char)(n % 10 + '0');
|
||||
while (p > buf && digits-- > 0)
|
||||
*p-- = (char) pad;
|
||||
return(_add(++p));
|
||||
}
|
||||
|
||||
static int
|
||||
_add(str)
|
||||
const char *str;
|
||||
{
|
||||
for (;; ++pt, --gsize) {
|
||||
if (!gsize)
|
||||
return(0);
|
||||
if (!(*pt = *str++))
|
||||
return(1);
|
||||
}
|
||||
}
|
||||
@@ -1,66 +0,0 @@
|
||||
/*
|
||||
* string.h --
|
||||
*
|
||||
* Declarations of ANSI C library procedures for string handling.
|
||||
*
|
||||
* Copyright (c) 1991-1993 The Regents of the University of California.
|
||||
* Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) string.h 1.13 96/04/09 22:14:53
|
||||
*/
|
||||
|
||||
#ifndef _STRING
|
||||
#define _STRING
|
||||
|
||||
#include <tcl.h>
|
||||
|
||||
/*
|
||||
* The following #include is needed to define size_t. (This used to
|
||||
* include sys/stdtypes.h but that doesn't exist on older versions
|
||||
* of SunOS, e.g. 4.0.2, so I'm trying sys/types.h now.... hopefully
|
||||
* it exists everywhere)
|
||||
*/
|
||||
|
||||
#ifndef MAC_TCL
|
||||
#include <sys/types.h>
|
||||
#endif
|
||||
|
||||
extern char * memchr _ANSI_ARGS_((CONST VOID *s, int c, size_t n));
|
||||
extern int memcmp _ANSI_ARGS_((CONST VOID *s1, CONST VOID *s2,
|
||||
size_t n));
|
||||
extern char * memcpy _ANSI_ARGS_((VOID *t, CONST VOID *f, size_t n));
|
||||
extern char * memmove _ANSI_ARGS_((VOID *t, CONST VOID *f,
|
||||
size_t n));
|
||||
extern char * memset _ANSI_ARGS_((VOID *s, int c, size_t n));
|
||||
|
||||
extern int strcasecmp _ANSI_ARGS_((CONST char *s1,
|
||||
CONST char *s2));
|
||||
extern char * strcat _ANSI_ARGS_((char *dst, CONST char *src));
|
||||
extern char * strchr _ANSI_ARGS_((CONST char *string, int c));
|
||||
extern int strcmp _ANSI_ARGS_((CONST char *s1, CONST char *s2));
|
||||
extern char * strcpy _ANSI_ARGS_((char *dst, CONST char *src));
|
||||
extern size_t strcspn _ANSI_ARGS_((CONST char *string,
|
||||
CONST char *chars));
|
||||
extern char * strdup _ANSI_ARGS_((CONST char *string));
|
||||
extern char * strerror _ANSI_ARGS_((int error));
|
||||
extern size_t strlen _ANSI_ARGS_((CONST char *string));
|
||||
extern int strncasecmp _ANSI_ARGS_((CONST char *s1,
|
||||
CONST char *s2, size_t n));
|
||||
extern char * strncat _ANSI_ARGS_((char *dst, CONST char *src,
|
||||
size_t numChars));
|
||||
extern int strncmp _ANSI_ARGS_((CONST char *s1, CONST char *s2,
|
||||
size_t nChars));
|
||||
extern char * strncpy _ANSI_ARGS_((char *dst, CONST char *src,
|
||||
size_t numChars));
|
||||
extern char * strpbrk _ANSI_ARGS_((CONST char *string, char *chars));
|
||||
extern char * strrchr _ANSI_ARGS_((CONST char *string, int c));
|
||||
extern size_t strspn _ANSI_ARGS_((CONST char *string,
|
||||
CONST char *chars));
|
||||
extern char * strstr _ANSI_ARGS_((CONST char *string,
|
||||
CONST char *substring));
|
||||
extern char * strtok _ANSI_ARGS_((CONST char *s, CONST char *delim));
|
||||
|
||||
#endif /* _STRING */
|
||||
@@ -1,142 +0,0 @@
|
||||
/*
|
||||
* strncasecmp.c --
|
||||
*
|
||||
* Source code for the "strncasecmp" library routine.
|
||||
*
|
||||
* Copyright (c) 1988-1993 The Regents of the University of California.
|
||||
* Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) strncasecmp.c 1.7 96/10/24 15:23:36
|
||||
*/
|
||||
|
||||
#include "tclPort.h"
|
||||
|
||||
/*
|
||||
* This array is designed for mapping upper and lower case letter
|
||||
* together for a case independent comparison. The mappings are
|
||||
* based upon ASCII character sequences.
|
||||
*/
|
||||
|
||||
static unsigned char charmap[] = {
|
||||
0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
|
||||
0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
|
||||
0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
|
||||
0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
|
||||
0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
|
||||
0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2d, 0x2e, 0x2f,
|
||||
0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
|
||||
0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
|
||||
0x40, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
|
||||
0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f,
|
||||
0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
|
||||
0x78, 0x79, 0x7a, 0x5b, 0x5c, 0x5d, 0x5e, 0x5f,
|
||||
0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
|
||||
0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6d, 0x6e, 0x6f,
|
||||
0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
|
||||
0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
|
||||
0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87,
|
||||
0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f,
|
||||
0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97,
|
||||
0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f,
|
||||
0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7,
|
||||
0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf,
|
||||
0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7,
|
||||
0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf,
|
||||
0xc0, 0xe1, 0xe2, 0xe3, 0xe4, 0xc5, 0xe6, 0xe7,
|
||||
0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
|
||||
0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
|
||||
0xf8, 0xf9, 0xfa, 0xdb, 0xdc, 0xdd, 0xde, 0xdf,
|
||||
0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7,
|
||||
0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef,
|
||||
0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7,
|
||||
0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff,
|
||||
};
|
||||
|
||||
/*
|
||||
* Here are the prototypes just in case they are not included
|
||||
* in tclPort.h.
|
||||
*/
|
||||
int strncasecmp _ANSI_ARGS_((CONST char *s1,
|
||||
CONST char *s2, size_t n));
|
||||
|
||||
int strcasecmp _ANSI_ARGS_((CONST char *s1,
|
||||
CONST char *s2));
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strcasecmp --
|
||||
*
|
||||
* Compares two strings, ignoring case differences.
|
||||
*
|
||||
* Results:
|
||||
* Compares two null-terminated strings s1 and s2, returning -1, 0,
|
||||
* or 1 if s1 is lexicographically less than, equal to, or greater
|
||||
* than s2.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
int
|
||||
strcasecmp(s1, s2)
|
||||
CONST char *s1; /* First string. */
|
||||
CONST char *s2; /* Second string. */
|
||||
{
|
||||
unsigned char u1, u2;
|
||||
|
||||
for ( ; ; s1++, s2++) {
|
||||
u1 = (unsigned char) *s1;
|
||||
u2 = (unsigned char) *s2;
|
||||
if ((u1 == '\0') || (charmap[u1] != charmap[u2])) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
return charmap[u1] - charmap[u2];
|
||||
}
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strncasecmp --
|
||||
*
|
||||
* Compares two strings, ignoring case differences.
|
||||
*
|
||||
* Results:
|
||||
* Compares up to length chars of s1 and s2, returning -1, 0, or 1
|
||||
* if s1 is lexicographically less than, equal to, or greater
|
||||
* than s2 over those characters.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
int
|
||||
strncasecmp(s1, s2, length)
|
||||
CONST char *s1; /* First string. */
|
||||
CONST char *s2; /* Second string. */
|
||||
size_t length; /* Maximum number of characters to compare
|
||||
* (stop earlier if the end of either string
|
||||
* is reached). */
|
||||
{
|
||||
unsigned char u1, u2;
|
||||
|
||||
for (; length != 0; length--, s1++, s2++) {
|
||||
u1 = (unsigned char) *s1;
|
||||
u2 = (unsigned char) *s2;
|
||||
if (charmap[u1] != charmap[u2]) {
|
||||
return charmap[u1] - charmap[u2];
|
||||
}
|
||||
if (u1 == '\0') {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
@@ -1,68 +0,0 @@
|
||||
/*
|
||||
* strstr.c --
|
||||
*
|
||||
* Source code for the "strstr" library routine.
|
||||
*
|
||||
* Copyright (c) 1988-1993 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) strstr.c 1.4 96/02/15 12:08:22
|
||||
*/
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strstr --
|
||||
*
|
||||
* Locate the first instance of a substring in a string.
|
||||
*
|
||||
* Results:
|
||||
* If string contains substring, the return value is the
|
||||
* location of the first matching instance of substring
|
||||
* in string. If string doesn't contain substring, the
|
||||
* return value is 0. Matching is done on an exact
|
||||
* character-for-character basis with no wildcards or special
|
||||
* characters.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
char *
|
||||
strstr(string, substring)
|
||||
register char *string; /* String to search. */
|
||||
char *substring; /* Substring to try to find in string. */
|
||||
{
|
||||
register char *a, *b;
|
||||
|
||||
/* First scan quickly through the two strings looking for a
|
||||
* single-character match. When it's found, then compare the
|
||||
* rest of the substring.
|
||||
*/
|
||||
|
||||
b = substring;
|
||||
if (*b == 0) {
|
||||
return string;
|
||||
}
|
||||
for ( ; *string != 0; string += 1) {
|
||||
if (*string != *b) {
|
||||
continue;
|
||||
}
|
||||
a = string;
|
||||
while (1) {
|
||||
if (*b == 0) {
|
||||
return string;
|
||||
}
|
||||
if (*a++ != *b++) {
|
||||
break;
|
||||
}
|
||||
}
|
||||
b = substring;
|
||||
}
|
||||
return (char *) 0;
|
||||
}
|
||||
@@ -1,257 +0,0 @@
|
||||
/*
|
||||
* strtod.c --
|
||||
*
|
||||
* Source code for the "strtod" library procedure.
|
||||
*
|
||||
* Copyright (c) 1988-1993 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) strtod.c 1.9 96/12/13 15:02:46
|
||||
*/
|
||||
|
||||
#include "tcl.h"
|
||||
#ifdef NO_STDLIB_H
|
||||
# include "../compat/stdlib.h"
|
||||
#else
|
||||
# include <stdlib.h>
|
||||
#endif
|
||||
#include <ctype.h>
|
||||
|
||||
#ifndef TRUE
|
||||
#define TRUE 1
|
||||
#define FALSE 0
|
||||
#endif
|
||||
#ifndef NULL
|
||||
#define NULL 0
|
||||
#endif
|
||||
|
||||
static int maxExponent = 511; /* Largest possible base 10 exponent. Any
|
||||
* exponent larger than this will already
|
||||
* produce underflow or overflow, so there's
|
||||
* no need to worry about additional digits.
|
||||
*/
|
||||
static double powersOf10[] = { /* Table giving binary powers of 10. Entry */
|
||||
10., /* is 10^2^i. Used to convert decimal */
|
||||
100., /* exponents into floating-point numbers. */
|
||||
1.0e4,
|
||||
1.0e8,
|
||||
1.0e16,
|
||||
1.0e32,
|
||||
1.0e64,
|
||||
1.0e128,
|
||||
1.0e256
|
||||
};
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strtod --
|
||||
*
|
||||
* This procedure converts a floating-point number from an ASCII
|
||||
* decimal representation to internal double-precision format.
|
||||
*
|
||||
* Results:
|
||||
* The return value is the double-precision floating-point
|
||||
* representation of the characters in string. If endPtr isn't
|
||||
* NULL, then *endPtr is filled in with the address of the
|
||||
* next character after the last one that was part of the
|
||||
* floating-point number.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
double
|
||||
strtod(string, endPtr)
|
||||
CONST char *string; /* A decimal ASCII floating-point number,
|
||||
* optionally preceded by white space.
|
||||
* Must have form "-I.FE-X", where I is the
|
||||
* integer part of the mantissa, F is the
|
||||
* fractional part of the mantissa, and X
|
||||
* is the exponent. Either of the signs
|
||||
* may be "+", "-", or omitted. Either I
|
||||
* or F may be omitted, or both. The decimal
|
||||
* point isn't necessary unless F is present.
|
||||
* The "E" may actually be an "e". E and X
|
||||
* may both be omitted (but not just one).
|
||||
*/
|
||||
char **endPtr; /* If non-NULL, store terminating character's
|
||||
* address here. */
|
||||
{
|
||||
int sign, expSign = FALSE;
|
||||
double fraction, dblExp, *d;
|
||||
register CONST char *p;
|
||||
register int c;
|
||||
int exp = 0; /* Exponent read from "EX" field. */
|
||||
int fracExp = 0; /* Exponent that derives from the fractional
|
||||
* part. Under normal circumstatnces, it is
|
||||
* the negative of the number of digits in F.
|
||||
* However, if I is very long, the last digits
|
||||
* of I get dropped (otherwise a long I with a
|
||||
* large negative exponent could cause an
|
||||
* unnecessary overflow on I alone). In this
|
||||
* case, fracExp is incremented one for each
|
||||
* dropped digit. */
|
||||
int mantSize; /* Number of digits in mantissa. */
|
||||
int decPt; /* Number of mantissa digits BEFORE decimal
|
||||
* point. */
|
||||
CONST char *pExp; /* Temporarily holds location of exponent
|
||||
* in string. */
|
||||
|
||||
/*
|
||||
* Strip off leading blanks and check for a sign.
|
||||
*/
|
||||
|
||||
p = string;
|
||||
while (isspace(*p)) {
|
||||
p += 1;
|
||||
}
|
||||
if (*p == '-') {
|
||||
sign = TRUE;
|
||||
p += 1;
|
||||
} else {
|
||||
if (*p == '+') {
|
||||
p += 1;
|
||||
}
|
||||
sign = FALSE;
|
||||
}
|
||||
|
||||
/*
|
||||
* Count the number of digits in the mantissa (including the decimal
|
||||
* point), and also locate the decimal point.
|
||||
*/
|
||||
|
||||
decPt = -1;
|
||||
for (mantSize = 0; ; mantSize += 1)
|
||||
{
|
||||
c = *p;
|
||||
if (!isdigit(c)) {
|
||||
if ((c != '.') || (decPt >= 0)) {
|
||||
break;
|
||||
}
|
||||
decPt = mantSize;
|
||||
}
|
||||
p += 1;
|
||||
}
|
||||
|
||||
/*
|
||||
* Now suck up the digits in the mantissa. Use two integers to
|
||||
* collect 9 digits each (this is faster than using floating-point).
|
||||
* If the mantissa has more than 18 digits, ignore the extras, since
|
||||
* they can't affect the value anyway.
|
||||
*/
|
||||
|
||||
pExp = p;
|
||||
p -= mantSize;
|
||||
if (decPt < 0) {
|
||||
decPt = mantSize;
|
||||
} else {
|
||||
mantSize -= 1; /* One of the digits was the point. */
|
||||
}
|
||||
if (mantSize > 18) {
|
||||
fracExp = decPt - 18;
|
||||
mantSize = 18;
|
||||
} else {
|
||||
fracExp = decPt - mantSize;
|
||||
}
|
||||
if (mantSize == 0) {
|
||||
fraction = 0.0;
|
||||
p = string;
|
||||
goto done;
|
||||
} else {
|
||||
int frac1, frac2;
|
||||
frac1 = 0;
|
||||
for ( ; mantSize > 9; mantSize -= 1)
|
||||
{
|
||||
c = *p;
|
||||
p += 1;
|
||||
if (c == '.') {
|
||||
c = *p;
|
||||
p += 1;
|
||||
}
|
||||
frac1 = 10*frac1 + (c - '0');
|
||||
}
|
||||
frac2 = 0;
|
||||
for (; mantSize > 0; mantSize -= 1)
|
||||
{
|
||||
c = *p;
|
||||
p += 1;
|
||||
if (c == '.') {
|
||||
c = *p;
|
||||
p += 1;
|
||||
}
|
||||
frac2 = 10*frac2 + (c - '0');
|
||||
}
|
||||
fraction = (1.0e9 * frac1) + frac2;
|
||||
}
|
||||
|
||||
/*
|
||||
* Skim off the exponent.
|
||||
*/
|
||||
|
||||
p = pExp;
|
||||
if ((*p == 'E') || (*p == 'e')) {
|
||||
p += 1;
|
||||
if (*p == '-') {
|
||||
expSign = TRUE;
|
||||
p += 1;
|
||||
} else {
|
||||
if (*p == '+') {
|
||||
p += 1;
|
||||
}
|
||||
expSign = FALSE;
|
||||
}
|
||||
while (isdigit(*p)) {
|
||||
exp = exp * 10 + (*p - '0');
|
||||
p += 1;
|
||||
}
|
||||
}
|
||||
if (expSign) {
|
||||
exp = fracExp - exp;
|
||||
} else {
|
||||
exp = fracExp + exp;
|
||||
}
|
||||
|
||||
/*
|
||||
* Generate a floating-point number that represents the exponent.
|
||||
* Do this by processing the exponent one bit at a time to combine
|
||||
* many powers of 2 of 10. Then combine the exponent with the
|
||||
* fraction.
|
||||
*/
|
||||
|
||||
if (exp < 0) {
|
||||
expSign = TRUE;
|
||||
exp = -exp;
|
||||
} else {
|
||||
expSign = FALSE;
|
||||
}
|
||||
if (exp > maxExponent) {
|
||||
exp = maxExponent;
|
||||
}
|
||||
dblExp = 1.0;
|
||||
for (d = powersOf10; exp != 0; exp >>= 1, d += 1) {
|
||||
if (exp & 01) {
|
||||
dblExp *= *d;
|
||||
}
|
||||
}
|
||||
if (expSign) {
|
||||
fraction /= dblExp;
|
||||
} else {
|
||||
fraction *= dblExp;
|
||||
}
|
||||
|
||||
done:
|
||||
if (endPtr != NULL) {
|
||||
*endPtr = (char *) p;
|
||||
}
|
||||
|
||||
if (sign) {
|
||||
return -fraction;
|
||||
}
|
||||
return fraction;
|
||||
}
|
||||
@@ -1,83 +0,0 @@
|
||||
/*
|
||||
* strtol.c --
|
||||
*
|
||||
* Source code for the "strtol" library procedure.
|
||||
*
|
||||
* Copyright (c) 1988 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) strtol.c 1.4 96/02/15 12:08:23
|
||||
*/
|
||||
|
||||
#include <ctype.h>
|
||||
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strtol --
|
||||
*
|
||||
* Convert an ASCII string into an integer.
|
||||
*
|
||||
* Results:
|
||||
* The return value is the integer equivalent of string. If endPtr
|
||||
* is non-NULL, then *endPtr is filled in with the character
|
||||
* after the last one that was part of the integer. If string
|
||||
* doesn't contain a valid integer value, then zero is returned
|
||||
* and *endPtr is set to string.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
long int
|
||||
strtol(string, endPtr, base)
|
||||
char *string; /* String of ASCII digits, possibly
|
||||
* preceded by white space. For bases
|
||||
* greater than 10, either lower- or
|
||||
* upper-case digits may be used.
|
||||
*/
|
||||
char **endPtr; /* Where to store address of terminating
|
||||
* character, or NULL. */
|
||||
int base; /* Base for conversion. Must be less
|
||||
* than 37. If 0, then the base is chosen
|
||||
* from the leading characters of string:
|
||||
* "0x" means hex, "0" means octal, anything
|
||||
* else means decimal.
|
||||
*/
|
||||
{
|
||||
register char *p;
|
||||
int result;
|
||||
|
||||
/*
|
||||
* Skip any leading blanks.
|
||||
*/
|
||||
|
||||
p = string;
|
||||
while (isspace(*p)) {
|
||||
p += 1;
|
||||
}
|
||||
|
||||
/*
|
||||
* Check for a sign.
|
||||
*/
|
||||
|
||||
if (*p == '-') {
|
||||
p += 1;
|
||||
result = -(strtoul(p, endPtr, base));
|
||||
} else {
|
||||
if (*p == '+') {
|
||||
p += 1;
|
||||
}
|
||||
result = strtoul(p, endPtr, base);
|
||||
}
|
||||
if ((result == 0) && (endPtr != 0) && (*endPtr == p)) {
|
||||
*endPtr = string;
|
||||
}
|
||||
return result;
|
||||
}
|
||||
@@ -1,183 +0,0 @@
|
||||
/*
|
||||
* strtoul.c --
|
||||
*
|
||||
* Source code for the "strtoul" library procedure.
|
||||
*
|
||||
* Copyright (c) 1988 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) strtoul.c 1.5 96/02/15 12:08:24
|
||||
*/
|
||||
|
||||
#include <ctype.h>
|
||||
|
||||
/*
|
||||
* The table below is used to convert from ASCII digits to a
|
||||
* numerical equivalent. It maps from '0' through 'z' to integers
|
||||
* (100 for non-digit characters).
|
||||
*/
|
||||
|
||||
static char cvtIn[] = {
|
||||
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, /* '0' - '9' */
|
||||
100, 100, 100, 100, 100, 100, 100, /* punctuation */
|
||||
10, 11, 12, 13, 14, 15, 16, 17, 18, 19, /* 'A' - 'Z' */
|
||||
20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
|
||||
30, 31, 32, 33, 34, 35,
|
||||
100, 100, 100, 100, 100, 100, /* punctuation */
|
||||
10, 11, 12, 13, 14, 15, 16, 17, 18, 19, /* 'a' - 'z' */
|
||||
20, 21, 22, 23, 24, 25, 26, 27, 28, 29,
|
||||
30, 31, 32, 33, 34, 35};
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* strtoul --
|
||||
*
|
||||
* Convert an ASCII string into an integer.
|
||||
*
|
||||
* Results:
|
||||
* The return value is the integer equivalent of string. If endPtr
|
||||
* is non-NULL, then *endPtr is filled in with the character
|
||||
* after the last one that was part of the integer. If string
|
||||
* doesn't contain a valid integer value, then zero is returned
|
||||
* and *endPtr is set to string.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
unsigned long int
|
||||
strtoul(string, endPtr, base)
|
||||
char *string; /* String of ASCII digits, possibly
|
||||
* preceded by white space. For bases
|
||||
* greater than 10, either lower- or
|
||||
* upper-case digits may be used.
|
||||
*/
|
||||
char **endPtr; /* Where to store address of terminating
|
||||
* character, or NULL. */
|
||||
int base; /* Base for conversion. Must be less
|
||||
* than 37. If 0, then the base is chosen
|
||||
* from the leading characters of string:
|
||||
* "0x" means hex, "0" means octal, anything
|
||||
* else means decimal.
|
||||
*/
|
||||
{
|
||||
register char *p;
|
||||
register unsigned long int result = 0;
|
||||
register unsigned digit;
|
||||
int anyDigits = 0;
|
||||
|
||||
/*
|
||||
* Skip any leading blanks.
|
||||
*/
|
||||
|
||||
p = string;
|
||||
while (isspace(*p)) {
|
||||
p += 1;
|
||||
}
|
||||
|
||||
/*
|
||||
* If no base was provided, pick one from the leading characters
|
||||
* of the string.
|
||||
*/
|
||||
|
||||
if (base == 0)
|
||||
{
|
||||
if (*p == '0') {
|
||||
p += 1;
|
||||
if (*p == 'x') {
|
||||
p += 1;
|
||||
base = 16;
|
||||
} else {
|
||||
|
||||
/*
|
||||
* Must set anyDigits here, otherwise "0" produces a
|
||||
* "no digits" error.
|
||||
*/
|
||||
|
||||
anyDigits = 1;
|
||||
base = 8;
|
||||
}
|
||||
}
|
||||
else base = 10;
|
||||
} else if (base == 16) {
|
||||
|
||||
/*
|
||||
* Skip a leading "0x" from hex numbers.
|
||||
*/
|
||||
|
||||
if ((p[0] == '0') && (p[1] == 'x')) {
|
||||
p += 2;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* Sorry this code is so messy, but speed seems important. Do
|
||||
* different things for base 8, 10, 16, and other.
|
||||
*/
|
||||
|
||||
if (base == 8) {
|
||||
for ( ; ; p += 1) {
|
||||
digit = *p - '0';
|
||||
if (digit > 7) {
|
||||
break;
|
||||
}
|
||||
result = (result << 3) + digit;
|
||||
anyDigits = 1;
|
||||
}
|
||||
} else if (base == 10) {
|
||||
for ( ; ; p += 1) {
|
||||
digit = *p - '0';
|
||||
if (digit > 9) {
|
||||
break;
|
||||
}
|
||||
result = (10*result) + digit;
|
||||
anyDigits = 1;
|
||||
}
|
||||
} else if (base == 16) {
|
||||
for ( ; ; p += 1) {
|
||||
digit = *p - '0';
|
||||
if (digit > ('z' - '0')) {
|
||||
break;
|
||||
}
|
||||
digit = cvtIn[digit];
|
||||
if (digit > 15) {
|
||||
break;
|
||||
}
|
||||
result = (result << 4) + digit;
|
||||
anyDigits = 1;
|
||||
}
|
||||
} else {
|
||||
for ( ; ; p += 1) {
|
||||
digit = *p - '0';
|
||||
if (digit > ('z' - '0')) {
|
||||
break;
|
||||
}
|
||||
digit = cvtIn[digit];
|
||||
if (digit >= base) {
|
||||
break;
|
||||
}
|
||||
result = result*base + digit;
|
||||
anyDigits = 1;
|
||||
}
|
||||
}
|
||||
|
||||
/*
|
||||
* See if there were any digits at all.
|
||||
*/
|
||||
|
||||
if (!anyDigits) {
|
||||
p = string;
|
||||
}
|
||||
|
||||
if (endPtr != 0) {
|
||||
*endPtr = p;
|
||||
}
|
||||
|
||||
return result;
|
||||
}
|
||||
@@ -1,100 +0,0 @@
|
||||
/*
|
||||
* tclErrno.h --
|
||||
*
|
||||
* This header file contains the various POSIX errno definitions that
|
||||
* are used by Tcl. This file is derived from the spec POSIX 2.4 and
|
||||
* previous implementations for Berkeley UNIX.
|
||||
*
|
||||
* Copyright (c) 1982, 1986, 1989 Regents of the University of California.
|
||||
* Copyright (c) 1996 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) tclErrno.h 1.1 96/04/29 15:25:31
|
||||
*/
|
||||
|
||||
extern int errno; /* global error number */
|
||||
|
||||
#define EPERM 1 /* Operation not permitted */
|
||||
#define ENOENT 2 /* No such file or directory */
|
||||
#define ESRCH 3 /* No such process */
|
||||
#define EINTR 4 /* Interrupted system call */
|
||||
#define EIO 5 /* Input/output error */
|
||||
#define ENXIO 6 /* Device not configured */
|
||||
#define E2BIG 7 /* Argument list too long */
|
||||
#define ENOEXEC 8 /* Exec format error */
|
||||
#define EBADF 9 /* Bad file descriptor */
|
||||
#define ECHILD 10 /* No child processes */
|
||||
#define EDEADLK 11 /* Resource deadlock avoided */
|
||||
/* 11 was EAGAIN */
|
||||
#define ENOMEM 12 /* Cannot allocate memory */
|
||||
#define EACCES 13 /* Permission denied */
|
||||
#define EFAULT 14 /* Bad address */
|
||||
#define ENOTBLK 15 /* Block device required */
|
||||
#define EBUSY 16 /* Device busy */
|
||||
#define EEXIST 17 /* File exists */
|
||||
#define EXDEV 18 /* Cross-device link */
|
||||
#define ENODEV 19 /* Operation not supported by device */
|
||||
#define ENOTDIR 20 /* Not a directory */
|
||||
#define EISDIR 21 /* Is a directory */
|
||||
#define EINVAL 22 /* Invalid argument */
|
||||
#define ENFILE 23 /* Too many open files in system */
|
||||
#define EMFILE 24 /* Too many open files */
|
||||
#define ENOTTY 25 /* Inappropriate ioctl for device */
|
||||
#define ETXTBSY 26 /* Text file busy */
|
||||
#define EFBIG 27 /* File too large */
|
||||
#define ENOSPC 28 /* No space left on device */
|
||||
#define ESPIPE 29 /* Illegal seek */
|
||||
#define EROFS 30 /* Read-only file system */
|
||||
#define EMLINK 31 /* Too many links */
|
||||
#define EPIPE 32 /* Broken pipe */
|
||||
#define EDOM 33 /* Numerical argument out of domain */
|
||||
#define ERANGE 34 /* Result too large */
|
||||
#define EAGAIN 35 /* Resource temporarily unavailable */
|
||||
#define EWOULDBLOCK EAGAIN /* Operation would block */
|
||||
#define EINPROGRESS 36 /* Operation now in progress */
|
||||
#define EALREADY 37 /* Operation already in progress */
|
||||
#define ENOTSOCK 38 /* Socket operation on non-socket */
|
||||
#define EDESTADDRREQ 39 /* Destination address required */
|
||||
#define EMSGSIZE 40 /* Message too long */
|
||||
#define EPROTOTYPE 41 /* Protocol wrong type for socket */
|
||||
#define ENOPROTOOPT 42 /* Protocol not available */
|
||||
#define EPROTONOSUPPORT 43 /* Protocol not supported */
|
||||
#define ESOCKTNOSUPPORT 44 /* Socket type not supported */
|
||||
#define EOPNOTSUPP 45 /* Operation not supported on socket */
|
||||
#define EPFNOSUPPORT 46 /* Protocol family not supported */
|
||||
#define EAFNOSUPPORT 47 /* Address family not supported by protocol family */
|
||||
#define EADDRINUSE 48 /* Address already in use */
|
||||
#define EADDRNOTAVAIL 49 /* Can't assign requested address */
|
||||
#define ENETDOWN 50 /* Network is down */
|
||||
#define ENETUNREACH 51 /* Network is unreachable */
|
||||
#define ENETRESET 52 /* Network dropped connection on reset */
|
||||
#define ECONNABORTED 53 /* Software caused connection abort */
|
||||
#define ECONNRESET 54 /* Connection reset by peer */
|
||||
#define ENOBUFS 55 /* No buffer space available */
|
||||
#define EISCONN 56 /* Socket is already connected */
|
||||
#define ENOTCONN 57 /* Socket is not connected */
|
||||
#define ESHUTDOWN 58 /* Can't send after socket shutdown */
|
||||
#define ETOOMANYREFS 59 /* Too many references: can't splice */
|
||||
#define ETIMEDOUT 60 /* Connection timed out */
|
||||
#define ECONNREFUSED 61 /* Connection refused */
|
||||
#define ELOOP 62 /* Too many levels of symbolic links */
|
||||
#define ENAMETOOLONG 63 /* File name too long */
|
||||
#define EHOSTDOWN 64 /* Host is down */
|
||||
#define EHOSTUNREACH 65 /* No route to host */
|
||||
#define ENOTEMPTY 66 /* Directory not empty */
|
||||
#define EPROCLIM 67 /* Too many processes */
|
||||
#define EUSERS 68 /* Too many users */
|
||||
#define EDQUOT 69 /* Disc quota exceeded */
|
||||
#define ESTALE 70 /* Stale NFS file handle */
|
||||
#define EREMOTE 71 /* Too many levels of remote in path */
|
||||
#define EBADRPC 72 /* RPC struct is bad */
|
||||
#define ERPCMISMATCH 73 /* RPC version wrong */
|
||||
#define EPROGUNAVAIL 74 /* RPC prog. not avail */
|
||||
#define EPROGMISMATCH 75 /* Program version wrong */
|
||||
#define EPROCUNAVAIL 76 /* Bad procedure for program */
|
||||
#define ENOLCK 77 /* No locks available */
|
||||
#define ENOSYS 78 /* Function not implemented */
|
||||
#define EFTYPE 79 /* Inappropriate file type or format */
|
||||
|
||||
@@ -1,42 +0,0 @@
|
||||
/*
|
||||
* Copyright (c) 1988 Regents of the University of California.
|
||||
* All rights reserved.
|
||||
*
|
||||
* Redistribution and use in source and binary forms are permitted
|
||||
* provided that this notice is preserved and that due credit is given
|
||||
* to the University of California at Berkeley. The name of the University
|
||||
* may not be used to endorse or promote products derived from this
|
||||
* software without specific written prior permission. This software
|
||||
* is provided ``as is'' without express or implied warranty.
|
||||
*
|
||||
* SCCS: @(#) tmpnam.c 1.3 96/02/15 12:08:25
|
||||
*/
|
||||
|
||||
#include <sys/param.h>
|
||||
#include <sys/stat.h>
|
||||
#include <sys/file.h>
|
||||
#include <stdio.h>
|
||||
|
||||
/*
|
||||
* Use /tmp instead of /usr/tmp, because L_tmpname is only 14 chars
|
||||
* on some machines (like NeXT machines) and /usr/tmp will cause
|
||||
* buffer overflows.
|
||||
*/
|
||||
|
||||
#ifdef P_tmpdir
|
||||
# undef P_tmpdir
|
||||
#endif
|
||||
#define P_tmpdir "/tmp"
|
||||
|
||||
char *
|
||||
tmpnam(s)
|
||||
char *s;
|
||||
{
|
||||
static char name[50];
|
||||
char *mktemp();
|
||||
|
||||
if (!s)
|
||||
s = name;
|
||||
(void)sprintf(s, "%s/XXXXXX", P_tmpdir);
|
||||
return(mktemp(s));
|
||||
}
|
||||
@@ -1,84 +0,0 @@
|
||||
/*
|
||||
* unistd.h --
|
||||
*
|
||||
* Macros, CONSTants and prototypes for Posix conformance.
|
||||
*
|
||||
* Copyright 1989 Regents of the University of California
|
||||
* Permission to use, copy, modify, and distribute this
|
||||
* software and its documentation for any purpose and without
|
||||
* fee is hereby granted, provided that the above copyright
|
||||
* notice appear in all copies. The University of California
|
||||
* makes no representations about the suitability of this
|
||||
* software for any purpose. It is provided "as is" without
|
||||
* express or implied warranty.
|
||||
*
|
||||
* SCCS: @(#) unistd.h 1.7 96/02/15 14:43:57
|
||||
*/
|
||||
|
||||
#ifndef _UNISTD
|
||||
#define _UNISTD
|
||||
|
||||
#include <sys/types.h>
|
||||
#ifndef _TCL
|
||||
# include "tcl.h"
|
||||
#endif
|
||||
|
||||
#ifndef NULL
|
||||
#define NULL 0
|
||||
#endif
|
||||
|
||||
/*
|
||||
* Strict POSIX stuff goes here. Extensions go down below, in the
|
||||
* ifndef _POSIX_SOURCE section.
|
||||
*/
|
||||
|
||||
extern void _exit _ANSI_ARGS_((int status));
|
||||
extern int access _ANSI_ARGS_((CONST char *path, int mode));
|
||||
extern int chdir _ANSI_ARGS_((CONST char *path));
|
||||
extern int chown _ANSI_ARGS_((CONST char *path, uid_t owner, gid_t group));
|
||||
extern int close _ANSI_ARGS_((int fd));
|
||||
extern int dup _ANSI_ARGS_((int oldfd));
|
||||
extern int dup2 _ANSI_ARGS_((int oldfd, int newfd));
|
||||
extern int execl _ANSI_ARGS_((CONST char *path, ...));
|
||||
extern int execle _ANSI_ARGS_((CONST char *path, ...));
|
||||
extern int execlp _ANSI_ARGS_((CONST char *file, ...));
|
||||
extern int execv _ANSI_ARGS_((CONST char *path, char **argv));
|
||||
extern int execve _ANSI_ARGS_((CONST char *path, char **argv, char **envp));
|
||||
extern int execvp _ANSI_ARGS_((CONST char *file, char **argv));
|
||||
extern pid_t fork _ANSI_ARGS_((void));
|
||||
extern char *getcwd _ANSI_ARGS_((char *buf, size_t size));
|
||||
extern gid_t getegid _ANSI_ARGS_((void));
|
||||
extern uid_t geteuid _ANSI_ARGS_((void));
|
||||
extern gid_t getgid _ANSI_ARGS_((void));
|
||||
extern int getgroups _ANSI_ARGS_((int bufSize, int *buffer));
|
||||
extern pid_t getpid _ANSI_ARGS_((void));
|
||||
extern uid_t getuid _ANSI_ARGS_((void));
|
||||
extern int isatty _ANSI_ARGS_((int fd));
|
||||
extern long lseek _ANSI_ARGS_((int fd, long offset, int whence));
|
||||
extern int pipe _ANSI_ARGS_((int *fildes));
|
||||
extern int read _ANSI_ARGS_((int fd, char *buf, size_t size));
|
||||
extern int setgid _ANSI_ARGS_((gid_t group));
|
||||
extern int setuid _ANSI_ARGS_((uid_t user));
|
||||
extern unsigned sleep _ANSI_ARGS_ ((unsigned seconds));
|
||||
extern char *ttyname _ANSI_ARGS_((int fd));
|
||||
extern int unlink _ANSI_ARGS_((CONST char *path));
|
||||
extern int write _ANSI_ARGS_((int fd, CONST char *buf, size_t size));
|
||||
|
||||
#ifndef _POSIX_SOURCE
|
||||
extern char *crypt _ANSI_ARGS_((CONST char *, CONST char *));
|
||||
extern int fchown _ANSI_ARGS_((int fd, uid_t owner, gid_t group));
|
||||
extern int flock _ANSI_ARGS_((int fd, int operation));
|
||||
extern int ftruncate _ANSI_ARGS_((int fd, unsigned long length));
|
||||
extern int ioctl _ANSI_ARGS_((int fd, int request, ...));
|
||||
extern int readlink _ANSI_ARGS_((CONST char *path, char *buf, int bufsize));
|
||||
extern int setegid _ANSI_ARGS_((gid_t group));
|
||||
extern int seteuid _ANSI_ARGS_((uid_t user));
|
||||
extern int setreuid _ANSI_ARGS_((int ruid, int euid));
|
||||
extern int symlink _ANSI_ARGS_((CONST char *, CONST char *));
|
||||
extern int ttyslot _ANSI_ARGS_((void));
|
||||
extern int truncate _ANSI_ARGS_((CONST char *path, unsigned long length));
|
||||
extern int vfork _ANSI_ARGS_((void));
|
||||
#endif /* _POSIX_SOURCE */
|
||||
|
||||
#endif /* _UNISTD */
|
||||
|
||||
@@ -1,170 +0,0 @@
|
||||
/*
|
||||
* waitpid.c --
|
||||
*
|
||||
* This procedure emulates the POSIX waitpid kernel call on
|
||||
* BSD systems that don't have waitpid but do have wait3.
|
||||
* This code is based on a prototype version written by
|
||||
* Mark Diekhans and Karl Lehenbauer.
|
||||
*
|
||||
* Copyright (c) 1993 The Regents of the University of California.
|
||||
* Copyright (c) 1994 Sun Microsystems, Inc.
|
||||
*
|
||||
* See the file "license.terms" for information on usage and redistribution
|
||||
* of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
*
|
||||
* SCCS: @(#) waitpid.c 1.9 96/02/15 12:08:26
|
||||
*/
|
||||
|
||||
#include "tclInt.h"
|
||||
#include "tclPort.h"
|
||||
|
||||
/*
|
||||
* A linked list of the following structures is used to keep track
|
||||
* of processes for which we received notification from the kernel,
|
||||
* but the application hasn't waited for them yet (this can happen
|
||||
* because wait may not return the process we really want). We
|
||||
* save the information here until the application finally does
|
||||
* wait for the process.
|
||||
*/
|
||||
|
||||
typedef struct WaitInfo {
|
||||
int pid; /* Pid of process that exited. */
|
||||
WAIT_STATUS_TYPE status; /* Status returned when child exited
|
||||
* or suspended. */
|
||||
struct WaitInfo *nextPtr; /* Next in list of exited processes. */
|
||||
} WaitInfo;
|
||||
|
||||
static WaitInfo *deadList = NULL; /* First in list of all dead
|
||||
* processes. */
|
||||
|
||||
/*
|
||||
*----------------------------------------------------------------------
|
||||
*
|
||||
* waitpid --
|
||||
*
|
||||
* This procedure emulates the functionality of the POSIX
|
||||
* waitpid kernel call, using the BSD wait3 kernel call.
|
||||
* Note: it doesn't emulate absolutely all of the waitpid
|
||||
* functionality, in that it doesn't support pid's of 0
|
||||
* or < -1.
|
||||
*
|
||||
* Results:
|
||||
* -1 is returned if there is an error in the wait kernel call.
|
||||
* Otherwise the pid of an exited or suspended process is
|
||||
* returned and *statusPtr is set to the status value of the
|
||||
* process.
|
||||
*
|
||||
* Side effects:
|
||||
* None.
|
||||
*
|
||||
*----------------------------------------------------------------------
|
||||
*/
|
||||
|
||||
#ifdef waitpid
|
||||
# undef waitpid
|
||||
#endif
|
||||
|
||||
int
|
||||
waitpid(pid, statusPtr, options)
|
||||
int pid; /* The pid to wait on. Must be -1 or
|
||||
* greater than zero. */
|
||||
int *statusPtr; /* Where to store wait status for the
|
||||
* process. */
|
||||
int options; /* OR'ed combination of WNOHANG and
|
||||
* WUNTRACED. */
|
||||
{
|
||||
register WaitInfo *waitPtr, *prevPtr;
|
||||
int result;
|
||||
WAIT_STATUS_TYPE status;
|
||||
|
||||
if ((pid < -1) || (pid == 0)) {
|
||||
errno = EINVAL;
|
||||
return -1;
|
||||
}
|
||||
|
||||
/*
|
||||
* See if there's a suitable process that has already stopped or
|
||||
* exited. If so, remove it from the list of exited processes and
|
||||
* return its information.
|
||||
*/
|
||||
|
||||
for (waitPtr = deadList, prevPtr = NULL; waitPtr != NULL;
|
||||
prevPtr = waitPtr, waitPtr = waitPtr->nextPtr) {
|
||||
if ((pid != waitPtr->pid) && (pid != -1)) {
|
||||
continue;
|
||||
}
|
||||
if (!(options & WUNTRACED) && (WIFSTOPPED(waitPtr->status))) {
|
||||
continue;
|
||||
}
|
||||
result = waitPtr->pid;
|
||||
*statusPtr = *((int *) &waitPtr->status);
|
||||
if (prevPtr == NULL) {
|
||||
deadList = waitPtr->nextPtr;
|
||||
} else {
|
||||
prevPtr->nextPtr = waitPtr->nextPtr;
|
||||
}
|
||||
ckfree((char *) waitPtr);
|
||||
return result;
|
||||
}
|
||||
|
||||
/*
|
||||
* Wait for any process to stop or exit. If it's an acceptable one
|
||||
* then return it to the caller; otherwise store information about it
|
||||
* in the list of exited processes and try again. On systems that
|
||||
* have only wait but not wait3, there are several situations we can't
|
||||
* handle, but we do the best we can (e.g. can still handle some
|
||||
* combinations of options by invoking wait instead of wait3).
|
||||
*/
|
||||
|
||||
while (1) {
|
||||
#if NO_WAIT3
|
||||
if (options & WNOHANG) {
|
||||
return 0;
|
||||
}
|
||||
if (options != 0) {
|
||||
errno = EINVAL;
|
||||
return -1;
|
||||
}
|
||||
result = wait(&status);
|
||||
#else
|
||||
result = wait3(&status, options, 0);
|
||||
#endif
|
||||
if ((result == -1) && (errno == EINTR)) {
|
||||
continue;
|
||||
}
|
||||
if (result <= 0) {
|
||||
return result;
|
||||
}
|
||||
|
||||
if ((pid != result) && (pid != -1)) {
|
||||
goto saveInfo;
|
||||
}
|
||||
if (!(options & WUNTRACED) && (WIFSTOPPED(status))) {
|
||||
goto saveInfo;
|
||||
}
|
||||
*statusPtr = *((int *) &status);
|
||||
return result;
|
||||
|
||||
/*
|
||||
* Can't return this info to caller. Save it in the list of
|
||||
* stopped or exited processes. Tricky point: first check for
|
||||
* an existing entry for the process and overwrite it if it
|
||||
* exists (e.g. a previously stopped process might now be dead).
|
||||
*/
|
||||
|
||||
saveInfo:
|
||||
for (waitPtr = deadList; waitPtr != NULL; waitPtr = waitPtr->nextPtr) {
|
||||
if (waitPtr->pid == result) {
|
||||
waitPtr->status = status;
|
||||
goto waitAgain;
|
||||
}
|
||||
}
|
||||
waitPtr = (WaitInfo *) ckalloc(sizeof(WaitInfo));
|
||||
waitPtr->pid = result;
|
||||
waitPtr->status = status;
|
||||
waitPtr->nextPtr = deadList;
|
||||
deadList = waitPtr;
|
||||
|
||||
waitAgain: continue;
|
||||
}
|
||||
}
|
||||
@@ -1,166 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) AddErrInfo.3 1.28 97/06/12 13:39:53
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_AddErrorInfo 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetErrorCode, Tcl_PosixError \- record information about errors
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_AddObjErrorInfo\fR(\fIinterp, message, length\fR)
|
||||
.sp
|
||||
\fBTcl_AddErrorInfo\fR(\fIinterp, message\fR)
|
||||
.sp
|
||||
\fBTcl_SetObjErrorCode\fR(\fIinterp, errorObjPtr\fR)
|
||||
.sp
|
||||
\fBTcl_SetErrorCode\fR(\fIinterp, element, element, ... \fB(char *) NULL\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_PosixError\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *message
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to record information.
|
||||
.AP char *message in
|
||||
For \fBTcl_AddObjErrorInfo\fR,
|
||||
this points to the first byte of an array of bytes
|
||||
containing a string to record in the \fBerrorInfo\fR variable.
|
||||
This byte array may contain embedded null bytes
|
||||
unless \fIlength\fR is negative.
|
||||
For \fBTcl_AddErrorInfo\fR,
|
||||
this is a conventional C string to record in the \fBerrorInfo\fR variable.
|
||||
.AP int length in
|
||||
The number of bytes to copy from \fImessage\fR when
|
||||
setting the \fBerrorInfo\fR variable.
|
||||
If negative, all bytes up to the first null byte are used.
|
||||
.AP Tcl_Obj *errorObjPtr in
|
||||
This variable \fBerrorCode\fR will be set to this value.
|
||||
.AP char *element in
|
||||
String to record as one element of \fBerrorCode\fR variable.
|
||||
Last \fIelement\fR argument must be NULL.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures are used to manipulate two Tcl global variables
|
||||
that hold information about errors.
|
||||
The variable \fBerrorInfo\fR holds a stack trace of the
|
||||
operations that were in progress when an error occurred,
|
||||
and is intended to be human-readable.
|
||||
The variable \fBerrorCode\fR holds a list of items that
|
||||
are intended to be machine-readable.
|
||||
The first item in \fBerrorCode\fR identifies the class of
|
||||
error that occurred
|
||||
(e.g. POSIX means an error occurred in a POSIX system call)
|
||||
and additional elements in \fBerrorCode\fR hold additional pieces
|
||||
of information that depend on the class.
|
||||
See the Tcl overview manual entry for details on the various
|
||||
formats for \fBerrorCode\fR.
|
||||
.PP
|
||||
The \fBerrorInfo\fR variable is gradually built up as an
|
||||
error unwinds through the nested operations.
|
||||
Each time an error code is returned to \fBTcl_EvalObj\fR
|
||||
(or \fBTcl_Eval\fR, which calls \fBTcl_EvalObj\fR)
|
||||
it calls the procedure \fBTcl_AddObjErrorInfo\fR to add
|
||||
additional text to \fBerrorInfo\fR describing the
|
||||
command that was being executed when the error occurred.
|
||||
By the time the error has been passed all the way back
|
||||
to the application, it will contain a complete trace
|
||||
of the activity in progress when the error occurred.
|
||||
.PP
|
||||
It is sometimes useful to add additional information to
|
||||
\fBerrorInfo\fR beyond what can be supplied automatically
|
||||
by \fBTcl_EvalObj\fR.
|
||||
\fBTcl_AddObjErrorInfo\fR may be used for this purpose:
|
||||
its \fImessage\fR and \fIlength\fR arguments describe an additional
|
||||
string to be appended to \fBerrorInfo\fR.
|
||||
For example, the \fBsource\fR command calls \fBTcl_AddObjErrorInfo\fR
|
||||
to record the name of the file being processed and the
|
||||
line number on which the error occurred;
|
||||
for Tcl procedures, the procedure name and line number
|
||||
within the procedure are recorded, and so on.
|
||||
The best time to call \fBTcl_AddObjErrorInfo\fR is just after
|
||||
\fBTcl_EvalObj\fR has returned \fBTCL_ERROR\fR.
|
||||
In calling \fBTcl_AddObjErrorInfo\fR, you may find it useful to
|
||||
use the \fBerrorLine\fR field of the interpreter (see the
|
||||
\fBTcl_Interp\fR manual entry for details).
|
||||
.PP
|
||||
\fBTcl_AddErrorInfo\fR resembles \fBTcl_AddObjErrorInfo\fR
|
||||
but differs in initializing \fBerrorInfo\fR from the string
|
||||
value of the interpreter's result
|
||||
if the error is just starting to be logged.
|
||||
It does not use the result as a Tcl object
|
||||
so any embedded null characters in the result
|
||||
will cause information to be lost.
|
||||
It also takes a conventional C string in \fImessage\fR
|
||||
instead of \fBTcl_AddObjErrorInfo\fR's counted string.
|
||||
.PP
|
||||
The procedure \fBTcl_SetObjErrorCode\fR is used to set the
|
||||
\fBerrorCode\fR variable. \fIerrorObjPtr\fR contains a list object
|
||||
built up by the caller. \fBerrorCode\fR is set to this
|
||||
value. \fBTcl_SetObjErrorCode\fR is typically invoked just
|
||||
before returning an error in an object command. If an error is
|
||||
returned without calling \fBTcl_SetObjErrorCode\fR or
|
||||
\fBTcl_SetErrorCode\fR the Tcl interpreter automatically sets
|
||||
\fBerrorCode\fR to \fBNONE\fR.
|
||||
.PP
|
||||
The procedure \fBTcl_SetErrorCode\fR is also used to set the
|
||||
\fBerrorCode\fR variable. However, it takes one or more strings to
|
||||
record instead of an object. Otherwise, it is similar to
|
||||
\fBTcl_SetObjErrorCode\fR in behavior.
|
||||
.PP
|
||||
\fBTcl_PosixError\fR
|
||||
sets the \fBerrorCode\fR variable after an error in a POSIX kernel call.
|
||||
It reads the value of the \fBerrno\fR C variable and calls
|
||||
\fBTcl_SetErrorCode\fR to set \fBerrorCode\fR in the \fBPOSIX\fR format.
|
||||
The caller must previously have called \fBTcl_SetErrno\fR to set
|
||||
\fBerrno\fR; this is necessary on some platforms (e.g. Windows) where Tcl
|
||||
is linked into an application as a shared library, or when the error
|
||||
occurs in a dynamically loaded extension. See the manual entry for
|
||||
\fBTcl_SetErrno\fR for more information.
|
||||
.PP
|
||||
\fBTcl_PosixError\fR returns a human-readable diagnostic message
|
||||
for the error
|
||||
(this is the same value that will appear as the third element
|
||||
in \fBerrorCode\fR).
|
||||
It may be convenient to include this string as part of the
|
||||
error message returned to the application in
|
||||
the interpreter's result.
|
||||
.PP
|
||||
It is important to call the procedures described here rather than
|
||||
setting \fBerrorInfo\fR or \fBerrorCode\fR directly with
|
||||
\fBTcl_ObjSetVar2\fR.
|
||||
The reason for this is that the Tcl interpreter keeps information
|
||||
about whether these procedures have been called.
|
||||
For example, the first time \fBTcl_AddObjErrorInfo\fR is called
|
||||
for an error, it clears the existing value of \fBerrorInfo\fR
|
||||
and adds the error message in the interpreter's result to the variable
|
||||
before appending \fImessage\fR;
|
||||
in subsequent calls, it just appends the new \fImessage\fR.
|
||||
When \fBTcl_SetErrorCode\fR is called, it sets a flag indicating
|
||||
that \fBerrorCode\fR has been set;
|
||||
this allows the Tcl interpreter to set \fBerrorCode\fR to \fBNONE\fR
|
||||
if it receives an error return
|
||||
when \fBTcl_SetErrorCode\fR hasn't been called.
|
||||
.PP
|
||||
If the procedure \fBTcl_ResetResult\fR is called,
|
||||
it clears all of the state associated with
|
||||
\fBerrorInfo\fR and \fBerrorCode\fR
|
||||
(but it doesn't actually modify the variables).
|
||||
If an error had occurred, this will clear the error state to
|
||||
make it appear as if no error had occurred after all.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno
|
||||
|
||||
.SH KEYWORDS
|
||||
error, object, object result, stack, trace, variable
|
||||
@@ -1,52 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Alloc.3 1.2 96/06/05 18:00:19
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Alloc, Tcl_Free, Tcl_Realloc \- allocate or free heap memory
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_Alloc\fR(\fIsize\fR)
|
||||
.sp
|
||||
\fBTcl_Free\fR(\fIptr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_Realloc\fR(\fIptr, size\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS char *size
|
||||
.AP int size in
|
||||
Size in bytes of the memory block to allocate.
|
||||
.AP char *ptr in
|
||||
Pointer to memory block to free or realloc.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures provide a platform and compiler independent interface
|
||||
for memory allocation. Programs that need to transfer ownership of
|
||||
memory blocks between Tcl and other modules should use these routines
|
||||
rather than the native \fBmalloc()\fR and \fBfree()\fR routines
|
||||
provided by the C run-time library.
|
||||
.PP
|
||||
\fBTcl_Alloc\fR returns a pointer to a block of at least \fIsize\fR
|
||||
bytes suitably aligned for any use.
|
||||
.PP
|
||||
\fBTcl_Free\fR makes the space referred to by \fIptr\fR available for
|
||||
further allocation.
|
||||
.PP
|
||||
\fBTcl_Realloc\fR changes the size of the block pointed to by
|
||||
\fIptr\fR to \fIsize\fR bytes and returns a pointer to the new block.
|
||||
The contents will be unchanged up to the lesser of the new and old
|
||||
sizes. The returned location may be different from \fIptr\fR.
|
||||
.SH KEYWORDS
|
||||
alloc, allocation, free, malloc, memory, realloc
|
||||
@@ -1,42 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) AllowExc.3 1.5 96/03/25 19:55:47
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_AllowExceptions 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_AllowExceptions \- allow all exceptions in next script evaluation
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_AllowExceptions\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *doublePtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which script will be evaluated.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
If a script is evaluated at top-level (i.e. no other scripts are
|
||||
pending evaluation when the script is invoked), and if the script
|
||||
terminates with a completion code other than TCL_OK, TCL_CONTINUE
|
||||
or TCL_RETURN, then Tcl normally converts this into a TCL_ERROR
|
||||
return with an appropriate message.
|
||||
.PP
|
||||
However, if \fBTcl_AllowExceptions\fR is invoked immediately before
|
||||
calling a procedure such as \fBTcl_Eval\fR, then arbitrary completion
|
||||
codes are permitted from the script, and they are returned without
|
||||
modification.
|
||||
This is useful in cases where the caller can deal with exceptions
|
||||
such as TCL_BREAK or TCL_CONTINUE in a meaningful way.
|
||||
|
||||
.SH KEYWORDS
|
||||
continue, break, exception, interpreter
|
||||
@@ -1,73 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) AppInit.3 1.10 96/08/26 12:59:40
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_AppInit 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_AppInit \- perform application-specific initialization
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_AppInit\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter for the application.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_AppInit\fR is a ``hook'' procedure that is invoked by
|
||||
the main programs for Tcl applications such as \fBtclsh\fR and \fBwish\fR.
|
||||
Its purpose is to allow new Tcl applications to be created without
|
||||
modifying the main programs provided as part of Tcl and Tk.
|
||||
To create a new application you write a new version of
|
||||
\fBTcl_AppInit\fR to replace the default version provided by Tcl,
|
||||
then link your new \fBTcl_AppInit\fR with the Tcl library.
|
||||
.PP
|
||||
\fBTcl_AppInit\fR is invoked after by \fBTcl_Main\fR and \fBTk_Main\fR
|
||||
after their own initialization and before entering the main loop
|
||||
to process commands.
|
||||
Here are some examples of things that \fBTcl_AppInit\fR might do:
|
||||
.IP [1]
|
||||
Call initialization procedures for various packages used by
|
||||
the application.
|
||||
Each initialization procedure adds new commands to \fIinterp\fR
|
||||
for its package and performs other package-specific initialization.
|
||||
.IP [2]
|
||||
Process command-line arguments, which can be accessed from the
|
||||
Tcl variables \fBargv\fR and \fBargv0\fR in \fIinterp\fR.
|
||||
.IP [3]
|
||||
Invoke a startup script to initialize the application.
|
||||
.LP
|
||||
\fBTcl_AppInit\fR returns TCL_OK or TCL_ERROR.
|
||||
If it returns TCL_ERROR then it must leave an error message in
|
||||
\fIinterp->result\fR; otherwise the result is ignored.
|
||||
.PP
|
||||
In addition to \fBTcl_AppInit\fR, your application should also contain
|
||||
a procedure \fBmain\fR that calls \fBTcl_Main\fR as follows:
|
||||
.CS
|
||||
Tcl_Main(argc, argv, Tcl_AppInit);
|
||||
.CE
|
||||
The third argument to \fBTcl_Main\fR gives the address of the
|
||||
application-specific initialization procedure to invoke.
|
||||
This means that you don't have to use the name \fBTcl_AppInit\fR
|
||||
for the procedure, but in practice the name is nearly always
|
||||
\fBTcl_AppInit\fR (in versions before Tcl 7.4 the name \fBTcl_AppInit\fR
|
||||
was implicit; there was no way to specify the procedure explicitly).
|
||||
The best way to get started is to make a copy of the file
|
||||
\fBtclAppInit.c\fR from the Tcl library or source directory.
|
||||
It already contains a \fBmain\fR procedure and a template for
|
||||
\fBTcl_AppInit\fR that you can modify for your application.
|
||||
|
||||
.SH KEYWORDS
|
||||
application, argument, command, initialization, interpreter
|
||||
@@ -1,89 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\"
|
||||
'\" SCCS: @(#) AssocData.3 1.8 96/03/25 19:56:17
|
||||
.so man.macros
|
||||
.TH Tcl_SetAssocData 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_GetAssocData, Tcl_SetAssocData, Tcl_DeleteAssocData \- manage
|
||||
associations of string keys and user specified data with Tcl
|
||||
interpreters.
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
ClientData
|
||||
\fBTcl_GetAssocData\fR(\fIinterp, key, delProcPtr\fR)
|
||||
.sp
|
||||
\fBTcl_SetAssocData\fR(\fIinterp, key, delProc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteAssocData\fR(\fIinterp, key\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_InterpDeleteProc *delProcPtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to execute the specified command.
|
||||
.AP char *key in
|
||||
Key for association with which to store data or from which to delete or
|
||||
retrieve data. Typically the module prefix for a package.
|
||||
.AP Tcl_InterpDeleteProc *delProc in
|
||||
Procedure to call when \fIinterp\fR is deleted.
|
||||
.AP Tcl_InterpDeleteProc **delProcPtr in
|
||||
Pointer to location in which to store address of current deletion procedure
|
||||
for association. Ignored if NULL.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value associated with the given key in this
|
||||
interpreter. This data is owned by the caller.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures allow extensions to associate their own data with
|
||||
a Tcl interpreter.
|
||||
An association consists of a string key, typically the name of
|
||||
the extension, and a one-word value, which is typically a pointer
|
||||
to a data structure holding data specific to the extension.
|
||||
Tcl makes no interpretation of either the key or the value for
|
||||
an association.
|
||||
.PP
|
||||
Storage management is facilitated by storing with each association a
|
||||
procedure to call when the interpreter is deleted. This
|
||||
procedure can dispose of the storage occupied by the client's data in any
|
||||
way it sees fit.
|
||||
.PP
|
||||
\fBTcl_SetAssocData\fR creates an association between a string
|
||||
key and a user specified datum in the given interpreter.
|
||||
If there is already an association with the given \fIkey\fR,
|
||||
\fBTcl_SetAssocData\fR overwrites it with the new information.
|
||||
It is up to callers to organize their use of names to avoid conflicts,
|
||||
for example, by using package names as the keys.
|
||||
If the \fIdeleteProc\fR argument is non-NULL it specifies the address of a
|
||||
procedure to invoke if the interpreter is deleted before the association
|
||||
is deleted. \fIDeleteProc\fR should have arguments and result that match
|
||||
the type \fBTcl_InterpDeleteProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_InterpDeleteProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR);
|
||||
.CE
|
||||
When \fIdeleteProc\fR is invoked the \fIclientData\fR and \fIinterp\fR
|
||||
arguments will be the same as the corresponding arguments passed to
|
||||
\fBTcl_SetAssocData\fR.
|
||||
The deletion procedure will \fInot\fR be invoked if the association
|
||||
is deleted before the interpreter is deleted.
|
||||
.PP
|
||||
\fBTcl_GetAssocData\fR returns the datum stored in the association with the
|
||||
specified key in the given interpreter, and if the \fIdelProcPtr\fR field
|
||||
is non-\fBNULL\fR, the address indicated by it gets the address of the
|
||||
delete procedure stored with this association. If no association with the
|
||||
specified key exists in the given interpreter \fBTcl_GetAssocData\fR
|
||||
returns \fBNULL\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteAssocData\fR deletes an association with a specified key in
|
||||
the given interpreter. It does not call the deletion procedure.
|
||||
.SH KEYWORDS
|
||||
association, data, deletion procedure, interpreter, key
|
||||
@@ -1,156 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Async.3 1.14 96/08/26 12:59:41
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_AsyncCreate 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_AsyncCreate, Tcl_AsyncMark, Tcl_AsyncInvoke, Tcl_AsyncDelete \- handle asynchronous events
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_AsyncHandler
|
||||
\fBTcl_AsyncCreate\fR(\fIproc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_AsyncMark\fR(\fIasync\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_AsyncInvoke\fR(\fIinterp, code\fR)
|
||||
.sp
|
||||
\fBTcl_AsyncDelete\fR(\fIasync\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_AsyncReady\fR()
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_AsyncHandler clientData
|
||||
.AP Tcl_AsyncProc *proc in
|
||||
Procedure to invoke to handle an asynchronous event.
|
||||
.AP ClientData clientData in
|
||||
One-word value to pass to \fIproc\fR.
|
||||
.AP Tcl_AsyncHandler async in
|
||||
Token for asynchronous event handler.
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter in which command was being evaluated when handler was
|
||||
invoked, or NULL if handler was invoked when there was no interpreter
|
||||
active.
|
||||
.AP int code in
|
||||
Completion code from command that just completed in \fIinterp\fR,
|
||||
or 0 if \fIinterp\fR is NULL.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures provide a safe mechanism for dealing with
|
||||
asynchronous events such as signals.
|
||||
If an event such as a signal occurs while a Tcl script is being
|
||||
evaluated then it isn't safe to take any substantive action to
|
||||
process the event.
|
||||
For example, it isn't safe to evaluate a Tcl script since the
|
||||
interpreter may already be in the middle of evaluating a script;
|
||||
it may not even be safe to allocate memory, since a memory
|
||||
allocation could have been in progress when the event occurred.
|
||||
The only safe approach is to set a flag indicating that the event
|
||||
occurred, then handle the event later when the world has returned
|
||||
to a clean state, such as after the current Tcl command completes.
|
||||
.PP
|
||||
\fBTcl_AsyncCreate\fR creates an asynchronous handler and returns
|
||||
a token for it.
|
||||
The asynchronous handler must be created before
|
||||
any occurrences of the asynchronous event that it is intended
|
||||
to handle (it is not safe to create a handler at the time of
|
||||
an event).
|
||||
When an asynchronous event occurs the code that detects the event
|
||||
(such as a signal handler) should call \fBTcl_AsyncMark\fR with the
|
||||
token for the handler.
|
||||
\fBTcl_AsyncMark\fR will mark the handler as ready to execute, but it
|
||||
will not invoke the handler immediately.
|
||||
Tcl will call the \fIproc\fR associated with the handler later, when
|
||||
the world is in a safe state, and \fIproc\fR can then carry out
|
||||
the actions associated with the asynchronous event.
|
||||
\fIProc\fR should have arguments and result that match the
|
||||
type \fBTcl_AsyncProc\fR:
|
||||
.CS
|
||||
typedef int Tcl_AsyncProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
int \fIcode\fR);
|
||||
.CE
|
||||
The \fIclientData\fR will be the same as the \fIclientData\fR
|
||||
argument passed to \fBTcl_AsyncCreate\fR when the handler was
|
||||
created.
|
||||
If \fIproc\fR is invoked just after a command has completed
|
||||
execution in an interpreter, then \fIinterp\fR will identify
|
||||
the interpreter in which the command was evaluated and
|
||||
\fIcode\fR will be the completion code returned by that
|
||||
command.
|
||||
The command's result will be present in \fIinterp->result\fR.
|
||||
When \fIproc\fR returns, whatever it leaves in \fIinterp->result\fR
|
||||
will be returned as the result of the command and the integer
|
||||
value returned by \fIproc\fR will be used as the new completion
|
||||
code for the command.
|
||||
.PP
|
||||
It is also possible for \fIproc\fR to be invoked when no interpreter
|
||||
is active.
|
||||
This can happen, for example, if an asynchronous event occurs while
|
||||
the application is waiting for interactive input or an X event.
|
||||
In this case \fIinterp\fR will be NULL and \fIcode\fR will be
|
||||
0, and the return value from \fIproc\fR will be ignored.
|
||||
.PP
|
||||
The procedure \fBTcl_AsyncInvoke\fR is called to invoke all of the
|
||||
handlers that are ready.
|
||||
The procedure \fBTcl_AsyncReady\fR will return non-zero whenever any
|
||||
asynchronous handlers are ready; it can be checked to avoid calls
|
||||
to \fBTcl_AsyncInvoke\fR when there are no ready handlers.
|
||||
Tcl calls \fBTcl_AsyncReady\fR after each command is evaluated
|
||||
and calls \fBTcl_AsyncInvoke\fR if needed.
|
||||
Applications may also call \fBTcl_AsyncInvoke\fR at interesting
|
||||
times for that application.
|
||||
For example, Tcl's event handler calls \fBTcl_AsyncReady\fR
|
||||
after each event and calls \fBTcl_AsyncInvoke\fR if needed.
|
||||
The \fIinterp\fR and \fIcode\fR arguments to \fBTcl_AsyncInvoke\fR
|
||||
have the same meaning as for \fIproc\fR: they identify the active
|
||||
interpreter, if any, and the completion code from the command
|
||||
that just completed.
|
||||
.PP
|
||||
\fBTcl_AsyncDelete\fR removes an asynchronous handler so that
|
||||
its \fIproc\fR will never be invoked again.
|
||||
A handler can be deleted even when ready, and it will still
|
||||
not be invoked.
|
||||
.PP
|
||||
If multiple handlers become active at the same time, the
|
||||
handlers are invoked in the order they were created (oldest
|
||||
handler first).
|
||||
The \fIcode\fR and \fIinterp->result\fR for later handlers
|
||||
reflect the values returned by earlier handlers, so that
|
||||
the most recently created handler has last say about
|
||||
the interpreter's result and completion code.
|
||||
If new handlers become ready while handlers are executing,
|
||||
\fBTcl_AsyncInvoke\fR will invoke them all; at each point it
|
||||
invokes the highest-priority (oldest) ready handler, repeating
|
||||
this over and over until there are no longer any ready handlers.
|
||||
|
||||
.SH WARNING
|
||||
.PP
|
||||
It is almost always a bad idea for an asynchronous event
|
||||
handler to modify \fIinterp->result\fR or return a code different
|
||||
from its \fIcode\fR argument.
|
||||
This sort of behavior can disrupt the execution of scripts in
|
||||
subtle ways and result in bugs that are extremely difficult
|
||||
to track down.
|
||||
If an asynchronous event handler needs to evaluate Tcl scripts
|
||||
then it should first save \fIinterp->result\fR plus the values
|
||||
of the variables \fBerrorInfo\fR and \fBerrorCode\fR (this can
|
||||
be done, for example, by storing them in dynamic strings).
|
||||
When the asynchronous handler is finished it should restore
|
||||
\fIinterp->result\fR, \fBerrorInfo\fR, and \fBerrorCode\fR,
|
||||
and return the \fIcode\fR argument.
|
||||
|
||||
.SH KEYWORDS
|
||||
asynchronous event, handler, signal
|
||||
@@ -1,58 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1992-1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) BackgdErr.3 1.3 96/03/25 19:56:51
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_BackgroundError 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_BackgroundError \- report Tcl error that occurred in background processing
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_BackgroundError\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which the error occurred.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure is typically invoked when a Tcl error occurs during
|
||||
``background processing'' such as executing an event handler.
|
||||
When such an error occurs, the error condition is reported to Tcl
|
||||
or to a widget or some other C code, and there is not usually any
|
||||
obvious way for that code to report the error to the user.
|
||||
In these cases the code calls \fBTcl_BackgroundError\fR with an
|
||||
\fIinterp\fR argument identifying the interpreter in which the
|
||||
error occurred. At the time \fBTcl_BackgroundError\fR is invoked,
|
||||
\fIinterp->result\fR is expected to contain an error message.
|
||||
\fBTcl_BackgroundError\fR will invoke the \fBbgerror\fR
|
||||
Tcl command to report the error in an application-specific fashion.
|
||||
If no \fBbgerror\fR command exists, or if it returns with an error condition,
|
||||
then \fBTcl_BackgroundError\fR reports the error itself by printing
|
||||
a message on the standard error file.
|
||||
.PP
|
||||
\fBTcl_BackgroundError\fR does not invoke \fBbgerror\fR immediately
|
||||
because this could potentially interfere with scripts that are in process
|
||||
at the time the error occurred.
|
||||
Instead, it invokes \fBbgerror\fR later as an idle callback.
|
||||
\fBTcl_BackgroundError\fR saves the values of the \fBerrorInfo\fR and
|
||||
\fBerrorCode\fR variables and restores these values just before
|
||||
invoking \fBbgerror\fR.
|
||||
.PP
|
||||
It is possible for many background errors to accumulate before
|
||||
\fBbgerror\fR is invoked. When this happens, each of the errors
|
||||
is processed in order. However, if \fBbgerror\fR returns a
|
||||
break exception, then all remaining error reports for the
|
||||
interpreter are skipped.
|
||||
|
||||
.SH KEYWORDS
|
||||
background, bgerror, error
|
||||
@@ -1,45 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Backslash.3 1.16 96/03/25 19:57:09
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Backslash 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Backslash \- parse a backslash sequence
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char
|
||||
\fBTcl_Backslash\fR(\fIsrc, countPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS char *countPtr
|
||||
.AP char *src in
|
||||
Pointer to a string starting with a backslash.
|
||||
.AP int *countPtr out
|
||||
If \fIcountPtr\fR isn't NULL, \fI*countPtr\fR gets filled
|
||||
in with number of characters in the backslash sequence, including
|
||||
the backslash character.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This is a utility procedure used by several of the Tcl
|
||||
commands. It parses a backslash sequence and returns
|
||||
the single character corresponding to the sequence.
|
||||
\fBTcl_Backslash\fR modifies \fI*countPtr\fR to contain the number
|
||||
of characters in the backslash sequence.
|
||||
.PP
|
||||
See the Tcl manual entry for information on the valid
|
||||
backslash sequences.
|
||||
All of the sequences described in the Tcl
|
||||
manual entry are supported by \fBTcl_Backslash\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
backslash, parse
|
||||
@@ -1,83 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) BoolObj.3 1.7 97/05/08 19:50:57
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_BooleanObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_NewBooleanObj, Tcl_SetBooleanObj, Tcl_GetBooleanFromObj \- manipulate Tcl objects as boolean values
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewBooleanObj\fR(\fIboolValue\fR)
|
||||
.sp
|
||||
\fBTcl_SetBooleanObj\fR(\fIobjPtr, boolValue\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetBooleanFromObj\fR(\fIinterp, objPtr, boolPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP int boolValue in
|
||||
Integer value used to initialize or set a boolean object.
|
||||
If the integer is nonzero, the boolean object is set to 1;
|
||||
otherwise the boolean object is set to 0.
|
||||
.AP Tcl_Obj *objPtr in/out
|
||||
For \fBTcl_SetBooleanObj\fR, this points to the object to be converted
|
||||
to boolean type.
|
||||
For \fBTcl_GetBooleanFromObj\fR, this refers to the object
|
||||
from which to get a boolean value;
|
||||
if \fIobjPtr\fR does not already point to a boolean object,
|
||||
an attempt will be made to convert it to one.
|
||||
.AP Tcl_Interp *interp in/out
|
||||
If an error occurs during conversion,
|
||||
an error message is left in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
.AP int *boolPtr out
|
||||
Points to place where \fBTcl_GetBooleanFromObj\fR
|
||||
stores the boolean value (0 or 1) obtained from \fIobjPtr\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures are used to create, modify, and read
|
||||
boolean Tcl objects from C code.
|
||||
\fBTcl_NewBooleanObj\fR and \fBTcl_SetBooleanObj\fR
|
||||
will create a new object of boolean type
|
||||
or modify an existing object to have boolean type.
|
||||
Both of these procedures set the object to have the
|
||||
boolean value (0 or 1) specified by \fIboolValue\fR;
|
||||
if \fIboolValue\fR is nonzero, the object is set to 1,
|
||||
otherwise to 0.
|
||||
\fBTcl_NewBooleanObj\fR returns a pointer to a newly created object
|
||||
with reference count zero.
|
||||
Both procedures set the object's type to be boolean
|
||||
and assign the boolean value to the object's internal representation
|
||||
\fIlongValue\fR member.
|
||||
\fBTcl_SetBooleanObj\fR invalidates any old string representation
|
||||
and, if the object is not already a boolean object,
|
||||
frees any old internal representation.
|
||||
.PP
|
||||
\fBTcl_GetBooleanFromObj\fR attempts to return a boolean value
|
||||
from the Tcl object \fIobjPtr\fR.
|
||||
If the object is not already a boolean object,
|
||||
it will attempt to convert it to one.
|
||||
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
Otherwise, \fBTcl_GetBooleanFromObj\fR returns \fBTCL_OK\fR
|
||||
and stores the boolean value in the address given by \fIboolPtr\fR.
|
||||
If the object is not already a boolean object,
|
||||
the conversion will free any old internal representation.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
boolean, boolean object, boolean type, internal representation, object, object type, string representation
|
||||
@@ -1,63 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CallDel.3 1.11 96/03/25 19:57:25
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CallWhenDeleted 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CallWhenDeleted, Tcl_DontCallWhenDeleted \- Arrange for callback when interpreter is deleted
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_CallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
|
||||
.sp
|
||||
\fBTcl_DontCallWhenDeleted\fR(\fIinterp\fR, \fIproc\fR, \fIclientData\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_InterpDeleteProc clientData
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter with which to associated callback.
|
||||
.AP Tcl_InterpDeleteProc *proc in
|
||||
Procedure to call when \fIinterp\fR is deleted.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CallWhenDeleted\fR arranges for \fIproc\fR to be called by
|
||||
\fBTcl_DeleteInterp\fR if/when \fIinterp\fR is deleted at some future
|
||||
time. \fIProc\fR will be invoked just before the interpreter
|
||||
is deleted, but the interpreter will still be valid at the
|
||||
time of the call.
|
||||
\fIProc\fR should have arguments and result that match the
|
||||
type \fBTcl_InterpDeleteProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_InterpDeleteProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR);
|
||||
.CE
|
||||
The \fIclientData\fR and \fIinterp\fR parameters are
|
||||
copies of the \fIclientData\fR and \fIinterp\fR arguments given
|
||||
to \fBTcl_CallWhenDeleted\fR.
|
||||
Typically, \fIclientData\fR points to an application-specific
|
||||
data structure that \fIproc\fR uses to perform cleanup when an
|
||||
interpreter is about to go away.
|
||||
\fIProc\fR does not return a value.
|
||||
.PP
|
||||
\fBTcl_DontCallWhenDeleted\fR cancels a previous call to
|
||||
\fBTcl_CallWhenDeleted\fR with the same arguments, so that
|
||||
\fIproc\fR won't be called after all when \fIinterp\fR is
|
||||
deleted.
|
||||
If there is no deletion callback that matches \fIinterp\fR,
|
||||
\fIproc\fR, and \fIclientData\fR then the call to
|
||||
\fBTcl_DontCallWhenDeleted\fR has no effect.
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, delete, interpreter
|
||||
@@ -1,36 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CmdCmplt.3 1.6 96/03/25 19:57:46
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CommandComplete 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CommandComplete \- Check for unmatched braces in a Tcl command
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_CommandComplete\fR(\fIcmd\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS char *cmd
|
||||
.AP char *cmd in
|
||||
Command string to test for completeness.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CommandComplete\fR takes a Tcl command string
|
||||
as argument and determines whether it contains one or more
|
||||
complete commands (i.e. there are no unclosed quotes, braces,
|
||||
brackets, or variable references).
|
||||
If the command string is complete then it returns 1; otherwise it returns 0.
|
||||
|
||||
.SH KEYWORDS
|
||||
complete command, partial command
|
||||
@@ -1,55 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Concat.3 1.12 97/06/11 17:54:12
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Concat 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Concat \- concatenate a collection of strings
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_Concat\fR(\fIargc, argv\fR)
|
||||
.SH ARGUMENTS
|
||||
.AP int argc in
|
||||
Number of strings.
|
||||
.AP char *argv[] in
|
||||
Array of strings to concatenate. Must have \fIargc\fR entries.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_Concat\fR is a utility procedure used by several of the
|
||||
Tcl commands. Given a collection of strings, it concatenates
|
||||
them together into a single string, with the original strings
|
||||
separated by spaces. This procedure behaves differently than
|
||||
\fBTcl_Merge\fR, in that the arguments are simply concatenated:
|
||||
no effort is made to ensure proper list structure.
|
||||
However, in most common usage the arguments will all be proper
|
||||
lists themselves; if this is true, then the result will also have
|
||||
proper list structure.
|
||||
.PP
|
||||
\fBTcl_Concat\fR eliminates leading and trailing white space as it
|
||||
copies strings from \fBargv\fR to the result. If an element of
|
||||
\fBargv\fR consists of nothing but white space, then that string
|
||||
is ignored entirely. This white-space removal was added to make
|
||||
the output of the \fBconcat\fR command cleaner-looking.
|
||||
.PP
|
||||
.VS
|
||||
The result string is dynamically allocated
|
||||
using \fBTcl_Alloc\fR; the caller must eventually release the space
|
||||
by calling \fBTcl_Free\fR.
|
||||
.VE
|
||||
.VS
|
||||
.SH "SEE ALSO"
|
||||
Tcl_ConcatObj
|
||||
.SH KEYWORDS
|
||||
concatenate, strings
|
||||
@@ -1,571 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtChannel.3 1.29 97/06/20 13:37:45
|
||||
.so man.macros
|
||||
.TH Tcl_CreateChannel 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_CreateChannel, Tcl_GetChannelInstanceData, Tcl_GetChannelType, Tcl_GetChannelName, Tcl_GetChannelHandle, Tcl_GetChannelMode, Tcl_GetChannelBufferSize, Tcl_SetDefaultTranslation, Tcl_SetChannelBufferSize, Tcl_NotifyChannel, Tcl_BadChannelOption \- procedures for creating and manipulating channels
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_CreateChannel\fR(\fItypePtr, channelName, instanceData, mask\fR)
|
||||
.sp
|
||||
ClientData
|
||||
\fBTcl_GetChannelInstanceData\fR(\fIchannel\fR)
|
||||
.sp
|
||||
Tcl_ChannelType *
|
||||
\fBTcl_GetChannelType\fR(\fIchannel\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetChannelName\fR(\fIchannel\fR)
|
||||
.VS
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetChannelHandle\fR(\fIchannel, direction, handlePtr\fR)
|
||||
.VE
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetChannelFlags\fR(\fIchannel\fR)
|
||||
.sp
|
||||
\fBTcl_SetDefaultTranslation\fR(\fIchannel, transMode\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetChannelBufferSize\fR(\fIchannel\fR)
|
||||
.sp
|
||||
\fBTcl_SetChannelBufferSize\fR(\fIchannel, size\fR)
|
||||
.sp
|
||||
.VS
|
||||
\fBTcl_NotifyChannel\fR(\fIchannel, mask\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_BadChannelOption\fR(\fIinterp, optionName, optionList\fR)
|
||||
.VE
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_EolTranslation *channelName in
|
||||
.AP Tcl_ChannelType *typePtr in
|
||||
Points to a structure containing the addresses of procedures that
|
||||
can be called to perform I/O and other functions on the channel.
|
||||
.AP char *channelName in
|
||||
The name of this channel, such as \fBfile3\fR; must not be in use
|
||||
by any other channel. Can be NULL, in which case the channel is
|
||||
created without a name.
|
||||
.AP ClientData instanceData in
|
||||
Arbitrary one-word value to be associated with this channel. This
|
||||
value is passed to procedures in \fItypePtr\fR when they are invoked.
|
||||
.AP int mask in
|
||||
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
|
||||
whether a channel is readable and writable.
|
||||
.AP Tcl_Channel channel in
|
||||
The channel to operate on.
|
||||
.VS
|
||||
.AP int direction in
|
||||
\fBTCL_READABLE\fR means the input handle is wanted; \fBTCL_WRITABLE\fR
|
||||
means the output handle is wanted.
|
||||
.AP ClientData *handlePtr out
|
||||
Points to the location where the desired OS-specific handle should be
|
||||
stored.
|
||||
.VE
|
||||
.AP Tcl_EolTranslation transMode in
|
||||
The translation mode; one of the constants \fBTCL_TRANSLATE_AUTO\fR,
|
||||
\fBTCL_TRANSLATE_CR\fR, \fBTCL_TRANSLATE_LF\fR and \fBTCL_TRANSLATE_CRLF\fR.
|
||||
.AP int size in
|
||||
The size, in bytes, of buffers to allocate in this channel.
|
||||
.VS
|
||||
.AP int mask in
|
||||
An OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
|
||||
and \fBTCL_EXCEPTION\fR that indicates events that have occurred on
|
||||
this channel.
|
||||
.AP Tcl_Interp *interp in
|
||||
Current interpreter. (can be NULL)
|
||||
.AP char *optionName in
|
||||
Name of the invalid option.
|
||||
.AP char *optionList in
|
||||
Specific options list (space separated words, without "-")
|
||||
to append to the standard generic options list.
|
||||
Can be NULL for generic options error message only.
|
||||
.VE
|
||||
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Tcl uses a two-layered channel architecture. It provides a generic upper
|
||||
layer to enable C and Tcl programs to perform input and output using the
|
||||
same APIs for a variety of files, devices, sockets etc. The generic C APIs
|
||||
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
|
||||
.PP
|
||||
The lower layer provides type-specific channel drivers for each type
|
||||
of device supported on each platform. This manual entry describes the
|
||||
C APIs used to communicate between the generic layer and the
|
||||
type-specific channel drivers. It also explains how new types of
|
||||
channels can be added by providing new channel drivers.
|
||||
.PP
|
||||
Channel drivers consist of a number of components: First, each channel
|
||||
driver provides a \fBTcl_ChannelType\fR structure containing pointers to
|
||||
functions implementing the various operations used by the generic layer to
|
||||
communicate with the channel driver. The \fBTcl_ChannelType\fR structure
|
||||
and the functions referenced by it are described in the section
|
||||
TCL_CHANNELTYPE, below.
|
||||
.PP
|
||||
Second, channel drivers usually provide a Tcl command to create
|
||||
instances of that type of channel. For example, the Tcl \fBopen\fR
|
||||
command creates channels that use the file and command channel
|
||||
drivers, and the Tcl \fBsocket\fR command creates channels that use
|
||||
TCP sockets for network communication.
|
||||
.PP
|
||||
Third, a channel driver optionally provides a C function to open
|
||||
channel instances of that type. For example, \fBTcl_OpenFileChannel\fR
|
||||
opens a channel that uses the file channel driver, and
|
||||
\fBTcl_OpenTcpClient\fR opens a channel that uses the TCP network
|
||||
protocol. These creation functions typically use
|
||||
\fBTcl_CreateChannel\fR internally to open the channel.
|
||||
.PP
|
||||
To add a new type of channel you must implement a C API or a Tcl command
|
||||
that opens a channel by invoking \fBTcl_CreateChannel\fR.
|
||||
When your driver calls \fBTcl_CreateChannel\fR it passes in
|
||||
a \fBTcl_ChannelType\fR structure describing the driver's I/O
|
||||
procedures.
|
||||
The generic layer will then invoke the functions referenced in that
|
||||
structure to perform operations on the channel.
|
||||
.PP
|
||||
\fBTcl_CreateChannel\fR opens a new channel and associates the supplied
|
||||
\fItypePtr\fR and \fIinstanceData\fR with it. The channel is opened in the
|
||||
mode indicated by \fImask\fR.
|
||||
For a discussion of channel drivers, their operations and the
|
||||
\fBTcl_ChannelType\fR structure, see the section TCL_CHANNELTYPE, below.
|
||||
.PP
|
||||
\fBTcl_GetChannelInstanceData\fR returns the instance data associated with
|
||||
the channel in \fIchannel\fR. This is the same as the \fIinstanceData\fR
|
||||
argument in the call to \fBTcl_CreateChannel\fR that created this channel.
|
||||
.PP
|
||||
\fBTcl_GetChannelType\fR returns a pointer to the \fBTcl_ChannelType\fR
|
||||
structure used by the channel in the \fIchannel\fR argument. This is
|
||||
the same as the \fItypePtr\fR argument in the call to
|
||||
\fBTcl_CreateChannel\fR that created this channel.
|
||||
.PP
|
||||
\fBTcl_GetChannelName\fR returns a string containing the name associated
|
||||
with the channel, or NULL if the \fIchannelName\fR argument to
|
||||
\fBTcl_CreateChannel\fR was NULL.
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_GetChannelHandle\fR places the OS-specific device handle
|
||||
associated with \fIchannel\fR for the given \fIdirection\fR in the
|
||||
location specified by \fIhandlePtr\fR and returns \fBTCL_OK\fR. If
|
||||
the channel does not have a device handle for the specified direction,
|
||||
then \fBTCL_ERROR\fR is returned instead. Different channel drivers
|
||||
will return different types of handle. Refer to the manual entries
|
||||
for each driver to determine what type of handle is returned.
|
||||
.VE
|
||||
.PP
|
||||
\fBTcl_GetChannelMode\fR returns an OR-ed combination of \fBTCL_READABLE\fR
|
||||
and \fBTCL_WRITABLE\fR, indicating whether the channel is open for input
|
||||
and output.
|
||||
.PP
|
||||
\fBTcl_SetDefaultTranslation\fR sets the default end of line translation
|
||||
mode. This mode will be installed as the translation mode for the channel
|
||||
if an attempt is made to output on the channel while it is still in
|
||||
\fBTCL_TRANSLATE_AUTO\fR mode. For a description of end of line translation
|
||||
modes, see the manual entry for \fBfconfigure\fR.
|
||||
.PP
|
||||
\fBTcl_GetChannelBufferSize\fR returns the size, in bytes, of buffers
|
||||
allocated to store input or output in \fIchan\fR. If the value was not set
|
||||
by a previous call to \fBTcl_SetChannelBufferSize\fR, described below, then
|
||||
the default value of 4096 is returned.
|
||||
.PP
|
||||
\fBTcl_SetChannelBufferSize\fR sets the size, in bytes, of buffers that
|
||||
will be allocated in subsequent operations on the channel to store input or
|
||||
output. The \fIsize\fR argument should be between ten and one million,
|
||||
allowing buffers of ten bytes to one million bytes. If \fIsize\fR is
|
||||
outside this range, \fBTcl_SetChannelBufferSize\fR sets the buffer size to
|
||||
4096.
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_NotifyChannel\fR is called by a channel driver to indicate to
|
||||
the generic layer that the events specified by \fImask\fR have
|
||||
occurred on the channel. Channel drivers are responsible for invoking
|
||||
this function whenever the channel handlers need to be called for the
|
||||
channel. See \fBWATCHPROC\fR below for more details.
|
||||
.VE
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_BadChannelOption\fR is called from driver specific set or get option
|
||||
procs to generate a complete error message.
|
||||
.VE
|
||||
|
||||
.SH TCL_CHANNELTYPE
|
||||
.PP
|
||||
A channel driver provides a \fBTcl_ChannelType\fR structure that contains
|
||||
pointers to functions that implement the various operations on a channel;
|
||||
these operations are invoked as needed by the generic layer. The
|
||||
\fBTcl_ChannelType\fR structure contains the following fields:
|
||||
.PP
|
||||
.VS
|
||||
.CS
|
||||
typedef struct Tcl_ChannelType {
|
||||
char *\fItypeName\fR;
|
||||
Tcl_DriverBlockModeProc *\fIblockModeProc\fR;
|
||||
Tcl_DriverCloseProc *\fIcloseProc\fR;
|
||||
Tcl_DriverInputProc *\fIinputProc\fR;
|
||||
Tcl_DriverOutputProc *\fIoutputProc\fR;
|
||||
Tcl_DriverSeekProc *\fIseekProc\fR;
|
||||
Tcl_DriverSetOptionProc *\fIsetOptionProc\fR;
|
||||
Tcl_DriverGetOptionProc *\fIgetOptionProc\fR;
|
||||
Tcl_DriverWatchProc *\fIwatchProc\fR;
|
||||
Tcl_DriverGetHandleProc *\fIgetHandleProc\fR;
|
||||
} Tcl_ChannelType;
|
||||
.CE
|
||||
.VE
|
||||
.PP
|
||||
The driver must provide implementations for all functions except
|
||||
\fIblockModeProc\fR, \fIseekProc\fR, \fIsetOptionProc\fR, and
|
||||
\fIgetOptionProc\fR, which may be specified as NULL to indicate that the
|
||||
channel does not support seeking. Other functions that can not be
|
||||
implemented for this type of device should return \fBEINVAL\fR when invoked
|
||||
to indicate that they are not implemented.
|
||||
|
||||
.SH TYPENAME
|
||||
.PP
|
||||
The \fItypeName\fR field contains a null-terminated string that
|
||||
identifies the type of the device implemented by this driver, e.g.
|
||||
\fBfile\fR or \fBsocket\fR.
|
||||
|
||||
.SH BLOCKMODEPROC
|
||||
.PP
|
||||
The \fIblockModeProc\fR field contains the address of a function called by
|
||||
the generic layer to set blocking and nonblocking mode on the device.
|
||||
\fIBlockModeProc\fR should match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverBlockModeProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
int \fImode\fR);
|
||||
.CE
|
||||
.PP
|
||||
The \fIinstanceData\fR is the same as the value passed to
|
||||
\fBTcl_CreateChannel\fR when this channel was created. The \fImode\fR
|
||||
argument is either \fBTCL_MODE_BLOCKING\fR or \fBTCL_MODE_NONBLOCKING\fR to
|
||||
set the device into blocking or nonblocking mode. The function should
|
||||
return zero if the operation was successful, or a nonzero POSIX error code
|
||||
if the operation failed.
|
||||
.PP
|
||||
If the operation is successful, the function can modify the supplied
|
||||
\fIinstanceData\fR to record that the channel entered blocking or
|
||||
nonblocking mode and to implement the blocking or nonblocking behavior.
|
||||
For some device types, the blocking and nonblocking behavior can be
|
||||
implemented by the underlying operating system; for other device types, the
|
||||
behavior must be emulated in the channel driver.
|
||||
|
||||
.SH CLOSEPROC
|
||||
.PP
|
||||
The \fIcloseProc\fR field contains the address of a function called by the
|
||||
generic layer to clean up driver-related information when the channel is
|
||||
closed. \fICloseProc\fR must match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverCloseProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
Tcl_Interp *\fIinterp\fR);
|
||||
.CE
|
||||
.PP
|
||||
The \fIinstanceData\fR argument is the same as the value provided to
|
||||
\fBTcl_CreateChannel\fR when the channel was created. The function should
|
||||
release any storage maintained by the channel driver for this channel, and
|
||||
close the input and output devices encapsulated by this channel. All queued
|
||||
output will have been flushed to the device before this function is called,
|
||||
and no further driver operations will be invoked on this instance after
|
||||
calling the \fIcloseProc\fR. If the close operation is successful, the
|
||||
procedure should return zero; otherwise it should return a nonzero POSIX
|
||||
error code. In addition, if an error occurs and \fIinterp\fR is not NULL,
|
||||
the procedure should store an error message in \fIinterp->result\fR.
|
||||
|
||||
.SH INPUTPROC
|
||||
.PP
|
||||
The \fIinputProc\fR field contains the address of a function called by the
|
||||
generic layer to read data from the file or device and store it in an
|
||||
internal buffer. \fIInputProc\fR must match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverInputProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
char *\fIbuf\fR,
|
||||
int \fIbufSize\fR,
|
||||
int *\fIerrorCodePtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
\fIInstanceData\fR is the same as the value passed to
|
||||
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
|
||||
argument points to an array of bytes in which to store input from the
|
||||
device, and the \fIbufSize\fR argument indicates how many bytes are
|
||||
available at \fIbuf\fR.
|
||||
.PP
|
||||
The \fIerrorCodePtr\fR argument points to an integer variable provided by
|
||||
the generic layer. If an error occurs, the function should set the variable
|
||||
to a POSIX error code that identifies the error that occurred.
|
||||
.PP
|
||||
The function should read data from the input device encapsulated by the
|
||||
channel and store it at \fIbuf\fR. On success, the function should return
|
||||
a nonnegative integer indicating how many bytes were read from the input
|
||||
device and stored at \fIbuf\fR. On error, the function should return -1. If
|
||||
an error occurs after some data has been read from the device, that data is
|
||||
lost.
|
||||
.PP
|
||||
If \fIinputProc\fR can determine that the input device has some data
|
||||
available but less than requested by the \fIbufSize\fR argument, the
|
||||
function should only attempt to read as much data as is available and
|
||||
return without blocking. If the input device has no data available
|
||||
whatsoever and the channel is in nonblocking mode, the function should
|
||||
return an \fBEAGAIN\fR error. If the input device has no data available
|
||||
whatsoever and the channel is in blocking mode, the function should block
|
||||
for the shortest possible time until at least one byte of data can be read
|
||||
from the device; then, it should return as much data as it can read without
|
||||
blocking.
|
||||
|
||||
.SH OUTPUTPROC
|
||||
.PP
|
||||
The \fIoutputProc\fR field contains the address of a function called by the
|
||||
generic layer to transfer data from an internal buffer to the output device.
|
||||
\fIOutputProc\fR must match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverOutputProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
char *\fIbuf\fR,
|
||||
int \fItoWrite\fR,
|
||||
int *\fIerrorCodePtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
\fIInstanceData\fR is the same as the value passed to
|
||||
\fBTcl_CreateChannel\fR when the channel was created. The \fIbuf\fR
|
||||
argument contains an array of bytes to be written to the device, and the
|
||||
\fItoWrite\fR argument indicates how many bytes are to be written from the
|
||||
\fIbuf\fR argument.
|
||||
.PP
|
||||
The \fIerrorCodePtr\fR argument points to an integer variable provided by
|
||||
the generic layer. If an error occurs, the function should set this
|
||||
variable to a POSIX error code that identifies the error.
|
||||
.PP
|
||||
The function should write the data at \fIbuf\fR to the output device
|
||||
encapsulated by the channel. On success, the function should return a
|
||||
nonnegative integer indicating how many bytes were written to the output
|
||||
device. The return value is normally the same as \fItoWrite\fR, but may be
|
||||
less in some cases such as if the output operation is interrupted by a
|
||||
signal. If an error occurs the function should return -1. In case of
|
||||
error, some data may have been written to the device.
|
||||
.PP
|
||||
If the channel is nonblocking and the output device is unable to absorb any
|
||||
data whatsoever, the function should return -1 with an \fBEAGAIN\fR error
|
||||
without writing any data.
|
||||
|
||||
.SH SEEKPROC
|
||||
.PP
|
||||
The \fIseekProc\fR field contains the address of a function called by the
|
||||
generic layer to move the access point at which subsequent input or output
|
||||
operations will be applied. \fISeekProc\fR must match the following
|
||||
prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverSeekProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
long \fIoffset\fR,
|
||||
int \fIseekMode\fR,
|
||||
int *\fIerrorCodePtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
The \fIinstanceData\fR argument is the same as the value given to
|
||||
\fBTcl_CreateChannel\fR when this channel was created. \fIOffset\fR and
|
||||
\fIseekMode\fR have the same meaning as for the \fBTcl_SeekChannel\fR
|
||||
procedure (described in the manual entry for \fBTcl_OpenFileChannel\fR).
|
||||
.PP
|
||||
The \fIerrorCodePtr\fR argument points to an integer variable provided by
|
||||
the generic layer for returning \fBerrno\fR values from the function. The
|
||||
function should set this variable to a POSIX error code if an error occurs.
|
||||
The function should store an \fBEINVAL\fR error code if the channel type
|
||||
does not implement seeking.
|
||||
.PP
|
||||
The return value is the new access point or -1 in case of error. If an
|
||||
error occurred, the function should not move the access point.
|
||||
|
||||
.SH SETOPTIONPROC
|
||||
.PP
|
||||
The \fIsetOptionProc\fR field contains the address of a function called by
|
||||
the generic layer to set a channel type specific option on a channel.
|
||||
\fIsetOptionProc\fR must match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverSetOptionProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
char *\fIoptionName\fR,
|
||||
char *\fIoptionValue\fR);
|
||||
.CE
|
||||
.PP
|
||||
\fIoptionName\fR is the name of an option to set, and \fIoptionValue\fR is
|
||||
the new value for that option, as a string. The \fIinstanceData\fR is the
|
||||
same as the value given to \fBTcl_CreateChannel\fR when this channel was
|
||||
created. The function should do whatever channel type specific action is
|
||||
required to implement the new value of the option.
|
||||
.PP
|
||||
Some options are handled by the generic code and this function is never
|
||||
called to set them, e.g. \fB-blockmode\fR. Other options are specific to
|
||||
each channel type and the \fIsetOptionProc\fR procedure of the channel
|
||||
driver will get called to implement them. The \fIsetOptionProc\fR field can
|
||||
be NULL, which indicates that this channel type supports no type specific
|
||||
options.
|
||||
.PP
|
||||
If the option value is successfully modified to the new value, the function
|
||||
returns \fBTCL_OK\fR.
|
||||
.VS
|
||||
It should call \fBTcl_BadChannelOption\fR which itself returns
|
||||
\fBTCL_ERROR\fR if the \fIoptionName\fR is
|
||||
unrecognized.
|
||||
.VE
|
||||
If \fIoptionValue\fR specifies a value for the option that
|
||||
is not supported or if a system call error occurs,
|
||||
the function should leave an error message in the
|
||||
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
|
||||
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
|
||||
error code.
|
||||
|
||||
.SH GETOPTIONPROC
|
||||
.PP
|
||||
The \fIgetOptionProc\fR field contains the address of a function called by
|
||||
the generic layer to get the value of a channel type specific option on a
|
||||
channel. \fIgetOptionProc\fR must match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverGetOptionProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
.VS
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
.VE
|
||||
char *\fIoptionName\fR,
|
||||
Tcl_DString *\fIdsPtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
\fIOptionName\fR is the name of an option supported by this type of
|
||||
channel. If the option name is not NULL, the function stores its current
|
||||
value, as a string, in the Tcl dynamic string \fIdsPtr\fR.
|
||||
If \fIoptionName\fR is NULL, the function stores in \fIdsPtr\fR an
|
||||
alternating list of all supported options and their current values.
|
||||
On success, the function returns \fBTCL_OK\fR.
|
||||
.VS
|
||||
It should call \fBTcl_BadChannelOption\fR which itself returns
|
||||
\fBTCL_ERROR\fR if the \fIoptionName\fR is
|
||||
unrecognized. If a system call error occurs,
|
||||
the function should leave an error message in the
|
||||
\fIresult\fR field of \fIinterp\fR if \fIinterp\fR is not NULL. The
|
||||
function should also call \fBTcl_SetErrno\fR to store an appropriate POSIX
|
||||
error code.
|
||||
.VE
|
||||
.PP
|
||||
Some options are handled by the generic code and this function is never
|
||||
called to retrieve their value, e.g. \fB-blockmode\fR. Other options are
|
||||
specific to each channel type and the \fIgetOptionProc\fR procedure of the
|
||||
channel driver will get called to implement them. The \fIgetOptionProc\fR
|
||||
field can be NULL, which indicates that this channel type supports no type
|
||||
specific options.
|
||||
|
||||
.SH WATCHPROC
|
||||
.VS
|
||||
.PP
|
||||
The \fIwatchProc\fR field contains the address of a function called
|
||||
by the generic layer to initialize the event notification mechanism to
|
||||
notice events of interest on this channel.
|
||||
\fIWatchProc\fR should match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef void Tcl_DriverWatchProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
int \fImask\fR);
|
||||
.CE
|
||||
.VE
|
||||
.PP
|
||||
The \fIinstanceData\fR is the same as the value passed to
|
||||
\fBTcl_CreateChannel\fR when this channel was created. The \fImask\fR
|
||||
argument is an OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR
|
||||
and \fBTCL_EXCEPTION\fR; it indicates events the caller is interested in
|
||||
noticing on this channel.
|
||||
.PP
|
||||
.VS
|
||||
The function should initialize device type specific mechanisms to
|
||||
notice when an event of interest is present on the channel. When one
|
||||
or more of the designated events occurs on the channel, the channel
|
||||
driver is responsible for calling \fBTcl_NotifyChannel\fR to inform
|
||||
the generic channel module. The driver should take care not to starve
|
||||
other channel drivers or sources of callbacks by invoking
|
||||
Tcl_NotifyChannel too frequently. Fairness can be insured by using
|
||||
the Tcl event queue to allow the channel event to be scheduled in sequence
|
||||
with other events. See the description of \fBTcl_QueueEvent\fR for
|
||||
details on how to queue an event.
|
||||
|
||||
.SH GETHANDLEPROC
|
||||
.PP
|
||||
The \fIgetHandleProc\fR field contains the address of a function called by
|
||||
the generic layer to retrieve a device-specific handle from the channel.
|
||||
\fIGetHandleProc\fR should match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef int Tcl_DriverGetHandleProc(
|
||||
ClientData \fIinstanceData\fR,
|
||||
int \fIdirection\fR,
|
||||
ClientData *\fIhandlePtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
\fIInstanceData is the same as the value passed to
|
||||
\fBTcl_CreateChannel\fR when this channel was created. The \fIdirection\fR
|
||||
argument is either \fBTCL_READABLE\fR to retrieve the handle used
|
||||
for input, or \fBTCL_WRITABLE\fR to retrieve the handle used for
|
||||
output.
|
||||
.PP
|
||||
If the channel implementation has device-specific handles, the
|
||||
function should retrieve the appropriate handle associated with the
|
||||
channel, according the \fIdirection\fR argument. The handle should be
|
||||
stored in the location referred to by \fIhandlePtr\fR, and
|
||||
\fBTCL_OK\fR should be returned. If the channel is not open for the
|
||||
specified direction, or if the channel implementation does not use
|
||||
device handles, the function should return \fBTCL_ERROR\fR.
|
||||
.VE
|
||||
|
||||
.VS
|
||||
.SH TCL_BADCHANNELOPTION
|
||||
.PP
|
||||
This procedure generates a "bad option" error message in an
|
||||
(optional) interpreter. It is used by channel drivers when
|
||||
a invalid Set/Get option is requested. Its purpose is to concatenate
|
||||
the generic options list to the specific ones and factorize
|
||||
the generic options error message string.
|
||||
.PP
|
||||
It always return \fBTCL_ERROR\fR
|
||||
.PP
|
||||
An error message is generated in interp's result object to
|
||||
indicate that a command was invoked with the a bad option
|
||||
The message has the form
|
||||
.CS
|
||||
bad option "blah": should be one of
|
||||
<...generic options...>+<...specific options...>
|
||||
so you get for instance:
|
||||
bad option "-blah": should be one of -blocking,
|
||||
-buffering, -buffersize, -eofchar, -translation,
|
||||
-peername, or -sockname
|
||||
when called with optionList="peername sockname"
|
||||
.CE
|
||||
"blah" is the optionName argument and "<specific options>"
|
||||
is a space separated list of specific option words.
|
||||
The function takes good care of inserting minus signs before
|
||||
each option, commas after, and an "or" before the last option.
|
||||
.VE
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_Close(3), Tcl_OpenFileChannel(3), Tcl_SetErrno(3), Tcl_QueueEvent(3)
|
||||
|
||||
.SH KEYWORDS
|
||||
blocking, channel driver, channel registration, channel type, nonblocking
|
||||
@@ -1,92 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtChnlHdlr.3 1.10 96/03/14 10:54:43
|
||||
.so man.macros
|
||||
.TH Tcl_CreateChannelHandler 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_CreateChannelHandler, Tcl_DeleteChannelHandler \- call a procedure when a channel becomes readable or writable
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
void
|
||||
\fBTcl_CreateChannelHandler\fR(\fIchannel, mask, proc, clientData\fR)
|
||||
.sp
|
||||
void
|
||||
\fBTcl_DeleteChannelHandler\fR(\fIchannel, proc, clientData\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ChannelProc clientData
|
||||
.AP Tcl_Channel channel in
|
||||
Tcl channel such as returned by \fBTcl_CreateChannel\fR.
|
||||
.AP int mask in
|
||||
Conditions under which \fIproc\fR should be called: OR-ed combination of
|
||||
\fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR and \fBTCL_EXCEPTION\fR. Specify
|
||||
a zero value to temporarily disable an existing handler.
|
||||
.AP Tcl_FileProc *proc in
|
||||
Procedure to invoke whenever the channel indicated by \fIchannel\fR meets
|
||||
the conditions specified by \fImask\fR.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateChannelHandler\fR arranges for \fIproc\fR to be called in the
|
||||
future whenever input or output becomes possible on the channel identified
|
||||
by \fIchannel\fR, or whenever an exceptional condition exists for
|
||||
\fIchannel\fR. The conditions of interest under which \fIproc\fR will be
|
||||
invoked are specified by the \fImask\fR argument.
|
||||
See the manual entry for \fBfileevent\fR for a precise description of
|
||||
what it means for a channel to be readable or writable.
|
||||
\fIProc\fR must conform to the following prototype:
|
||||
.CS
|
||||
typedef void Tcl_ChannelProc(
|
||||
ClientData \fIclientData\fR,
|
||||
int \fImask\fR);
|
||||
.CE
|
||||
.PP
|
||||
The \fIclientData\fR argument is the same as the value passed to
|
||||
\fBTcl_CreateChannelHandler\fR when the handler was created. Typically,
|
||||
\fIclientData\fR points to a data structure containing application-specific
|
||||
information about the channel. \fIMask\fR is an integer mask indicating
|
||||
which of the requested conditions actually exists for the channel; it will
|
||||
contain a subset of the bits from the \fImask\fR argument to
|
||||
\fBTcl_CreateChannelHandler\fR when the handler was created.
|
||||
.PP
|
||||
Each channel handler is identified by a unique combination of \fIchannel\fR,
|
||||
\fIproc\fR and \fIclientData\fR.
|
||||
There may be many handlers for a given channel as long as they don't
|
||||
have the same \fIchannel\fR, \fIproc\fR, and \fIclientData\fR.
|
||||
If \fBTcl_CreateChannelHandler\fR is invoked when there is already a handler
|
||||
for \fIchannel\fR, \fIproc\fR, and \fIclientData\fR, then no new
|
||||
handler is created; instead, the \fImask\fR is changed for the
|
||||
existing handler.
|
||||
.PP
|
||||
\fBTcl_DeleteChannelHandler\fR deletes a channel handler identified by
|
||||
\fIchannel\fR, \fIproc\fR and \fIclientData\fR; if no such handler exists,
|
||||
the call has no effect.
|
||||
.PP
|
||||
Channel handlers are invoked via the Tcl event mechanism, so they
|
||||
are only useful in applications that are event-driven.
|
||||
Note also that the conditions specified in the \fImask\fR argument
|
||||
to \fIproc\fR may no longer exist when \fIproc\fR is invoked: for
|
||||
example, if there are two handlers for \fBTCL_READABLE\fR on the same
|
||||
channel, the first handler could consume all of the available input
|
||||
so that the channel is no longer readable when the second handler
|
||||
is invoked.
|
||||
For this reason it may be useful to use nonblocking I/O on channels
|
||||
for which there are event handlers.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Notifier(3), Tcl_CreateChannel(3), Tcl_OpenFileChannel(3), vwait(n).
|
||||
|
||||
.SH KEYWORDS
|
||||
blocking, callback, channel, events, handler, nonblocking.
|
||||
@@ -1,59 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtCloseHdlr.3 1.7 96/04/15 13:08:19
|
||||
.so man.macros
|
||||
.TH Tcl_CreateCloseHandler 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_CreateCloseHandler, Tcl_DeleteCloseHandler \- arrange for callbacks when channels are closed
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
void
|
||||
\fBTcl_CreateCloseHandler\fR(\fIchannel, proc, clientData\fR)
|
||||
.sp
|
||||
void
|
||||
\fBTcl_DeleteCloseHandler\fR(\fIchannel, proc, clientData\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_CloseProc callbackData in
|
||||
.AP Tcl_Channel channel in
|
||||
The channel for which to create or delete a close callback.
|
||||
.AP Tcl_CloseProc *proc in
|
||||
The procedure to call as the callback.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateCloseHandler\fR arranges for \fIproc\fR to be called when
|
||||
\fIchannel\fR is closed with \fBTcl_Close\fR or
|
||||
\fBTcl_UnregisterChannel\fR, or using the Tcl \fBclose\fR command.
|
||||
\fIProc\fR should match the following prototype:
|
||||
.PP
|
||||
.CS
|
||||
typedef void Tcl_CloseProc(
|
||||
ClientData \fIclientData\fR);
|
||||
.CE
|
||||
.PP
|
||||
The \fIclientData\fR is the same as the value provided in the call to
|
||||
\fBTcl_CreateCloseHandler\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteCloseHandler\fR removes a close callback for \fIchannel\fR.
|
||||
The \fIproc\fR and \fIclientData\fR identify which close callback to
|
||||
remove; \fBTcl_DeleteCloseHandler\fR does nothing if its \fIproc\fR and
|
||||
\fIclientData\fR arguments do not match the \fIproc\fR and \fIclientData\fR
|
||||
for a close handler for \fIchannel\fR.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
close(n), Tcl_Close(3), Tcl_UnregisterChannel(3)
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, channel closing
|
||||
@@ -1,138 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtCommand.3 1.29 97/06/04 17:23:53
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateCommand 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateCommand \- implement new commands in C
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Command
|
||||
\fBTcl_CreateCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_CmdDeleteProc **deleteProcPtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to create new command.
|
||||
.AP char *cmdName in
|
||||
Name of command.
|
||||
.AP Tcl_CmdProc *proc in
|
||||
Implementation of new command: \fIproc\fR will be called whenever
|
||||
\fIcmdName\fR is invoked as a command.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
|
||||
.AP Tcl_CmdDeleteProc *deleteProc in
|
||||
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
|
||||
allows for command-specific cleanup. If NULL, then no procedure is
|
||||
called before the command is deleted.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateCommand\fR defines a new command in \fIinterp\fR and associates
|
||||
it with procedure \fIproc\fR such that whenever \fIcmdName\fR is
|
||||
invoked as a Tcl command (via a call to \fBTcl_Eval\fR) the Tcl interpreter
|
||||
will call \fIproc\fR to process the command.
|
||||
It differs from \fBTcl_CreateObjCommand\fR in that a new string-based
|
||||
command is defined;
|
||||
that is, a command procedure is defined that takes an array of
|
||||
argument strings instead of objects.
|
||||
The object-based command procedures registered by \fBTcl_CreateObjCommand\fR
|
||||
can execute significantly faster than the string-based command procedures
|
||||
defined by \fBTcl_CreateCommand\fR.
|
||||
This is because they take Tcl objects as arguments
|
||||
and those objects can retain an internal representation that
|
||||
can be manipulated more efficiently.
|
||||
Also, Tcl's interpreter now uses objects internally.
|
||||
In order to invoke a string-based command procedure
|
||||
registered by \fBTcl_CreateCommand\fR,
|
||||
it must generate and fetch a string representation
|
||||
from each argument object before the call
|
||||
and create a new Tcl object to hold the string result returned by the
|
||||
string-based command procedure.
|
||||
New commands should be defined using \fBTcl_CreateObjCommand\fR.
|
||||
We support \fBTcl_CreateCommand\fR for backwards compatibility.
|
||||
.PP
|
||||
The procedures \fBTcl_DeleteCommand\fR, \fBTcl_GetCommandInfo\fR,
|
||||
and \fBTcl_SetCommandInfo\fR are used in conjunction with
|
||||
\fBTcl_CreateCommand\fR.
|
||||
.PP
|
||||
\fBTcl_CreateCommand\fR will delete an existing command \fIcmdName\fR,
|
||||
if one is already associated with the interpreter.
|
||||
It returns a token that may be used to refer
|
||||
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
|
||||
If \fIcmdName\fR contains any \fB::\fR namespace qualifiers,
|
||||
then the command is added to the specified namespace;
|
||||
otherwise the command is added to the global namespace.
|
||||
If \fBTcl_CreateCommand\fR is called for an interpreter that is in
|
||||
the process of being deleted, then it does not create a new command
|
||||
and it returns NULL.
|
||||
\fIProc\fR should have arguments and result that match the type
|
||||
\fBTcl_CmdProc\fR:
|
||||
.CS
|
||||
typedef int Tcl_CmdProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
int \fIargc\fR,
|
||||
char *\fIargv\fR[]);
|
||||
.CE
|
||||
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
|
||||
parameters will be copies of the \fIclientData\fR and \fIinterp\fR
|
||||
arguments given to \fBTcl_CreateCommand\fR.
|
||||
Typically, \fIclientData\fR points to an application-specific
|
||||
data structure that describes what to do when the command procedure
|
||||
is invoked. \fIArgc\fR and \fIargv\fR describe the arguments to
|
||||
the command, \fIargc\fR giving the number of arguments (including
|
||||
the command name) and \fIargv\fR giving the values of the arguments
|
||||
as strings. The \fIargv\fR array will contain \fIargc\fR+1 values;
|
||||
the first \fIargc\fR values point to the argument strings, and the
|
||||
last value is NULL.
|
||||
.PP
|
||||
\fIProc\fR must return an integer code that is either \fBTCL_OK\fR, \fBTCL_ERROR\fR,
|
||||
\fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR. See the Tcl overview man page
|
||||
for details on what these codes mean. Most normal commands will only
|
||||
return \fBTCL_OK\fR or \fBTCL_ERROR\fR. In addition, \fIproc\fR must set
|
||||
the interpreter result to point to a string value;
|
||||
in the case of a \fBTCL_OK\fR return code this gives the result
|
||||
of the command, and in the case of \fBTCL_ERROR\fR it gives an error message.
|
||||
The \fBTcl_SetResult\fR procedure provides an easy interface for setting
|
||||
the return value; for complete details on how the the interpreter result
|
||||
field is managed, see the \fBTcl_Interp\fR man page.
|
||||
Before invoking a command procedure,
|
||||
\fBTcl_Eval\fR sets the interpreter result to point to an empty string,
|
||||
so simple commands can return an empty result by doing nothing at all.
|
||||
.PP
|
||||
The contents of the \fIargv\fR array belong to Tcl and are not
|
||||
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
|
||||
not modify them, nor should it set the interpreter result to point
|
||||
anywhere within the \fIargv\fR values.
|
||||
Call \fBTcl_SetResult\fR with status \fBTCL_VOLATILE\fR if you want
|
||||
to return something from the \fIargv\fR array.
|
||||
.PP
|
||||
\fIDeleteProc\fR will be invoked when (if) \fIcmdName\fR is deleted.
|
||||
This can occur through a call to \fBTcl_DeleteCommand\fR or \fBTcl_DeleteInterp\fR,
|
||||
or by replacing \fIcmdName\fR in another call to \fBTcl_CreateCommand\fR.
|
||||
\fIDeleteProc\fR is invoked before the command is deleted, and gives the
|
||||
application an opportunity to release any structures associated
|
||||
with the command. \fIDeleteProc\fR should have arguments and
|
||||
result that match the type \fBTcl_CmdDeleteProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||||
argument passed to \fBTcl_CreateCommand\fR.
|
||||
.PP
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName, Tcl_SetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
bind, command, create, delete, interpreter, namespace
|
||||
@@ -1,100 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtFileHdlr.3 1.7 97/04/23 16:11:17
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateFileHandler 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateFileHandler, Tcl_DeleteFileHandler \- associate procedure callbacks with files or devices (Unix only)
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.VS
|
||||
.sp
|
||||
\fBTcl_CreateFileHandler\fR(\fIfd, mask, proc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteFileHandler\fR(\fIfd\fR)
|
||||
.VE
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_FileProc clientData
|
||||
.VS
|
||||
.AP int fd in
|
||||
Unix file descriptor for an open file or device.
|
||||
.VE
|
||||
.AP int mask in
|
||||
Conditions under which \fIproc\fR should be called:
|
||||
OR-ed combination of \fBTCL_READABLE\fR, \fBTCL_WRITABLE\fR,
|
||||
and \fBTCL_EXCEPTION\fR. May be set to 0 to temporarily disable
|
||||
a handler.
|
||||
.AP Tcl_FileProc *proc in
|
||||
Procedure to invoke whenever the file or device indicated
|
||||
by \fIfile\fR meets the conditions specified by \fImask\fR.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_CreateFileHandler\fR arranges for \fIproc\fR to be
|
||||
invoked in the future whenever I/O becomes possible on a file
|
||||
or an exceptional condition exists for the file. The file
|
||||
is indicated by \fIfd\fR, and the conditions of interest
|
||||
.VE
|
||||
are indicated by \fImask\fR. For example, if \fImask\fR
|
||||
is \fBTCL_READABLE\fR, \fIproc\fR will be called when
|
||||
the file is readable.
|
||||
The callback to \fIproc\fR is made by \fBTcl_DoOneEvent\fR, so
|
||||
\fBTcl_CreateFileHandler\fR is only useful in programs that dispatch
|
||||
events through \fBTcl_DoOneEvent\fR or through Tcl commands such
|
||||
as \fBvwait\fR.
|
||||
.PP
|
||||
\fIProc\fR should have arguments and result that match the
|
||||
type \fBTcl_FileProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_FileProc(
|
||||
ClientData \fIclientData\fR,
|
||||
int \fImask\fR);
|
||||
.CE
|
||||
The \fIclientData\fR parameter to \fIproc\fR is a copy
|
||||
of the \fIclientData\fR
|
||||
argument given to \fBTcl_CreateFileHandler\fR when the callback
|
||||
was created. Typically, \fIclientData\fR points to a data
|
||||
structure containing application-specific information about
|
||||
the file. \fIMask\fR is an integer mask indicating which
|
||||
of the requested conditions actually exists for the file; it
|
||||
will contain a subset of the bits in the \fImask\fR argument
|
||||
to \fBTcl_CreateFileHandler\fR.
|
||||
.PP
|
||||
.PP
|
||||
There may exist only one handler for a given file at a given time.
|
||||
If \fBTcl_CreateFileHandler\fR is called when a handler already
|
||||
exists for \fIfd\fR, then the new callback replaces the information
|
||||
that was previously recorded.
|
||||
.PP
|
||||
\fBTcl_DeleteFileHandler\fR may be called to delete the
|
||||
file handler for \fIfd\fR; if no handler exists for the
|
||||
file given by \fIfd\fR then the procedure has no effect.
|
||||
.PP
|
||||
The purpose of file handlers is to enable an application to respond to
|
||||
events while waiting for files to become ready for I/O. For this to work
|
||||
correctly, the application may need to use non-blocking I/O operations on
|
||||
the files for which handlers are declared. Otherwise the application may
|
||||
block if it reads or writes too much data; while waiting for the I/O to
|
||||
complete the application won't be able to service other events. Use
|
||||
\fBTcl_SetChannelOption\fR with \fB\-blocking\fR to set the channel into
|
||||
blocking or nonblocking mode as required.
|
||||
.PP
|
||||
.VS
|
||||
Note that these interfaces are only supported by the Unix
|
||||
implementation of the Tcl notifier.
|
||||
.VE
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, file, handler
|
||||
@@ -1,131 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtInterp.3 1.17 97/10/31 13:05:51
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Interp *
|
||||
\fBTcl_CreateInterp\fR()
|
||||
.sp
|
||||
\fBTcl_DeleteInterp\fR(\fIinterp\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_InterpDeleted\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
Token for interpreter to be destroyed.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
|
||||
a token for it. The token is required in calls to most other Tcl
|
||||
procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
|
||||
\fBTcl_DeleteInterp\fR.
|
||||
Clients are only allowed to access a few of the fields of
|
||||
Tcl_Interp structures; see the Tcl_Interp
|
||||
and \fBTcl_CreateCommand\fR man pages for details.
|
||||
The new interpreter is initialized with no defined variables and only
|
||||
the built-in Tcl commands. To bind in additional commands, call
|
||||
\fBTcl_CreateCommand\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
|
||||
will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
|
||||
been matched by calls to \fBTcl_Release\fR. At that time, all of the
|
||||
resources associated with it, including variables, procedures, and
|
||||
application-specific command bindings, will be deleted. After
|
||||
\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
|
||||
interpreter will fail and return \fBTCL_ERROR\fR. After the call to
|
||||
\fBTcl_DeleteInterp\fR it is safe to examine \fIinterp->result\fR, query or
|
||||
set the values of variables, define, undefine or retrieve procedures, and
|
||||
examine the runtime evaluation stack. See below, in the section
|
||||
\fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
|
||||
.PP
|
||||
\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
|
||||
called with \fIinterp\fR as its argument; this indicates that the
|
||||
interpreter will eventually be deleted, when the last call to
|
||||
\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
|
||||
nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
|
||||
will return \fBTCL_ERROR\fR.
|
||||
.PP
|
||||
\fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish
|
||||
between when only the memory the callback is responsible for is being
|
||||
deleted and when the whole interpreter is being deleted. In the former case
|
||||
the callback may recreate the data being deleted, but this would lead to an
|
||||
infinite loop if the interpreter were being deleted.
|
||||
|
||||
.SH "INTERPRETERS AND MEMORY MANAGEMENT"
|
||||
.PP
|
||||
\fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
|
||||
be used by nested evaluations and C code in various extensions. Tcl
|
||||
implements a simple mechanism that allows callers to use interpreters
|
||||
without worrying about the interpreter being deleted in a nested call, and
|
||||
without requiring special code to protect the interpreter, in most cases.
|
||||
This mechanism ensures that nested uses of an interpreter can safely
|
||||
continue using it even after \fBTcl_DeleteInterp\fR is called.
|
||||
.PP
|
||||
The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
|
||||
to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
|
||||
the last call to \fBTcl_Preserve\fR is matched by a call to
|
||||
\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
|
||||
\fBTcl_Preserve\fR for a description of these functions.
|
||||
.PP
|
||||
The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
|
||||
and \fBTcl_Release\fR are simple:
|
||||
.TP
|
||||
Interpreters Passed As Arguments
|
||||
Functions that are passed an interpreter as an argument can safely use the
|
||||
interpreter without any special protection. Thus, when you write an
|
||||
extension consisting of new Tcl commands, no special code is needed to
|
||||
protect interpreters received as arguments. This covers the majority of all
|
||||
uses.
|
||||
.TP
|
||||
Interpreter Creation And Deletion
|
||||
When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
|
||||
\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
|
||||
\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
|
||||
\fBTcl_Release\fR should be wrapped around all uses of the interpreter.
|
||||
Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
|
||||
has been called. To ensure that the interpreter is properly deleted when
|
||||
it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
|
||||
code already called \fBTcl_DeleteInterp\fR; if not, call
|
||||
\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
|
||||
Do not call \fBTcl_DeleteInterp\fR on an interpreter for which
|
||||
\fBTcl_InterpDeleted\fR returns nonzero.
|
||||
.TP
|
||||
Retrieving An Interpreter From A Data Structure
|
||||
When an interpreter is retrieved from a data structure (e.g. the client
|
||||
data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR,
|
||||
\fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of
|
||||
calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
|
||||
all uses of the interpreter; it is unsafe to reuse the interpreter once
|
||||
\fBTcl_Release\fR has been called. If an interpreter is stored inside a
|
||||
callback data structure, an appropriate deletion cleanup mechanism should
|
||||
be set up by the code that creates the data structure so that the
|
||||
interpreter is removed from the data structure (e.g. by setting the field
|
||||
to NULL) when the interpreter is deleted. Otherwise, you may be using an
|
||||
interpreter that has been freed and whose memory may already have been
|
||||
reused.
|
||||
.PP
|
||||
All uses of interpreters in Tcl and Tk have already been protected.
|
||||
Extension writers should ensure that their code also properly protects any
|
||||
additional interpreters used, as described above.
|
||||
|
||||
.SH KEYWORDS
|
||||
command, create, delete, interpreter
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_Preserve(3), Tcl_Release(3)
|
||||
@@ -1,93 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtMathFnc.3 1.9 96/08/26 12:59:43
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateMathFunc 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateMathFunc \- Define a new math function for expressions
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_CreateMathFunc\fR(\fIinterp, name, numArgs, argTypes, proc, clientData\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ValueType clientData
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which new function will be defined.
|
||||
.AP char *name in
|
||||
Name for new function.
|
||||
.AP int numArgs in
|
||||
Number of arguments to new function; also gives size of \fIargTypes\fR array.
|
||||
.AP Tcl_ValueType *argTypes in
|
||||
Points to an array giving the permissible types for each argument to
|
||||
function.
|
||||
.AP Tcl_MathProc *proc in
|
||||
Procedure that implements the function.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR when it is invoked.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Tcl allows a number of mathematical functions to be used in
|
||||
expressions, such as \fBsin\fR, \fBcos\fR, and \fBhypot\fR.
|
||||
\fBTcl_CreateMathFunc\fR allows applications to add additional functions
|
||||
to those already provided by Tcl or to replace existing functions.
|
||||
\fIName\fR is the name of the function as it will appear in expressions.
|
||||
If \fIname\fR doesn't already exist as a function then a new function
|
||||
is created. If it does exist, then the existing function is replaced.
|
||||
\fINumArgs\fR and \fIargTypes\fR describe the arguments to the function.
|
||||
Each entry in the \fIargTypes\fR array must be either TCL_INT, TCL_DOUBLE,
|
||||
or TCL_EITHER to indicate whether the corresponding argument must be an
|
||||
integer, a double-precision floating value, or either, respectively.
|
||||
.PP
|
||||
Whenever the function is invoked in an expression Tcl will invoke
|
||||
\fIproc\fR. \fIProc\fR should have arguments and result that match
|
||||
the type \fBTcl_MathProc\fR:
|
||||
.CS
|
||||
typedef int Tcl_MathProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
Tcl_Value *\fIargs\fR,
|
||||
Tcl_Value *\fIresultPtr\fR);
|
||||
.CE
|
||||
.PP
|
||||
When \fIproc\fR is invoked the \fIclientData\fR and \fIinterp\fR
|
||||
arguments will be the same as those passed to \fBTcl_CreateMathFunc\fR.
|
||||
\fIArgs\fR will point to an array of \fInumArgs\fR Tcl_Value structures,
|
||||
which describe the actual arguments to the function:
|
||||
.CS
|
||||
typedef struct Tcl_Value {
|
||||
Tcl_ValueType \fItype\fR;
|
||||
long \fIintValue\fR;
|
||||
double \fIdoubleValue\fR;
|
||||
} Tcl_Value;
|
||||
.CE
|
||||
.PP
|
||||
The \fItype\fR field indicates the type of the argument and is
|
||||
either TCL_INT or TCL_DOUBLE.
|
||||
It will match the \fIargTypes\fR value specified for the function unless
|
||||
the \fIargTypes\fR value was TCL_EITHER. Tcl converts
|
||||
the argument supplied in the expression to the type requested in
|
||||
\fIargTypes\fR, if that is necessary.
|
||||
Depending on the value of the \fItype\fR field, the \fIintValue\fR
|
||||
or \fIdoubleValue\fR field will contain the actual value of the argument.
|
||||
.PP
|
||||
\fIProc\fR should compute its result and store it either as an integer
|
||||
in \fIresultPtr->intValue\fR or as a floating value in
|
||||
\fIresultPtr->doubleValue\fR.
|
||||
It should set also \fIresultPtr->type\fR to either TCL_INT or TCL_DOUBLE
|
||||
to indicate which value was set.
|
||||
Under normal circumstances \fIproc\fR should return TCL_OK.
|
||||
If an error occurs while executing the function, \fIproc\fR should
|
||||
return TCL_ERROR and leave an error message in \fIinterp->result\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
expression, mathematical function
|
||||
@@ -1,248 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) CrtObjCmd.3 1.10 97/07/31 14:10:38
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateObjCommand 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateObjCommand, Tcl_DeleteCommand, Tcl_DeleteCommandFromToken, Tcl_GetCommandInfo, Tcl_SetCommandInfo, Tcl_GetCommandName \- implement new commands in C
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Command
|
||||
\fBTcl_CreateObjCommand\fR(\fIinterp, cmdName, proc, clientData, deleteProc\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_DeleteCommand\fR(\fIinterp, cmdName\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_DeleteCommandFromToken\fR(\fIinterp, token\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_SetCommandInfo\fR(\fIinterp, cmdName, infoPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetCommandName\fR(\fIinterp, token\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ObjCmdProc *deleteProc in/out
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to create a new command or that contains a command.
|
||||
.AP char *cmdName in
|
||||
Name of command.
|
||||
.AP Tcl_ObjCmdProc *proc in
|
||||
Implementation of the new command: \fIproc\fR will be called whenever
|
||||
\fIcmdName\fR is invoked as a command.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR and \fIdeleteProc\fR.
|
||||
.AP Tcl_CmdDeleteProc *deleteProc in
|
||||
Procedure to call before \fIcmdName\fR is deleted from the interpreter;
|
||||
allows for command-specific cleanup. If NULL, then no procedure is
|
||||
called before the command is deleted.
|
||||
.AP Tcl_Command token in
|
||||
Token for command, returned by previous call to \fBTcl_CreateObjCommand\fR.
|
||||
The command must not have been deleted.
|
||||
.AP Tcl_CmdInfo *infoPtr in/out
|
||||
Pointer to structure containing various information about a
|
||||
Tcl command.
|
||||
.BE
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateObjCommand\fR defines a new command in \fIinterp\fR
|
||||
and associates it with procedure \fIproc\fR
|
||||
such that whenever \fIname\fR is
|
||||
invoked as a Tcl command (e.g., via a call to \fBTcl_EvalObj\fR)
|
||||
the Tcl interpreter will call \fIproc\fR to process the command.
|
||||
.PP
|
||||
\fBTcl_CreateObjCommand\fR will delete any command \fIname\fR
|
||||
already associated with the interpreter.
|
||||
It returns a token that may be used to refer
|
||||
to the command in subsequent calls to \fBTcl_GetCommandName\fR.
|
||||
If \fIname\fR contains any \fB::\fR namespace qualifiers,
|
||||
then the command is added to the specified namespace;
|
||||
otherwise the command is added to the global namespace.
|
||||
If \fBTcl_CreateObjCommand\fR is called for an interpreter that is in
|
||||
the process of being deleted, then it does not create a new command
|
||||
and it returns NULL.
|
||||
\fIproc\fR should have arguments and result that match the type
|
||||
\fBTcl_ObjCmdProc\fR:
|
||||
.CS
|
||||
typedef int Tcl_ObjCmdProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
int \fIobjc\fR,
|
||||
.VS
|
||||
Tcl_Obj *CONST \fIobjv\fR[]);
|
||||
.CE
|
||||
When \fIproc\fR is invoked, the \fIclientData\fR and \fIinterp\fR parameters
|
||||
will be copies of the \fIclientData\fR and \fIinterp\fR arguments given to
|
||||
\fBTcl_CreateObjCommand\fR. Typically, \fIclientData\fR points to an
|
||||
application-specific data structure that describes what to do when the
|
||||
command procedure is invoked. \fIObjc\fR and \fIobjv\fR describe the
|
||||
arguments to the command, \fIobjc\fR giving the number of argument objects
|
||||
(including the command name) and \fIobjv\fR giving the values of the
|
||||
arguments. The \fIobjv\fR array will contain \fIobjc\fR values, pointing to
|
||||
the argument objects. Unlike \fIargv\fR[\fIargv\fR] used in a
|
||||
string-based command procedure, \fIobjv\fR[\fIobjc\fR] will not contain NULL.
|
||||
.PP
|
||||
Additionally, when \fIproc\fR is invoked, it must not modify the contents
|
||||
of the \fIobjv\fR array by assigning new pointer values to any element of the
|
||||
array (for example, \fIobjv\fR[\fB2\fR] = \fBNULL\fR) because this will
|
||||
cause memory to be lost and the runtime stack to be corrupted. The
|
||||
\fBCONST\fR in the declaration of \fIobjv\fR will cause ANSI-compliant
|
||||
compilers to report any such attempted assignment as an error. However,
|
||||
it is acceptable to modify the internal representation of any individual
|
||||
object argument. For instance, the user may call
|
||||
\fBTcl_GetIntFromObject\fR on \fIobjv\fR[\fB2\fR] to obtain the integer
|
||||
representation of that object; that call may change the type of the object
|
||||
that \fIobjv\fR[\fB2\fR] points at, but will not change where
|
||||
\fIobjv\fR[\fB2\fR] points.
|
||||
.VE
|
||||
.PP
|
||||
\fIproc\fR must return an integer code that is either \fBTCL_OK\fR,
|
||||
\fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR.
|
||||
See the Tcl overview man page
|
||||
for details on what these codes mean. Most normal commands will only
|
||||
return \fBTCL_OK\fR or \fBTCL_ERROR\fR.
|
||||
In addition, if \fIproc\fR needs to return a non-empty result,
|
||||
it can call \fBTcl_SetObjResult\fR to set the interpreter's result.
|
||||
In the case of a \fBTCL_OK\fR return code this gives the result
|
||||
of the command,
|
||||
and in the case of \fBTCL_ERROR\fR this gives an error message.
|
||||
Before invoking a command procedure,
|
||||
\fBTcl_EvalObj\fR sets interpreter's result to
|
||||
point to an object representing an empty string, so simple
|
||||
commands can return an empty result by doing nothing at all.
|
||||
.PP
|
||||
The contents of the \fIobjv\fR array belong to Tcl and are not
|
||||
guaranteed to persist once \fIproc\fR returns: \fIproc\fR should
|
||||
not modify them.
|
||||
Call \fBTcl_SetObjResult\fR if you want
|
||||
to return something from the \fIobjv\fR array.
|
||||
.PP
|
||||
\fIDeleteProc\fR will be invoked when (if) \fIname\fR is deleted.
|
||||
This can occur through a call to \fBTcl_DeleteCommand\fR,
|
||||
\fBTcl_DeleteCommandFromToken\fR, or \fBTcl_DeleteInterp\fR,
|
||||
or by replacing \fIname\fR in another call to \fBTcl_CreateObjCommand\fR.
|
||||
\fIDeleteProc\fR is invoked before the command is deleted, and gives the
|
||||
application an opportunity to release any structures associated
|
||||
with the command. \fIDeleteProc\fR should have arguments and
|
||||
result that match the type \fBTcl_CmdDeleteProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_CmdDeleteProc(ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||||
argument passed to \fBTcl_CreateObjCommand\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteCommand\fR deletes a command from a command interpreter.
|
||||
Once the call completes, attempts to invoke \fIcmdName\fR in
|
||||
\fIinterp\fR will result in errors.
|
||||
If \fIcmdName\fR isn't bound as a command in \fIinterp\fR then
|
||||
\fBTcl_DeleteCommand\fR does nothing and returns -1; otherwise
|
||||
it returns 0.
|
||||
There are no restrictions on \fIcmdName\fR: it may refer to
|
||||
a built-in command, an application-specific command, or a Tcl procedure.
|
||||
If \fIname\fR contains any \fB::\fR namespace qualifiers,
|
||||
the command is deleted from the specified namespace.
|
||||
.PP
|
||||
Given a token returned by \fBTcl_CreateObjCommand\fR,
|
||||
\fBTcl_DeleteCommandFromToken\fR deletes the command
|
||||
from a command interpreter.
|
||||
It will delete a command even if that command has been renamed.
|
||||
Once the call completes, attempts to invoke the command in
|
||||
\fIinterp\fR will result in errors.
|
||||
If the command corresponding to \fItoken\fR
|
||||
has already been deleted from \fIinterp\fR then
|
||||
\fBTcl_DeleteCommand\fR does nothing and returns -1;
|
||||
otherwise it returns 0.
|
||||
.PP
|
||||
\fBTcl_GetCommandInfo\fR checks to see whether its \fIcmdName\fR argument
|
||||
exists as a command in \fIinterp\fR.
|
||||
\fIcmdName\fR may include \fB::\fR namespace qualifiers
|
||||
to identify a command in a particular namespace.
|
||||
If the command is not found, then it returns 0.
|
||||
Otherwise it places information about the command
|
||||
in the \fBTcl_CmdInfo\fR structure
|
||||
pointed to by \fIinfoPtr\fR and returns 1.
|
||||
A \fBTcl_CmdInfo\fR structure has the following fields:
|
||||
.CS
|
||||
typedef struct Tcl_CmdInfo {
|
||||
int isNativeObjectProc;
|
||||
Tcl_ObjCmdProc *objProc;
|
||||
ClientData objClientData;
|
||||
Tcl_CmdProc *proc;
|
||||
ClientData clientData;
|
||||
Tcl_CmdDeleteProc *deleteProc;
|
||||
ClientData deleteData;
|
||||
Tcl_Namespace *namespacePtr;
|
||||
} Tcl_CmdInfo;
|
||||
.CE
|
||||
The \fIisNativeObjectProc\fR field has the value 1
|
||||
if \fBTcl_CreateObjCommand\fR was called to register the command;
|
||||
it is 0 if only \fBTcl_CreateCommand\fR was called.
|
||||
It allows a program to determine whether it is faster to
|
||||
call \fIobjProc\fR or \fIproc\fR:
|
||||
\fIobjProc\fR is normally faster
|
||||
if \fIisNativeObjectProc\fR has the value 1.
|
||||
The fields \fIobjProc\fR and \fIobjClientData\fR
|
||||
have the same meaning as the \fIproc\fR and \fIclientData\fR
|
||||
arguments to \fBTcl_CreateObjCommand\fR;
|
||||
they hold information about the object-based command procedure
|
||||
that the Tcl interpreter calls to implement the command.
|
||||
The fields \fIproc\fR and \fIclientData\fR
|
||||
hold information about the string-based command procedure
|
||||
that implements the command.
|
||||
If \fBTcl_CreateCommand\fR was called for this command,
|
||||
this is the procedure passed to it;
|
||||
otherwise, this is a compatibility procedure
|
||||
registered by \fBTcl_CreateObjCommand\fR
|
||||
that simply calls the command's
|
||||
object-based procedure after converting its string arguments to Tcl objects.
|
||||
The field \fIdeleteData\fR is the ClientData value
|
||||
to pass to \fIdeleteProc\fR; it is normally the same as
|
||||
\fIclientData\fR but may be set independently using the
|
||||
\fBTcl_SetCommandInfo\fR procedure.
|
||||
The field \fInamespacePtr\fR holds a pointer to the
|
||||
Tcl_Namespace that contains the command.
|
||||
.PP
|
||||
\fBTcl_SetCommandInfo\fR is used to modify the procedures and
|
||||
ClientData values associated with a command.
|
||||
Its \fIcmdName\fR argument is the name of a command in \fIinterp\fR.
|
||||
\fIcmdName\fR may include \fB::\fR namespace qualifiers
|
||||
to identify a command in a particular namespace.
|
||||
If this command does not exist then \fBTcl_SetCommandInfo\fR returns 0.
|
||||
Otherwise, it copies the information from \fI*infoPtr\fR to
|
||||
Tcl's internal structure for the command and returns 1.
|
||||
Note that this procedure allows the ClientData for a command's
|
||||
deletion procedure to be given a different value than the ClientData
|
||||
for its command procedure.
|
||||
Note that \fBTcl_SetCmdInfo\fR will not change a command's namespace;
|
||||
you must use \fBTcl_RenameCommand\fR to do that.
|
||||
.PP
|
||||
\fBTcl_GetCommandName\fR provides a mechanism for tracking commands
|
||||
that have been renamed.
|
||||
Given a token returned by \fBTcl_CreateObjCommand\fR
|
||||
when the command was created, \fBTcl_GetCommandName\fR returns the
|
||||
string name of the command. If the command has been renamed since it
|
||||
was created, then \fBTcl_GetCommandName\fR returns the current name.
|
||||
This name does not include any \fB::\fR namespace qualifiers.
|
||||
The command corresponding to \fItoken\fR must not have been deleted.
|
||||
The string returned by \fBTcl_GetCommandName\fR is in dynamic memory
|
||||
owned by Tcl and is only guaranteed to retain its value as long as the
|
||||
command isn't deleted or renamed; callers should copy the string if
|
||||
they need to keep it for a long time.
|
||||
.PP
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_CreateCommand, Tcl_ResetResult, Tcl_SetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
bind, command, create, delete, namespace, object
|
||||
@@ -1,230 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtSlave.3 1.26 97/07/31 18:00:14
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateSlave 3 7.6 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_IsSafe, Tcl_MakeSafe, Tcl_CreateSlave, Tcl_GetSlave, Tcl_GetMaster, Tcl_GetInterpPath, Tcl_CreateAlias, Tcl_CreateAliasObj, Tcl_GetAlias, Tcl_GetAliasObj, Tcl_ExposeCommand, Tcl_HideCommand \- manage multiple Tcl interpreters, aliases and hidden commands.
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_IsSafe\fR(\fIinterp\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_MakeSafe\fR(\fIinterp\fR)
|
||||
.sp
|
||||
Tcl_Interp *
|
||||
\fBTcl_CreateSlave\fR(\fIinterp, slaveName, isSafe\fR)
|
||||
.sp
|
||||
Tcl_Interp *
|
||||
\fBTcl_GetSlave\fR(\fIinterp, slaveName\fR)
|
||||
.sp
|
||||
Tcl_Interp *
|
||||
\fBTcl_GetMaster\fR(\fIinterp\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetInterpPath\fR(\fIaskingInterp, slaveInterp\fR)
|
||||
.sp
|
||||
.VS
|
||||
int
|
||||
\fBTcl_CreateAlias\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, argc, argv\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_CreateAliasObj\fR(\fIslaveInterp, srcCmd, targetInterp, targetCmd, objc, objv\fR)
|
||||
.VE
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetAlias\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, argcPtr, argvPtr\fR)
|
||||
.sp
|
||||
.VS
|
||||
int
|
||||
\fBTcl_GetAliasObj\fR(\fIinterp, srcCmd, targetInterpPtr, targetCmdPtr, objcPtr, objvPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExposeCommand\fR(\fIinterp, hiddenCmdName, cmdName\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_HideCommand\fR(\fIinterp, cmdName, hiddenCmdName\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_InterpDeleteProc **hiddenCmdName
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to execute the specified command.
|
||||
.AP char *slaveName in
|
||||
Name of slave interpreter to create or manipulate.
|
||||
.AP int isSafe in
|
||||
If non-zero, a ``safe'' slave that is suitable for running untrusted code
|
||||
is created, otherwise a trusted slave is created.
|
||||
.AP Tcl_Interp *slaveInterp in
|
||||
Interpreter to use for creating the source command for an alias (see
|
||||
below).
|
||||
.AP char *srcCmd in
|
||||
Name of source command for alias.
|
||||
.AP Tcl_Interp *targetInterp in
|
||||
Interpreter that contains the target command for an alias.
|
||||
.AP char *targetCmd in
|
||||
Name of target command for alias in \fItargetInterp\fR.
|
||||
.AP int argc in
|
||||
Count of additional arguments to pass to the alias command.
|
||||
.AP char **argv in
|
||||
Vector of strings, the additional arguments to pass to the alias command.
|
||||
This storage is owned by the caller.
|
||||
.AP int objc in
|
||||
Count of additional object arguments to pass to the alias object command.
|
||||
.AP Tcl_Object **objv in
|
||||
Vector of Tcl_Obj structures, the additional object argumenst to pass to
|
||||
the alias object command.
|
||||
This storage is owned by the caller.
|
||||
.AP Tcl_Interp **targetInterpPtr in
|
||||
Pointer to location to store the address of the interpreter where a target
|
||||
command is defined for an alias.
|
||||
.AP char **targetCmdPtr out
|
||||
Pointer to location to store the address of the name of the target command
|
||||
for an alias.
|
||||
.AP int *argcPtr out
|
||||
Pointer to location to store count of additional arguments to be passed to
|
||||
the alias. The location is in storage owned by the caller.
|
||||
.AP char ***argvPtr out
|
||||
Pointer to location to store a vector of strings, the additional arguments
|
||||
to pass to an alias. The location is in storage owned by the caller, the
|
||||
vector of strings is owned by the called function.
|
||||
.AP int *objcPtr out
|
||||
Pointer to location to store count of additional object arguments to be
|
||||
passed to the alias. The location is in storage owned by the caller.
|
||||
.AP Tcl_Obj ***objvPtr out
|
||||
Pointer to location to store a vector of Tcl_Obj structures, the additional
|
||||
arguments to pass to an object alias command. The location is in storage
|
||||
owned by the caller, the vector of Tcl_Obj structures is owned by the
|
||||
called function.
|
||||
.VS
|
||||
.AP char *cmdName in
|
||||
Name of an exposed command to hide or create.
|
||||
.AP char *hiddenCmdName in
|
||||
Name under which a hidden command is stored and with which it can be
|
||||
exposed or invoked.
|
||||
.VE
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures are intended for access to the multiple interpreter
|
||||
facility from inside C programs. They enable managing multiple interpreters
|
||||
in a hierarchical relationship, and the management of aliases, commands
|
||||
that when invoked in one interpreter execute a command in another
|
||||
interpreter. The return value for those procedures that return an \fBint\fR
|
||||
is either \fBTCL_OK\fR or \fBTCL_ERROR\fR. If \fBTCL_ERROR\fR is returned
|
||||
then the \fBresult\fR field of the interpreter contains an error message.
|
||||
.PP
|
||||
\fBTcl_CreateSlave\fR creates a new interpreter as a slave of \fIinterp\fR.
|
||||
It also creates a slave command named \fIslaveName\fR in \fIinterp\fR which
|
||||
allows \fIinterp\fR to manipulate the new slave.
|
||||
If \fIisSafe\fR is zero, the command creates a trusted slave in which Tcl
|
||||
code has access to all the Tcl commands.
|
||||
If it is \fB1\fR, the command creates a ``safe'' slave in which Tcl code
|
||||
has access only to set of Tcl commands defined as ``Safe Tcl''; see the
|
||||
manual entry for the Tcl \fBinterp\fR command for details.
|
||||
If the creation of the new slave interpreter failed, \fBNULL\fR is returned.
|
||||
.PP
|
||||
\fBTcl_IsSafe\fR returns \fB1\fR if \fIinterp\fR is ``safe'' (was created
|
||||
with the \fBTCL_SAFE_INTERPRETER\fR flag specified),
|
||||
\fB0\fR otherwise.
|
||||
.PP
|
||||
\fBTcl_MakeSafe\fR makes \fIinterp\fR ``safe'' by removing all
|
||||
non-core and core unsafe functionality. Note that if you call this after
|
||||
adding some extension to an interpreter, all traces of that extension will
|
||||
be removed from the interpreter.
|
||||
.PP
|
||||
\fBTcl_GetSlave\fR returns a pointer to a slave interpreter of
|
||||
\fIinterp\fR. The slave interpreter is identified by \fIslaveName\fR.
|
||||
If no such slave interpreter exists, \fBNULL\fR is returned.
|
||||
.PP
|
||||
\fBTcl_GetMaster\fR returns a pointer to the master interpreter of
|
||||
\fIinterp\fR. If \fIinterp\fR has no master (it is a
|
||||
top-level interpreter) then \fBNULL\fR is returned.
|
||||
.PP
|
||||
\fBTcl_GetInterpPath\fR sets the \fIresult\fR field in \fIaskingInterp\fR
|
||||
to the relative path between \fIaskingInterp\fR and \fIslaveInterp\fR;
|
||||
\fIslaveInterp\fR must be a slave of \fIaskingInterp\fR. If the computation
|
||||
of the relative path succeeds, \fBTCL_OK\fR is returned, else
|
||||
\fBTCL_ERROR\fR is returned and the \fIresult\fR field in
|
||||
\fIaskingInterp\fR contains the error message.
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_CreateAlias\fR creates an object command named \fIsrcCmd\fR in
|
||||
\fIslaveInterp\fR that when invoked, will cause the command \fItargetCmd\fR
|
||||
to be invoked in \fItargetInterp\fR. The arguments specified by the strings
|
||||
contained in \fIargv\fR are always prepended to any arguments supplied in the
|
||||
invocation of \fIsrcCmd\fR and passed to \fItargetCmd\fR.
|
||||
This operation returns \fBTCL_OK\fR if it succeeds, or \fBTCL_ERROR\fR if
|
||||
it fails; in that case, an error message is left in the object result
|
||||
of \fIslaveInterp\fR.
|
||||
Note that there are no restrictions on the ancestry relationship (as
|
||||
created by \fBTcl_CreateSlave\fR) between \fIslaveInterp\fR and
|
||||
\fItargetInterp\fR. Any two interpreters can be used, without any
|
||||
restrictions on how they are related.
|
||||
.PP
|
||||
\fBTcl_CreateAliasObj\fR is similar to \fBTcl_CreateAliasObj\fR except
|
||||
that it takes a vector of objects to pass as additional arguments instead
|
||||
of a vector of strings.
|
||||
.VE
|
||||
.PP
|
||||
\fBTcl_GetAlias\fR returns information about an alias \fIaliasName\fR
|
||||
in \fIinterp\fR. Any of the result fields can be \fBNULL\fR, in
|
||||
which case the corresponding datum is not returned. If a result field is
|
||||
non\-\fBNULL\fR, the address indicated is set to the corresponding datum.
|
||||
For example, if \fItargetNamePtr\fR is non\-\fBNULL\fR it is set to a
|
||||
pointer to the string containing the name of the target command.
|
||||
.VS
|
||||
.PP
|
||||
\fBTcl_GetAliasObj\fR is similar to \fBTcl_GetAlias\fR except that it
|
||||
returns a pointer to a vector of Tcl_Obj structures instead of a vector of
|
||||
strings.
|
||||
.PP
|
||||
\fBTcl_ExposeCommand\fR moves the command named \fIhiddenCmdName\fR from
|
||||
the set of hidden commands to the set of exposed commands, putting
|
||||
it under the name
|
||||
\fIcmdName\fR.
|
||||
\fIHiddenCmdName\fR must be the name of an existing hidden
|
||||
command, or the operation will return \fBTCL_ERROR\fR and leave an error
|
||||
message in the \fIresult\fR field in \fIinterp\fR.
|
||||
If an exposed command named \fIcmdName\fR already exists,
|
||||
the operation returns \fBTCL_ERROR\fR and leaves an error message in the
|
||||
object result of \fIinterp\fR.
|
||||
If the operation succeeds, it returns \fBTCL_OK\fR.
|
||||
After executing this command, attempts to use \fIcmdName\fR in a call to
|
||||
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will again succeed.
|
||||
.PP
|
||||
\fBTcl_HideCommand\fR moves the command named \fIcmdName\fR from the set of
|
||||
exposed commands to the set of hidden commands, under the name
|
||||
\fIhiddenCmdName\fR.
|
||||
\fICmdName\fR must be the name of an existing exposed
|
||||
command, or the operation will return \fBTCL_ERROR\fR and leave an error
|
||||
message in the object result of \fIinterp\fR.
|
||||
Currently both \fIcmdName\fR and \fIhiddenCmdName\fR must not contain
|
||||
namespace qualifiers, or the operation will return \fBTCL_ERROR\fR and
|
||||
leave an error message in the object result of \fIinterp\fR.
|
||||
The \fICmdName\fR will be looked up in the global namespace, and not
|
||||
relative to the current namespace, even if the current namespace is not the
|
||||
global one.
|
||||
If a hidden command whose name is \fIhiddenCmdName\fR already
|
||||
exists, the operation also returns \fBTCL_ERROR\fR and the \fIresult\fR
|
||||
field in \fIinterp\fR contains an error message.
|
||||
If the operation succeeds, it returns \fBTCL_OK\fR.
|
||||
After executing this command, attempts to use \fIcmdName\fR in a call to
|
||||
\fBTcl_Eval\fR or with the Tcl \fBeval\fR command will fail.
|
||||
.PP
|
||||
.SH "SEE ALSO"
|
||||
For a description of the Tcl interface to multiple interpreters, see
|
||||
\fIinterp(n)\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
alias, command, exposed commands, hidden commands, interpreter, invoke,
|
||||
master, slave,
|
||||
|
||||
@@ -1,76 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtTimerHdlr.3 1.4 96/09/17 10:54:58
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateTimerHandler 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateTimerHandler, Tcl_DeleteTimerHandler \- call a procedure at a
|
||||
given time
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_TimerToken
|
||||
\fBTcl_CreateTimerHandler\fR(\fImilliseconds, proc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteTimerHandler\fR(\fItoken\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_TimerToken milliseconds
|
||||
.AP int milliseconds in
|
||||
How many milliseconds to wait before invoking \fIproc\fR.
|
||||
.AP Tcl_TimerProc *proc in
|
||||
Procedure to invoke after \fImilliseconds\fR have elapsed.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.AP Tcl_TimerToken token in
|
||||
Token for previously-created timer handler (the return value
|
||||
from some previous call to \fBTcl_CreateTimerHandler\fR).
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateTimerHandler\fR arranges for \fIproc\fR to be
|
||||
invoked at a time \fImilliseconds\fR milliseconds in the
|
||||
future.
|
||||
The callback to \fIproc\fR will be made by \fBTcl_DoOneEvent\fR,
|
||||
so \fBTcl_CreateTimerHandler\fR is only useful in programs that
|
||||
dispatch events through \fBTcl_DoOneEvent\fR or through Tcl commands
|
||||
such as \fBvwait\fR.
|
||||
The call to \fIproc\fR may not be made at the exact time given by
|
||||
\fImilliseconds\fR: it will be made at the next opportunity
|
||||
after that time. For example, if \fBTcl_DoOneEvent\fR isn't
|
||||
called until long after the time has elapsed, or if there
|
||||
are other pending events to process before the call to
|
||||
\fIproc\fR, then the call to \fIproc\fR will be delayed.
|
||||
.PP
|
||||
\fIProc\fR should have arguments and return value that match
|
||||
the type \fBTcl_TimerProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_TimerProc(ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR parameter to \fIproc\fR is a
|
||||
copy of the \fIclientData\fR argument given to
|
||||
\fBTcl_CreateTimerHandler\fR when the callback
|
||||
was created. Typically, \fIclientData\fR points to a data
|
||||
structure containing application-specific information about
|
||||
what to do in \fIproc\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteTimerHandler\fR may be called to delete a
|
||||
previously-created timer handler. It deletes the handler
|
||||
indicated by \fItoken\fR so that no call to \fIproc\fR
|
||||
will be made; if that handler no longer exists
|
||||
(e.g. because the time period has already elapsed and \fIproc\fR
|
||||
has been invoked then \fBTcl_DeleteTimerHandler\fR does nothing.
|
||||
The tokens returned by \fBTcl_CreateTimerHandler\fR never have
|
||||
a value of NULL, so if NULL is passed to \fBTcl_DeleteTimerHandler\fR
|
||||
then the procedure does nothing.
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, clock, handler, timer
|
||||
@@ -1,106 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) CrtTrace.3 1.14 96/03/25 20:01:10
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_CreateTrace 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_CreateTrace, Tcl_DeleteTrace \- arrange for command execution to be traced
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Trace
|
||||
\fBTcl_CreateTrace\fR(\fIinterp, level, proc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteTrace\fR(\fIinterp, trace\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_CmdTraceProc (clientData)()
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter containing command to be traced or untraced.
|
||||
.AP int level in
|
||||
Only commands at or below this nesting level will be traced. 1 means
|
||||
top-level commands only, 2 means top-level commands or those that are
|
||||
invoked as immediate consequences of executing top-level commands
|
||||
(procedure bodies, bracketed commands, etc.) and so on.
|
||||
.AP Tcl_CmdTraceProc *proc in
|
||||
Procedure to call for each command that's executed. See below for
|
||||
details on the calling sequence.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.AP Tcl_Trace trace in
|
||||
Token for trace to be removed (return value from previous call
|
||||
to \fBTcl_CreateTrace\fR).
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_CreateTrace\fR arranges for command tracing. From now on, \fIproc\fR
|
||||
will be invoked before Tcl calls command procedures to process
|
||||
commands in \fIinterp\fR. The return value from
|
||||
\fBTcl_CreateTrace\fR is a token for the trace,
|
||||
which may be passed to \fBTcl_DeleteTrace\fR to remove the trace. There may
|
||||
be many traces in effect simultaneously for the same command interpreter.
|
||||
.PP
|
||||
\fIProc\fR should have arguments and result that match the
|
||||
type \fBTcl_CmdTraceProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_CmdTraceProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
int \fIlevel\fR,
|
||||
char *\fIcommand\fR,
|
||||
Tcl_CmdProc *\fIcmdProc\fR,
|
||||
ClientData \fIcmdClientData\fR,
|
||||
int \fIargc\fR,
|
||||
char *\fIargv\fR[]);
|
||||
.CE
|
||||
The \fIclientData\fR and \fIinterp\fR parameters are
|
||||
copies of the corresponding arguments given to \fBTcl_CreateTrace\fR.
|
||||
\fIClientData\fR typically points to an application-specific
|
||||
data structure that describes what to do when \fIproc\fR
|
||||
is invoked. \fILevel\fR gives the nesting level of the command
|
||||
(1 for top-level commands passed to \fBTcl_Eval\fR by the application,
|
||||
2 for the next-level commands passed to \fBTcl_Eval\fR as part of parsing
|
||||
or interpreting level-1 commands, and so on). \fICommand\fR
|
||||
points to a string containing the text of the
|
||||
command, before any argument substitution.
|
||||
\fICmdProc\fR contains the address of the command procedure that
|
||||
will be called to process the command (i.e. the \fIproc\fR argument
|
||||
of some previous call to \fBTcl_CreateCommand\fR) and \fIcmdClientData\fR
|
||||
contains the associated client data for \fIcmdProc\fR (the \fIclientData\fR
|
||||
value passed to \fBTcl_CreateCommand\fR). \fIArgc\fR and \fIargv\fR give
|
||||
the final argument information that will be passed to \fIcmdProc\fR, after
|
||||
command, variable, and backslash substitution.
|
||||
\fIProc\fR must not modify the \fIcommand\fR or \fIargv\fR strings.
|
||||
.PP
|
||||
Tracing will only occur for commands at nesting level less than
|
||||
or equal to the \fIlevel\fR parameter (i.e. the \fIlevel\fR
|
||||
parameter to \fIproc\fR will always be less than or equal to the
|
||||
\fIlevel\fR parameter to \fBTcl_CreateTrace\fR).
|
||||
.PP
|
||||
Calls to \fIproc\fR will be made by the Tcl parser immediately before
|
||||
it calls the command procedure for the command (\fIcmdProc\fR). This
|
||||
occurs after argument parsing and substitution, so tracing for
|
||||
substituted commands occurs before tracing of the commands
|
||||
containing the substitutions. If there is a syntax error in a
|
||||
command, or if there is no command procedure associated with a
|
||||
command name, then no tracing will occur for that command. If a
|
||||
string passed to Tcl_Eval contains multiple commands (bracketed, or
|
||||
on different lines) then multiple calls to \fIproc\fR will occur,
|
||||
one for each command. The \fIcommand\fR string for each of these
|
||||
trace calls will reflect only a single command, not the entire string
|
||||
passed to Tcl_Eval.
|
||||
.PP
|
||||
\fBTcl_DeleteTrace\fR removes a trace, so that no future calls will be
|
||||
made to the procedure associated with the trace. After \fBTcl_DeleteTrace\fR
|
||||
returns, the caller should never again use the \fItrace\fR token.
|
||||
|
||||
.SH KEYWORDS
|
||||
command, create, delete, interpreter, trace
|
||||
@@ -1,145 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) DString.3 1.20 96/08/26 12:59:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_DString 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_DStringInit, Tcl_DStringAppend, Tcl_DStringAppendElement, Tcl_DStringStartSublist, Tcl_DStringEndSublist, Tcl_DStringLength, Tcl_DStringValue, Tcl_DStringSetLength, Tcl_DStringFree, Tcl_DStringResult, Tcl_DStringGetResult \- manipulate dynamic strings
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_DStringInit\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_DStringAppend\fR(\fIdsPtr, string, length\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_DStringAppendElement\fR(\fIdsPtr, string\fR)
|
||||
.sp
|
||||
\fBTcl_DStringStartSublist\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DStringEndSublist\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_DStringLength\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_DStringValue\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DStringSetLength\fR(\fIdsPtr, newLength\fR)
|
||||
.sp
|
||||
\fBTcl_DStringFree\fR(\fIdsPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DStringResult\fR(\fIinterp, dsPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DStringGetResult\fR(\fIinterp, dsPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_DString newLength
|
||||
.AP Tcl_DString *dsPtr in/out
|
||||
Pointer to structure that is used to manage a dynamic string.
|
||||
.AP char *string in
|
||||
Pointer to characters to add to dynamic string.
|
||||
.AP int length in
|
||||
Number of characters from string to add to dynamic string. If -1,
|
||||
add all characters up to null terminating character.
|
||||
.AP int newLength in
|
||||
New length for dynamic string, not including null terminating
|
||||
character.
|
||||
.AP Tcl_Interp *interp in/out
|
||||
Interpreter whose result is to be set from or moved to the
|
||||
dynamic string.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Dynamic strings provide a mechanism for building up arbitrarily long
|
||||
strings by gradually appending information. If the dynamic string is
|
||||
short then there will be no memory allocation overhead; as the string
|
||||
gets larger, additional space will be allocated as needed.
|
||||
.PP
|
||||
\fBTcl_DStringInit\fR initializes a dynamic string to zero length.
|
||||
The Tcl_DString structure must have been allocated by the caller.
|
||||
No assumptions are made about the current state of the structure;
|
||||
anything already in it is discarded.
|
||||
If the structure has been used previously, \fBTcl_DStringFree\fR should
|
||||
be called first to free up any memory allocated for the old
|
||||
string.
|
||||
.PP
|
||||
\fBTcl_DStringAppend\fR adds new information to a dynamic string,
|
||||
allocating more memory for the string if needed.
|
||||
If \fIlength\fR is less than zero then everything in \fIstring\fR
|
||||
is appended to the dynamic string; otherwise \fIlength\fR
|
||||
specifies the number of bytes to append.
|
||||
\fBTcl_DStringAppend\fR returns a pointer to the characters of
|
||||
the new string. The string can also be retrieved from the
|
||||
\fIstring\fR field of the Tcl_DString structure.
|
||||
.PP
|
||||
\fBTcl_DStringAppendElement\fR is similar to \fBTcl_DStringAppend\fR
|
||||
except that it doesn't take a \fIlength\fR argument (it appends
|
||||
all of \fIstring\fR) and it converts the string to a proper list element
|
||||
before appending.
|
||||
\fBTcl_DStringAppendElement\fR adds a separator space before the
|
||||
new list element unless the new list element is the first in a
|
||||
list or sub-list (i.e. either the current string is empty, or it
|
||||
contains the single character ``{'', or the last two characters of
|
||||
the current string are `` {'').
|
||||
\fBTcl_DStringAppendElement\fR returns a pointer to the
|
||||
characters of the new string.
|
||||
.PP
|
||||
\fBTcl_DStringStartSublist\fR and \fBTcl_DStringEndSublist\fR can be
|
||||
used to create nested lists.
|
||||
To append a list element that is itself a sublist, first
|
||||
call \fBTcl_DStringStartSublist\fR, then call \fBTcl_DStringAppendElement\fR
|
||||
for each of the elements in the sublist, then call
|
||||
\fBTcl_DStringEndSublist\fR to end the sublist.
|
||||
\fBTcl_DStringStartSublist\fR appends a space character if needed,
|
||||
followed by an open brace; \fBTcl_DStringEndSublist\fR appends
|
||||
a close brace.
|
||||
Lists can be nested to any depth.
|
||||
.PP
|
||||
\fBTcl_DStringLength\fR is a macro that returns the current length
|
||||
of a dynamic string (not including the terminating null character).
|
||||
\fBTcl_DStringValue\fR is a macro that returns a pointer to the
|
||||
current contents of a dynamic string.
|
||||
.PP
|
||||
.PP
|
||||
\fBTcl_DStringSetLength\fR changes the length of a dynamic string.
|
||||
If \fInewLength\fR is less than the string's current length, then
|
||||
the string is truncated.
|
||||
If \fInewLength\fR is greater than the string's current length,
|
||||
then the string will become longer and new space will be allocated
|
||||
for the string if needed.
|
||||
However, \fBTcl_DStringSetLength\fR will not initialize the new
|
||||
space except to provide a terminating null character; it is up to the
|
||||
caller to fill in the new space.
|
||||
\fBTcl_DStringSetLength\fR does not free up the string's storage space
|
||||
even if the string is truncated to zero length, so \fBTcl_DStringFree\fR
|
||||
will still need to be called.
|
||||
.PP
|
||||
\fBTcl_DStringFree\fR should be called when you're finished using
|
||||
the string. It frees up any memory that was allocated for the string
|
||||
and reinitializes the string's value to an empty string.
|
||||
.PP
|
||||
\fBTcl_DStringResult\fR sets the result of \fIinterp\fR to the value of
|
||||
the dynamic string given by \fIdsPtr\fR. It does this by moving
|
||||
a pointer from \fIdsPtr\fR to \fIinterp->result\fR.
|
||||
This saves the cost of allocating new memory and copying the string.
|
||||
\fBTcl_DStringResult\fR also reinitializes the dynamic string to
|
||||
an empty string.
|
||||
.PP
|
||||
\fBTcl_DStringGetResult\fR does the opposite of \fBTcl_DStringResult\fR.
|
||||
It sets the value of \fIdsPtr\fR to the result of \fIinterp\fR and
|
||||
it clears \fIinterp\fR's result.
|
||||
If possible it does this by moving a pointer rather than by copying
|
||||
the string.
|
||||
|
||||
.SH KEYWORDS
|
||||
append, dynamic string, free, result
|
||||
@@ -1,62 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) DetachPids.3 1.15 96/08/26 12:59:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_DetachPids 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_DetachPids, Tcl_ReapDetachedProcs \- manage child processes in background
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_DetachPids\fR(\fInumPids, pidPtr\fR)
|
||||
.sp
|
||||
\fBTcl_ReapDetachedProcs\fR()
|
||||
.SH ARGUMENTS
|
||||
.AS int *statusPtr
|
||||
.AP int numPids in
|
||||
Number of process ids contained in the array pointed to by \fIpidPtr\fR.
|
||||
.AP int *pidPtr in
|
||||
Address of array containing \fInumPids\fR process ids.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_DetachPids\fR and \fBTcl_ReapDetachedProcs\fR provide a
|
||||
mechanism for managing subprocesses that are running in background.
|
||||
These procedures are needed because the parent of a process must
|
||||
eventually invoke the \fBwaitpid\fR kernel call (or one of a few other
|
||||
similar kernel calls) to wait for the child to exit. Until the
|
||||
parent waits for the child, the child's state cannot be completely
|
||||
reclaimed by the system. If a parent continually creates children
|
||||
and doesn't wait on them, the system's process table will eventually
|
||||
overflow, even if all the children have exited.
|
||||
.PP
|
||||
\fBTcl_DetachPids\fR may be called to ask Tcl to take responsibility
|
||||
for one or more processes whose process ids are contained in the
|
||||
\fIpidPtr\fR array passed as argument. The caller presumably
|
||||
has started these processes running in background and doesn't
|
||||
want to have to deal with them again.
|
||||
.PP
|
||||
\fBTcl_ReapDetachedProcs\fR invokes the \fBwaitpid\fR kernel call
|
||||
on each of the background processes so that its state can be cleaned
|
||||
up if it has exited. If the process hasn't exited yet,
|
||||
\fBTcl_ReapDetachedProcs\fR doesn't wait for it to exit; it will check again
|
||||
the next time it is invoked.
|
||||
Tcl automatically calls \fBTcl_ReapDetachedProcs\fR each time the
|
||||
\fBexec\fR command is executed, so in most cases it isn't necessary
|
||||
for any code outside of Tcl to invoke \fBTcl_ReapDetachedProcs\fR.
|
||||
However, if you call \fBTcl_DetachPids\fR in situations where the
|
||||
\fBexec\fR command may never get executed, you may wish to call
|
||||
\fBTcl_ReapDetachedProcs\fR from time to time so that background
|
||||
processes can be cleaned up.
|
||||
|
||||
.SH KEYWORDS
|
||||
background, child, detach, process, wait
|
||||
@@ -1,108 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990-1992 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) DoOneEvent.3 1.6 97/05/09 18:12:05
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_DoOneEvent 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_DoOneEvent \- wait for events and invoke event handlers
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_DoOneEvent\fR(\fIflags\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS int flags
|
||||
.AP int flags in
|
||||
This parameter is normally zero. It may be an OR-ed combination
|
||||
of any of the following flag bits:
|
||||
TCL_WINDOW_EVENTS,
|
||||
TCL_FILE_EVENTS, TCL_TIMER_EVENTS, TCL_IDLE_EVENTS, TCL_ALL_EVENTS, or
|
||||
TCL_DONT_WAIT.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure is the entry point to Tcl's event loop; it is responsible for
|
||||
waiting for events and dispatching event handlers created with
|
||||
procedures such as \fBTk_CreateEventHandler\fR, \fBTcl_CreateFileHandler\fR,
|
||||
\fBTcl_CreateTimerHandler\fR, and \fBTcl_DoWhenIdle\fR.
|
||||
\fBTcl_DoOneEvent\fR checks to see if
|
||||
events are already present on the Tcl event queue; if so,
|
||||
it calls the handler(s) for the first (oldest) event, removes it from
|
||||
the queue, and returns.
|
||||
If there are no events ready to be handled, then \fBTcl_DoOneEvent\fR
|
||||
checks for new events from all possible sources.
|
||||
If any are found, it puts all of them on Tcl's event queue, calls
|
||||
handlers for the first event on the queue, and returns.
|
||||
If no events are found, \fBTcl_DoOneEvent\fR checks for \fBTcl_DoWhenIdle\fR
|
||||
callbacks; if any are found, it invokes all of them and returns.
|
||||
Finally, if no events or idle callbacks have been found, then
|
||||
\fBTcl_DoOneEvent\fR sleeps until an event occurs; then it adds any
|
||||
new events to the Tcl event queue, calls handlers for the first event,
|
||||
and returns.
|
||||
The normal return value is 1 to signify that some event
|
||||
was processed (see below for other alternatives).
|
||||
.PP
|
||||
If the \fIflags\fR argument to \fBTcl_DoOneEvent\fR is non-zero,
|
||||
it restricts the kinds of events that will be processed by
|
||||
\fBTcl_DoOneEvent\fR.
|
||||
\fIFlags\fR may be an OR-ed combination of any of the following bits:
|
||||
.TP 27
|
||||
\fBTCL_WINDOW_EVENTS\fR \-
|
||||
Process window system events.
|
||||
.TP 27
|
||||
\fBTCL_FILE_EVENTS\fR \-
|
||||
Process file events.
|
||||
.TP 27
|
||||
\fBTCL_TIMER_EVENTS\fR \-
|
||||
Process timer events.
|
||||
.TP 27
|
||||
\fBTCL_IDLE_EVENTS\fR \-
|
||||
Process idle callbacks.
|
||||
.TP 27
|
||||
\fBTCL_ALL_EVENTS\fR \-
|
||||
Process all kinds of events: equivalent to OR-ing together all of the
|
||||
above flags or specifying none of them.
|
||||
.TP 27
|
||||
\fBTCL_DONT_WAIT\fR \-
|
||||
Don't sleep: process only events that are ready at the time of the
|
||||
call.
|
||||
.LP
|
||||
If any of the flags \fBTCL_WINDOW_EVENTS\fR, \fBTCL_FILE_EVENTS\fR,
|
||||
\fBTCL_TIMER_EVENTS\fR, or \fBTCL_IDLE_EVENTS\fR is set, then the only
|
||||
events that will be considered are those for which flags are set.
|
||||
Setting none of these flags is equivalent to the value
|
||||
\fBTCL_ALL_EVENTS\fR, which causes all event types to be processed.
|
||||
If an application has defined additional event sources with
|
||||
\fBTcl_CreateEventSource\fR, then additional \fIflag\fR values
|
||||
may also be valid, depending on those event sources.
|
||||
.PP
|
||||
The \fBTCL_DONT_WAIT\fR flag causes \fBTcl_DoOneEvent\fR not to put
|
||||
the process to sleep: it will check for events but if none are found
|
||||
then it returns immediately with a return value of 0 to indicate
|
||||
that no work was done.
|
||||
\fBTcl_DoOneEvent\fR will also return 0 without doing anything if
|
||||
the only alternative is to block forever (this can happen, for example,
|
||||
if \fIflags\fR is \fBTCL_IDLE_EVENTS\fR and there are no
|
||||
\fBTcl_DoWhenIdle\fR callbacks pending, or if no event handlers or
|
||||
timer handlers exist).
|
||||
.PP
|
||||
\fBTcl_DoOneEvent\fR may be invoked recursively. For example,
|
||||
it is possible to invoke \fBTcl_DoOneEvent\fR recursively
|
||||
from a handler called by \fBTcl_DoOneEvent\fR. This sort
|
||||
of operation is useful in some modal situations, such
|
||||
as when a
|
||||
notification dialog has been popped up and an application wishes to
|
||||
wait for the user to click a button in the dialog before
|
||||
doing anything else.
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, event, handler, idle, timer
|
||||
@@ -1,86 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) DoWhenIdle.3 1.6 97/05/09 18:18:33
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_DoWhenIdle 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_DoWhenIdle, Tcl_CancelIdleCall \- invoke a procedure when there are no pending events
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_DoWhenIdle\fR(\fIproc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_CancelIdleCall\fR(\fIproc, clientData\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_IdleProc clientData
|
||||
.AP Tcl_IdleProc *proc in
|
||||
Procedure to invoke.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_DoWhenIdle\fR arranges for \fIproc\fR to be invoked
|
||||
when the application becomes idle. The application is
|
||||
considered to be idle when \fBTcl_DoOneEvent\fR has been
|
||||
called, couldn't find any events to handle, and is about
|
||||
to go to sleep waiting for an event to occur. At this
|
||||
point all pending \fBTcl_DoWhenIdle\fR handlers are
|
||||
invoked. For each call to \fBTcl_DoWhenIdle\fR there will
|
||||
be a single call to \fIproc\fR; after \fIproc\fR is
|
||||
invoked the handler is automatically removed.
|
||||
\fBTcl_DoWhenIdle\fR is only usable in programs that
|
||||
use \fBTcl_DoOneEvent\fR to dispatch events.
|
||||
.PP
|
||||
\fIProc\fR should have arguments and result that match the
|
||||
type \fBTcl_IdleProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_IdleProc(ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
|
||||
argument given to \fBTcl_DoWhenIdle\fR. Typically, \fIclientData\fR
|
||||
points to a data structure containing application-specific information about
|
||||
what \fIproc\fR should do.
|
||||
.PP
|
||||
\fBTcl_CancelIdleCall\fR
|
||||
may be used to cancel one or more previous
|
||||
calls to \fBTcl_DoWhenIdle\fR: if there is a \fBTcl_DoWhenIdle\fR
|
||||
handler registered for \fIproc\fR and \fIclientData\fR, then it
|
||||
is removed without invoking it. If there is more than one
|
||||
handler on the idle list that refers to \fIproc\fR and \fIclientData\fR,
|
||||
all of the handlers are removed. If no existing handlers match
|
||||
\fIproc\fR and \fIclientData\fR then nothing happens.
|
||||
.PP
|
||||
\fBTcl_DoWhenIdle\fR is most useful in situations where
|
||||
(a) a piece of work will have to be done but (b) it's
|
||||
possible that something will happen in the near future
|
||||
that will change what has to be done or require something
|
||||
different to be done. \fBTcl_DoWhenIdle\fR allows the
|
||||
actual work to be deferred until all pending events have
|
||||
been processed. At this point the exact work to be done
|
||||
will presumably be known and it can be done exactly once.
|
||||
.PP
|
||||
For example, \fBTcl_DoWhenIdle\fR might be used by an editor
|
||||
to defer display updates until all pending commands have
|
||||
been processed. Without this feature, redundant redisplays
|
||||
might occur in some situations, such as the processing of
|
||||
a command file.
|
||||
.SH BUGS
|
||||
.PP
|
||||
At present it is not safe for an idle callback to reschedule itself
|
||||
continuously. This will interact badly with certain features of Tk
|
||||
that attempt to wait for all idle callbacks to complete. If you would
|
||||
like for an idle callback to reschedule itself continuously, it is
|
||||
better to use a timer handler with a zero timeout period.
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, defer, idle callback
|
||||
@@ -1,79 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) DoubleObj.3 1.6 97/05/08 19:50:07
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_DoubleObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_NewDoubleObj, Tcl_SetDoubleObj, Tcl_GetDoubleFromObj \- manipulate Tcl objects as floating-point values
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewDoubleObj\fR(\fIdoubleValue\fR)
|
||||
.sp
|
||||
\fBTcl_SetDoubleObj\fR(\fIobjPtr, doubleValue\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetDoubleFromObj\fR(\fIinterp, objPtr, doublePtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp doubleValue in/out
|
||||
.AP double doubleValue in
|
||||
A double-precision floating point value used to initialize or set a double object.
|
||||
.AP Tcl_Obj *objPtr in/out
|
||||
For \fBTcl_SetDoubleObj\fR, this points to the object to be converted
|
||||
to double type.
|
||||
For \fBTcl_GetDoubleFromObj\fR, this refers to the object
|
||||
from which to get a double value;
|
||||
if \fIobjPtr\fR does not already point to a double object,
|
||||
an attempt will be made to convert it to one.
|
||||
.AP Tcl_Interp *interp in/out
|
||||
If an error occurs during conversion,
|
||||
an error message is left in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
.AP double *doublePtr out
|
||||
Points to place to store the double value
|
||||
obtained from \fIobjPtr\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures are used to create, modify, and read
|
||||
double Tcl objects from C code.
|
||||
\fBTcl_NewDoubleObj\fR and \fBTcl_SetDoubleObj\fR
|
||||
will create a new object of double type
|
||||
or modify an existing object to have double type.
|
||||
Both of these procedures set the object to have the
|
||||
double-precision floating point value given by \fIdoubleValue\fR;
|
||||
\fBTcl_NewDoubleObj\fR returns a pointer to a newly created object
|
||||
with reference count zero.
|
||||
Both procedures set the object's type to be double
|
||||
and assign the double value to the object's internal representation
|
||||
\fIdoubleValue\fR member.
|
||||
\fBTcl_SetDoubleObj\fR invalidates any old string representation
|
||||
and, if the object is not already a double object,
|
||||
frees any old internal representation.
|
||||
.PP
|
||||
\fBTcl_GetDoubleFromObj\fR attempts to return a double value
|
||||
from the Tcl object \fIobjPtr\fR.
|
||||
If the object is not already a double object,
|
||||
it will attempt to convert it to one.
|
||||
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
Otherwise, it returns \fBTCL_OK\fR and stores the double value
|
||||
in the address given by \fIdoublePtr\fR.
|
||||
If the object is not already a double object,
|
||||
the conversion will free any old internal representation.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
double, double object, double type, internal representation, object, object type, string representation
|
||||
@@ -1,114 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Eval.3 1.21 97/01/22 14:22:03
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Eval 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Eval, Tcl_VarEval, Tcl_EvalFile, Tcl_GlobalEval \- execute Tcl commands
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Eval\fR(\fIinterp, cmd\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_VarEval\fR(\fIinterp, string, string, ... \fB(char *) NULL\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_EvalFile\fR(\fIinterp, fileName\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GlobalEval\fR(\fIinterp, cmd\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp **termPtr;
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to execute the command.
|
||||
A string result will be stored in \fIinterp->result\fR.
|
||||
.AP char *cmd in
|
||||
Command (or sequence of commands) to execute. Must be in writable
|
||||
memory (\fBTcl_Eval\fR makes temporary modifications to the command).
|
||||
.AP char *string in
|
||||
String forming part of Tcl command.
|
||||
.AP char *fileName in
|
||||
Name of file containing Tcl command string.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
All four of these procedures execute Tcl commands.
|
||||
\fBTcl_Eval\fR is the core procedure and is used by all the others.
|
||||
It executes the commands in the script held by \fIcmd\fR
|
||||
until either an error occurs or it reaches the end of the script.
|
||||
.PP
|
||||
Note that \fBTcl_Eval\fR and \fBTcl_GlobalEval\fR
|
||||
have been largely replaced by the
|
||||
object-based procedures \fBTcl_EvalObj\fR and \fBTcl_GlobalEvalObj\fR.
|
||||
Those object-based procedures evaluate a script held in a Tcl object
|
||||
instead of a string.
|
||||
The object argument can retain the bytecode instructions for the script
|
||||
and so avoid reparsing the script each time it is executed.
|
||||
\fBTcl_Eval\fR is implemented using \fBTcl_EvalObj\fR
|
||||
but is slower because it must reparse the script each time
|
||||
since there is no object to retain the bytecode instructions.
|
||||
.PP
|
||||
The return value from \fBTcl_Eval\fR is one of the Tcl return codes
|
||||
\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
|
||||
\fBTCL_CONTINUE\fR, and \fIinterp->result\fR will point to
|
||||
a string with additional information (a result value or error message).
|
||||
If an error occurs during compilation, this return information
|
||||
describes the error.
|
||||
Otherwise, this return information corresponds to the last command
|
||||
executed from \fIcmd\fR.
|
||||
.PP
|
||||
\fBTcl_VarEval\fR takes any number of string arguments
|
||||
of any length, concatenates them into a single string,
|
||||
then calls \fBTcl_Eval\fR to execute that string as a Tcl command.
|
||||
It returns the result of the command and also modifies
|
||||
\fIinterp->result\fR in the usual fashion for Tcl commands.
|
||||
The last argument to \fBTcl_VarEval\fR must be NULL to indicate the end
|
||||
of arguments.
|
||||
.PP
|
||||
\fBTcl_EvalFile\fR reads the file given by \fIfileName\fR and evaluates
|
||||
its contents as a Tcl command by calling \fBTcl_Eval\fR. It returns
|
||||
a standard Tcl result that reflects the result of evaluating the file.
|
||||
If the file couldn't be read then a Tcl error is returned to describe
|
||||
why the file couldn't be read.
|
||||
.PP
|
||||
During the processing of a Tcl command it is legal to make nested
|
||||
calls to evaluate other commands (this is how procedures and
|
||||
some control structures are implemented).
|
||||
If a code other than \fBTCL_OK\fR is returned
|
||||
from a nested \fBTcl_Eval\fR invocation,
|
||||
then the caller should normally return immediately,
|
||||
passing that same return code back to its caller,
|
||||
and so on until the top-level application is reached.
|
||||
A few commands, like \fBfor\fR, will check for certain
|
||||
return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
|
||||
specially without returning.
|
||||
.PP
|
||||
\fBTcl_Eval\fR keeps track of how many nested \fBTcl_Eval\fR
|
||||
invocations are in progress for \fIinterp\fR.
|
||||
If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
|
||||
about to be returned from the topmost \fBTcl_Eval\fR
|
||||
invocation for \fIinterp\fR,
|
||||
it converts the return code to \fBTCL_ERROR\fR
|
||||
and sets \fIinterp->result\fR
|
||||
to point to an error message indicating that
|
||||
the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
|
||||
invoked in an inappropriate place.
|
||||
This means that top-level applications should never see a return code
|
||||
from \fBTcl_Eval\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_EvalObj, Tcl_GlobalEvalObj
|
||||
|
||||
.SH KEYWORDS
|
||||
command, execute, file, global, object, object result, variable
|
||||
@@ -1,91 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) EvalObj.3 1.4 97/01/22 15:18:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_EvalObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_EvalObj, Tcl_GlobalEvalObj \- execute Tcl commands
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_EvalObj\fR(\fIinterp, objPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GlobalEvalObj\fR(\fIinterp, objPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp **termPtr;
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to execute the command.
|
||||
The command's result will be stored in the interpreter's result object
|
||||
and can be retrieved using \fBTcl_GetObjResult\fR.
|
||||
.AP Tcl_Obj *objPtr in
|
||||
A Tcl object containing a command string
|
||||
(or sequence of commands in a string) to execute.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These two procedures execute Tcl commands.
|
||||
\fBTcl_EvalObj\fR is the core procedure
|
||||
and is used by \fBTcl_GlobalEvalObj\fR.
|
||||
It executes the commands in the script held by \fIobjPtr\fR
|
||||
until either an error occurs or it reaches the end of the script.
|
||||
If this is the first time \fIobjPtr\fR has been executed,
|
||||
its commands are compiled into bytecode instructions
|
||||
that are then executed if there are no compilation errors.
|
||||
.PP
|
||||
The return value from \fBTcl_EvalObj\fR is one of the Tcl return codes
|
||||
\fBTCL_OK\fR, \fBTCL_ERROR\fR, \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or
|
||||
\fBTCL_CONTINUE\fR,
|
||||
and a result object containing additional information
|
||||
(a result value or error message)
|
||||
that can be retrieved using \fBTcl_GetObjResult\fR.
|
||||
If an error occurs during compilation, this return information
|
||||
describes the error.
|
||||
Otherwise, this return information corresponds to the last command
|
||||
executed from \fIobjPtr\fR.
|
||||
.PP
|
||||
\fBTcl_GlobalEvalObj\fR is similar to \fBTcl_EvalObj\fR except that it
|
||||
processes the command at global level.
|
||||
This means that the variable context for the command consists of
|
||||
global variables only (it ignores any Tcl procedure that is active).
|
||||
This produces an effect similar to the Tcl command ``\fBuplevel 0\fR''.
|
||||
.PP
|
||||
During the processing of a Tcl command it is legal to make nested
|
||||
calls to evaluate other commands (this is how procedures and
|
||||
some control structures are implemented).
|
||||
If a code other than \fBTCL_OK\fR is returned
|
||||
from a nested \fBTcl_EvalObj\fR invocation,
|
||||
then the caller should normally return immediately,
|
||||
passing that same return code back to its caller,
|
||||
and so on until the top-level application is reached.
|
||||
A few commands, like \fBfor\fR, will check for certain
|
||||
return codes, like \fBTCL_BREAK\fR and \fBTCL_CONTINUE\fR, and process them
|
||||
specially without returning.
|
||||
.PP
|
||||
\fBTcl_EvalObj\fR keeps track of how many nested \fBTcl_EvalObj\fR
|
||||
invocations are in progress for \fIinterp\fR.
|
||||
If a code of \fBTCL_RETURN\fR, \fBTCL_BREAK\fR, or \fBTCL_CONTINUE\fR is
|
||||
about to be returned from the topmost \fBTcl_EvalObj\fR
|
||||
invocation for \fIinterp\fR,
|
||||
it converts the return code to \fBTCL_ERROR\fR
|
||||
and sets the interpreter's result object
|
||||
to point to an error message indicating that
|
||||
the \fBreturn\fR, \fBbreak\fR, or \fBcontinue\fR command was
|
||||
invoked in an inappropriate place.
|
||||
This means that top-level applications should never see a return code
|
||||
from \fBTcl_EvalObj\fR other then \fBTCL_OK\fR or \fBTCL_ERROR\fR.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_GetObjResult, Tcl_SetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
command, execute, file, global, object, object result, variable
|
||||
@@ -1,103 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Exit.3 1.8 96/12/10 07:37:23
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Exit 3 7.7 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Exit, Tcl_Finalize, Tcl_CreateExitHandler, Tcl_DeleteExitHandler \- end the application (and invoke exit handlers)
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_Exit\fR(\fIstatus\fR)
|
||||
.sp
|
||||
\fBTcl_Finalize\fR()
|
||||
.sp
|
||||
\fBTcl_CreateExitHandler\fR(\fIproc, clientData\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteExitHandler\fR(\fIproc, clientData\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ExitProc clientData
|
||||
.AP int status in
|
||||
Provides information about why application exited. Exact meaning may
|
||||
be platform-specific. 0 usually means a normal exit, any nonzero value
|
||||
usually means that an error occurred.
|
||||
.AP Tcl_ExitProc *proc in
|
||||
Procedure to invoke before exiting application.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The procedures described here provide a graceful mechanism to end the
|
||||
execution of a \fBTcl\fR application. Exit handlers are invoked to cleanup the
|
||||
application's state before ending the execution of \fBTcl\fR code.
|
||||
.PP
|
||||
Invoke \fBTcl_Exit\fR to end a \fBTcl\fR application and to exit from this
|
||||
process. This procedure is invoked by the \fBexit\fR command, and can be
|
||||
invoked anyplace else to terminate the application.
|
||||
No-one should ever invoke the \fBexit\fR system procedure directly; always
|
||||
invoke \fBTcl_Exit\fR instead, so that it can invoke exit handlers.
|
||||
Note that if other code invokes \fBexit\fR system procedure directly, or
|
||||
otherwise causes the application to terminate without calling
|
||||
\fBTcl_Exit\fR, the exit handlers will not be run.
|
||||
\fBTcl_Exit\fR internally invokes the \fBexit\fR system call, thus it never
|
||||
returns control to its caller.
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_Finalize\fR is similar to \fBTcl_Exit\fR except that it does not
|
||||
exit from the current process.
|
||||
It is useful for cleaning up when a process is finished using \fBTcl\fR but
|
||||
wishes to continue executing, and when \fBTcl\fR is used in a dynamically
|
||||
loaded extension that is about to be unloaded.
|
||||
On some systems \fBTcl\fR is automatically notified when it is being
|
||||
unloaded, and it calls \fBTcl_Finalize\fR internally; on these systems it
|
||||
not necessary for the caller to explicitly call \fBTcl_Finalize\fR.
|
||||
However, to ensure portability, your code should always invoke
|
||||
\fBTcl_Finalize\fR when \fBTcl\fR is being unloaded, to ensure that the
|
||||
code will work on all platforms. \fBTcl_Finalize\fR can be safely called
|
||||
more than once.
|
||||
.VE
|
||||
.PP
|
||||
\fBTcl_CreateExitHandler\fR arranges for \fIproc\fR to be invoked
|
||||
by \fBTcl_Finalize\fR and \fBTcl_Exit\fR.
|
||||
This provides a hook for cleanup operations such as flushing buffers
|
||||
and freeing global memory.
|
||||
\fIProc\fR should match the type \fBTcl_ExitProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_ExitProc(ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR parameter to \fIproc\fR is a
|
||||
copy of the \fIclientData\fR argument given to
|
||||
\fBTcl_CreateExitHandler\fR when the callback
|
||||
was created. Typically, \fIclientData\fR points to a data
|
||||
structure containing application-specific information about
|
||||
what to do in \fIproc\fR.
|
||||
.PP
|
||||
\fBTcl_DeleteExitHandler\fR may be called to delete a
|
||||
previously-created exit handler. It removes the handler
|
||||
indicated by \fIproc\fR and \fIclientData\fR so that no call
|
||||
to \fIproc\fR will be made. If no such handler exists then
|
||||
\fBTcl_DeleteExitHandler\fR does nothing.
|
||||
.PP
|
||||
.VS
|
||||
.PP
|
||||
\fBTcl_Finalize\fR and \fBTcl_Exit\fR execute all registered exit handlers,
|
||||
in reverse order from the order in which they were registered.
|
||||
This matches the natural order in which extensions are loaded and unloaded;
|
||||
if extension \fBA\fR loads extension \fBB\fR, it usually
|
||||
unloads \fBB\fR before it itself is unloaded.
|
||||
If extension \fBA\fR registers its exit handlers before loading extension
|
||||
\fBB\fR, this ensures that any exit handlers for \fBB\fR will be executed
|
||||
before the exit handlers for \fBA\fR.
|
||||
.VE
|
||||
|
||||
.SH KEYWORDS
|
||||
callback, cleanup, dynamic loading, end application, exit, unloading
|
||||
@@ -1,114 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) ExprLong.3 1.26 97/06/26 13:42:47
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_ExprLong 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString \- evaluate an expression
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprLong\fR(\fIinterp, string, longPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprDouble\fR(\fIinterp, string, doublePtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprBoolean\fR(\fIinterp, string, booleanPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprString\fR(\fIinterp, string\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *booleanPtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
|
||||
.AP char *string in
|
||||
Expression to be evaluated. Must be in writable memory (the expression
|
||||
parser makes temporary modifications to the string during parsing, which
|
||||
it undoes before returning).
|
||||
.AP long *longPtr out
|
||||
Pointer to location in which to store the integer value of the
|
||||
expression.
|
||||
.AP int *doublePtr out
|
||||
Pointer to location in which to store the floating-point value of the
|
||||
expression.
|
||||
.AP int *booleanPtr out
|
||||
Pointer to location in which to store the 0/1 boolean value of the
|
||||
expression.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These four procedures all evaluate the expression
|
||||
given by the \fIstring\fR argument
|
||||
and return the result in one of four different forms.
|
||||
The expression can have any of the forms accepted by the \fBexpr\fR command.
|
||||
Note that these procedures have been largely replaced by the
|
||||
object-based procedures \fBTcl_ExprLongObj\fR, \fBTcl_ExprDoubleObj\fR,
|
||||
\fBTcl_ExprBooleanObj\fR, and \fBTcl_ExprStringObj\fR.
|
||||
Those object-based procedures evaluate an expression held in a Tcl object
|
||||
instead of a string.
|
||||
The object argument can retain an internal representation
|
||||
that is more efficient to execute.
|
||||
.PP
|
||||
The \fIinterp\fR argument refers to an interpreter used to
|
||||
evaluate the expression (e.g. for variables and nested Tcl
|
||||
commands) and to return error information.
|
||||
\fIinterp->result\fR is assumed to be initialized
|
||||
in the standard fashion when they are invoked.
|
||||
.PP
|
||||
For all of these procedures the return value is a standard
|
||||
Tcl result: \fBTCL_OK\fR means the expression was successfully
|
||||
evaluated, and \fBTCL_ERROR\fR means that an error occurred while
|
||||
evaluating the expression.
|
||||
If \fBTCL_ERROR\fR is returned then
|
||||
\fIinterp->result\fR will hold a message describing the error.
|
||||
If an error occurs while executing a Tcl command embedded in
|
||||
the expression then that error will be returned.
|
||||
.PP
|
||||
If the expression is successfully evaluated, then its value is
|
||||
returned in one of four forms, depending on which procedure
|
||||
is invoked.
|
||||
\fBTcl_ExprLong\fR stores an integer value at \fI*longPtr\fR.
|
||||
If the expression's actual value is a floating-point number,
|
||||
then it is truncated to an integer.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
an error is returned.
|
||||
.PP
|
||||
\fBTcl_ExprDouble\fR stores a floating-point value at \fI*doublePtr\fR.
|
||||
If the expression's actual value is an integer, it is converted to
|
||||
floating-point.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
an error is returned.
|
||||
.PP
|
||||
\fBTcl_ExprBoolean\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
|
||||
If the expression's actual value is an integer or floating-point
|
||||
number, then they store 0 at \fI*booleanPtr\fR if
|
||||
the value was zero and 1 otherwise.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
it must be one of the values accepted by \fBTcl_GetBoolean\fR
|
||||
such as ``yes'' or ``no'', or else an error occurs.
|
||||
.PP
|
||||
\fBTcl_ExprString\fR returns the value of the expression as a
|
||||
string stored in \fIinterp->result\fR.
|
||||
If the expression's actual value is an integer
|
||||
then \fBTcl_ExprString\fR converts it to a string using \fBsprintf\fR
|
||||
with a ``%d'' converter.
|
||||
If the expression's actual value is a floating-point
|
||||
number, then \fBTcl_ExprString\fR calls \fBTcl_PrintDouble\fR
|
||||
to convert it to a string.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj
|
||||
|
||||
.SH KEYWORDS
|
||||
boolean, double, evaluate, expression, integer, object, string
|
||||
@@ -1,104 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) ExprLongObj.3 1.6 97/06/26 13:41:12
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_ExprLongObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_ExprLongObj, Tcl_ExprDoubleObj, Tcl_ExprBooleanObj, Tcl_ExprObj \- evaluate an expression
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprLongObj\fR(\fIinterp, objPtr, longPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprDoubleObj\fR(\fIinterp, objPtr, doublePtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprBooleanObj\fR(\fIinterp, objPtr, booleanPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ExprObj\fR(\fIinterp, objPtr, resultPtrPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *resultPtrPtr out
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in whose context to evaluate \fIstring\fR or \fIobjPtr\fR.
|
||||
.AP Tcl_Obj *objPtr in
|
||||
Pointer to an object containing the expression to evaluate.
|
||||
.AP long *longPtr out
|
||||
Pointer to location in which to store the integer value of the
|
||||
expression.
|
||||
.AP int *doublePtr out
|
||||
Pointer to location in which to store the floating-point value of the
|
||||
expression.
|
||||
.AP int *booleanPtr out
|
||||
Pointer to location in which to store the 0/1 boolean value of the
|
||||
expression.
|
||||
.AP Tcl_Obj *resultPtrPtr out
|
||||
Pointer to location in which to store a pointer to the object
|
||||
that is the result of the expression.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These four procedures all evaluate an expression, returning
|
||||
the result in one of four different forms.
|
||||
The expression is given by the \fIobjPtr\fR argument, and it
|
||||
can have any of the forms accepted by the \fBexpr\fR command.
|
||||
.PP
|
||||
The \fIinterp\fR argument refers to an interpreter used to
|
||||
evaluate the expression (e.g. for variables and nested Tcl
|
||||
commands) and to return error information.
|
||||
.PP
|
||||
For all of these procedures the return value is a standard
|
||||
Tcl result: \fBTCL_OK\fR means the expression was successfully
|
||||
evaluated, and \fBTCL_ERROR\fR means that an error occurred while
|
||||
evaluating the expression.
|
||||
If \fBTCL_ERROR\fR is returned,
|
||||
then a message describing the error
|
||||
can be retrieved using \fBTcl_GetObjResult\fR.
|
||||
If an error occurs while executing a Tcl command embedded in
|
||||
the expression then that error will be returned.
|
||||
.PP
|
||||
If the expression is successfully evaluated, then its value is
|
||||
returned in one of four forms, depending on which procedure
|
||||
is invoked.
|
||||
\fBTcl_ExprLongObj\fR stores an integer value at \fI*longPtr\fR.
|
||||
If the expression's actual value is a floating-point number,
|
||||
then it is truncated to an integer.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
an error is returned.
|
||||
.PP
|
||||
\fBTcl_ExprDoubleObj\fR stores a floating-point value at \fI*doublePtr\fR.
|
||||
If the expression's actual value is an integer, it is converted to
|
||||
floating-point.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
an error is returned.
|
||||
.PP
|
||||
\fBTcl_ExprBooleanObj\fR stores a 0/1 integer value at \fI*booleanPtr\fR.
|
||||
If the expression's actual value is an integer or floating-point
|
||||
number, then they store 0 at \fI*booleanPtr\fR if
|
||||
the value was zero and 1 otherwise.
|
||||
If the expression's actual value is a non-numeric string then
|
||||
it must be one of the values accepted by \fBTcl_GetBoolean\fR
|
||||
such as ``yes'' or ``no'', or else an error occurs.
|
||||
.PP
|
||||
If \fBTcl_ExprObj\fR successfully evaluates the expression,
|
||||
it stores a pointer to the Tcl object
|
||||
containing the expression's value at \fI*resultPtrPtr\fR.
|
||||
In this case, the caller is responsible for calling
|
||||
\fBTcl_DecrRefCount\fR to decrement the object's reference count
|
||||
when it is finished with the object.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_ExprLong, Tcl_ExprDouble, Tcl_ExprBoolean, Tcl_ExprString, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
boolean, double, evaluate, expression, integer, object, string
|
||||
@@ -1,46 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) FindExec.3 1.4 96/10/09 08:29:29
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_FindExecutable 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_FindExecutable \- identify the binary file containing the application
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_FindExecutable\fR(\fIargv0\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS char *argv0 in
|
||||
.AP char *argv0 in
|
||||
The first command-line argument to the program, which gives the
|
||||
application's name.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure computes the full path name of the executable file
|
||||
from which the application was invoked and saves it for Tcl's
|
||||
internal use.
|
||||
The executable's path name is needed for several purposes in
|
||||
Tcl. For example, it is needed on some platforms in the
|
||||
implementation of the \fBload\fR command.
|
||||
It is also returned by the \fBinfo nameofexecutable\fR command.
|
||||
.PP
|
||||
On UNIX platforms this procedure is typically invoked as the very
|
||||
first thing in the application's main program; it must be passed
|
||||
\fIargv[0]\fR as its argument. \fBTcl_FindExecutable\fR uses \fIargv0\fR
|
||||
along with the \fBPATH\fR environment variable to find the
|
||||
application's executable, if possible. If it fails to find
|
||||
the binary, then future calls to \fBinfo nameofexecutable\fR
|
||||
will return an empty string.
|
||||
|
||||
.SH KEYWORDS
|
||||
binary, executable file
|
||||
@@ -1,77 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) GetIndex.3 1.3 97/07/30 16:21:05
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_GetIndexFromObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_GetIndexFromObj \- lookup string in table of keywords
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetIndexFromObj\fR(\fIinterp, objPtr, tablePtr, msg, flags, indexPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp **tablePtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter to use for error reporting; if NULL, then no message is
|
||||
provided on errors.
|
||||
.AP Tcl_Obj *objPtr in/out
|
||||
The string value of this object is used to search through \fItablePtr\fR.
|
||||
The internal representation is modified to hold the index of the matching
|
||||
table entry.
|
||||
.AP char **tablePtr in
|
||||
An array of null-terminated strings. The end of the array is marked
|
||||
by a NULL string pointer.
|
||||
.AP char *msg in
|
||||
Null-terminated string describing what is being looked up, such as
|
||||
\fBoption\fR. This string is included in error messages.
|
||||
.AP int flags in
|
||||
OR-ed combination of bits providing additional information for
|
||||
operation. The only bit that is currently defined is \fBTCL_EXACT\fR.
|
||||
.AP int *indexPtr out
|
||||
The index of the string in \fItablePtr\fR that matches the value of
|
||||
\fIobjPtr\fR is returned here.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure provides an efficient way for looking up keywords,
|
||||
switch names, option names, and similar things where the value of
|
||||
an object must be one of a predefined set of values.
|
||||
\fIObjPtr\fR is compared against each of
|
||||
the strings in \fItablePtr\fR to find a match. A match occurs if
|
||||
\fIobjPtr\fR's string value is identical to one of the strings in
|
||||
\fItablePtr\fR, or if it is a unique abbreviation
|
||||
for exactly one of the strings in \fItablePtr\fR and the
|
||||
\fBTCL_EXACT\fR flag was not specified; in either case
|
||||
the index of the matching entry is stored at \fI*indexPtr\fR
|
||||
and TCL_OK is returned.
|
||||
.PP
|
||||
If there is no matching entry,
|
||||
TCL_ERROR is returned and an error message is left in \fIinterp\fR's
|
||||
result if \fIinterp\fR isn't NULL. \fIMsg\fR is included in the
|
||||
error message to indicate what was being looked up. For example,
|
||||
if \fImsg\fR is \fBoption\fR the error message will have a form like
|
||||
\fBbad option "firt": must be first, second, or third\fR.
|
||||
.PP
|
||||
If \fBTcl_GetIndexFromObj\fR completes successfully it modifies the
|
||||
internal representation of \fIobjPtr\fR to hold the address of
|
||||
the table and the index of the matching entry. If \fBTcl_GetIndexFromObj\fR
|
||||
is invoked again with the same \fIobjPtr\fR and \fItablePtr\fR
|
||||
arguments (e.g. during a reinvocation of a Tcl command), it returns
|
||||
the matching index immediately without having to redo the lookup
|
||||
operation. Note: \fBTcl_GetIndexFromObj\fR assumes that the entries
|
||||
in \fItablePtr\fR are static: they must not change between invocations.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_WrongNumArgs
|
||||
|
||||
.SH KEYWORDS
|
||||
index, object, table lookup
|
||||
@@ -1,81 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) GetInt.3 1.12 96/03/25 20:03:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_GetInt 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_GetInt, Tcl_GetDouble, Tcl_GetBoolean \- convert from string to integer, double, or boolean
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetInt\fR(\fIinterp, string, intPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetDouble\fR(\fIinterp, string, doublePtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetBoolean\fR(\fIinterp, string, boolPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *doublePtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter to use for error reporting.
|
||||
.AP char *string in
|
||||
Textual value to be converted.
|
||||
.AP int *intPtr out
|
||||
Points to place to store integer value converted from \fIstring\fR.
|
||||
.AP double *doublePtr out
|
||||
Points to place to store double-precision floating-point
|
||||
value converted from \fIstring\fR.
|
||||
.AP int *boolPtr out
|
||||
Points to place to store boolean value (0 or 1) converted from \fIstring\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures convert from strings to integers or double-precision
|
||||
floating-point values or booleans (represented as 0- or 1-valued
|
||||
integers). Each of the procedures takes a \fIstring\fR argument,
|
||||
converts it to an internal form of a particular type, and stores
|
||||
the converted value at the location indicated by the procedure's
|
||||
third argument. If all goes well, each of the procedures returns
|
||||
TCL_OK. If \fIstring\fR doesn't have the proper syntax for the
|
||||
desired type then TCL_ERROR is returned, an error message is left
|
||||
in \fIinterp->result\fR, and nothing is stored at *\fIintPtr\fR
|
||||
or *\fIdoublePtr\fR or *\fIboolPtr\fR.
|
||||
.PP
|
||||
\fBTcl_GetInt\fR expects \fIstring\fR to consist of a collection
|
||||
of integer digits, optionally signed and optionally preceded by
|
||||
white space. If the first two characters of \fIstring\fR are ``0x''
|
||||
then \fIstring\fR is expected to be in hexadecimal form; otherwise,
|
||||
if the first character of \fIstring\fR is ``0'' then \fIstring\fR
|
||||
is expected to be in octal form; otherwise, \fIstring\fR is
|
||||
expected to be in decimal form.
|
||||
.PP
|
||||
\fBTcl_GetDouble\fR expects \fIstring\fR to consist of a floating-point
|
||||
number, which is: white space; a sign; a sequence of digits; a
|
||||
decimal point; a sequence of digits; the letter ``e''; and a
|
||||
signed decimal exponent. Any of the fields may be omitted, except that
|
||||
the digits either before or after the decimal point must be present
|
||||
and if the ``e'' is present then it must be followed by the
|
||||
exponent number.
|
||||
.PP
|
||||
\fBTcl_GetBoolean\fR expects \fIstring\fR to specify a boolean
|
||||
value. If \fIstring\fR is any of \fB0\fR, \fBfalse\fR,
|
||||
\fBno\fR, or \fBoff\fR, then \fBTcl_GetBoolean\fR stores a zero
|
||||
value at \fI*boolPtr\fR.
|
||||
If \fIstring\fR is any of \fB1\fR, \fBtrue\fR, \fByes\fR, or \fBon\fR,
|
||||
then 1 is stored at \fI*boolPtr\fR.
|
||||
Any of these values may be abbreviated, and upper-case spellings
|
||||
are also acceptable.
|
||||
|
||||
.SH KEYWORDS
|
||||
boolean, conversion, double, floating-point, integer
|
||||
@@ -1,61 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) GetOpnFl.3 1.3 97/04/23 16:14:43
|
||||
.so man.macros
|
||||
.TH Tcl_GetOpenFile 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_GetOpenFile \- Get a standard IO File * handle from a channel. (Unix only)
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetOpenFile\fR(\fIinterp, string, write, checkUsage, filePtr\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp checkUsage
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter from which file handle is to be obtained.
|
||||
.AP char *string in
|
||||
String identifying channel, such as \fBstdin\fR or \fBfile4\fR.
|
||||
.AP int write in
|
||||
Non-zero means the file will be used for writing, zero means it will
|
||||
be used for reading.
|
||||
.AP int checkUsage in
|
||||
If non-zero, then an error will be generated if the file wasn't opened
|
||||
for the access indicated by \fIwrite\fR.
|
||||
.AP ClientData *filePtr out
|
||||
Points to word in which to store pointer to FILE structure for
|
||||
the file given by \fIstring\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_GetOpenFile\fR takes as argument a file identifier of the form
|
||||
returned by the \fBopen\fR command and
|
||||
returns at \fI*filePtr\fR a pointer to the FILE structure for
|
||||
the file.
|
||||
The \fIwrite\fR argument indicates whether the FILE pointer will
|
||||
be used for reading or writing.
|
||||
In some cases, such as a channel that connects to a pipeline of
|
||||
subprocesses, different FILE pointers will be returned for reading
|
||||
and writing.
|
||||
\fBTcl_GetOpenFile\fR normally returns TCL_OK.
|
||||
If an error occurs in \fBTcl_GetOpenFile\fR (e.g. \fIstring\fR didn't
|
||||
make any sense or \fIcheckUsage\fR was set and the file wasn't opened
|
||||
for the access specified by \fIwrite\fR) then TCL_ERROR is returned
|
||||
and \fIinterp->result\fR will contain an error message.
|
||||
In the current implementation \fIcheckUsage\fR is ignored and consistency
|
||||
checks are always performed.
|
||||
.VS
|
||||
.PP
|
||||
Note that this interface is only supported on the Unix platform.
|
||||
.VE
|
||||
|
||||
.SH KEYWORDS
|
||||
channel, file handle, permissions, pipeline, read, write
|
||||
@@ -1,73 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996 by Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" @(#) GetStdChan.3 1.2 96/03/08 13:59:57
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_GetStdChannel 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_GetStdChannel, Tcl_SetStdChannel \- procedures for retrieving and replacing the standard channels
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_GetStdChannel\fR(\fItype\fR)
|
||||
.sp
|
||||
\fBTcl_SetStdChannel\fR(\fIchannel, type\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Channel channel in
|
||||
.AP int type in
|
||||
The identifier for the standard channel to retrieve or modify. Must be one of
|
||||
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR.
|
||||
.AP Tcl_Channel channel in
|
||||
The channel to use as the new value for the specified standard channel.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Tcl defines three special channels that are used by various I/O related
|
||||
commands if no other channels are specified. The standard input channel
|
||||
has a channel name of \fBstdin\fR and is used by \fBread\fR and \fBgets\fR.
|
||||
The standard output channel is named \fBstdout\fR and is used by
|
||||
\fBputs\fR. The standard error channel is named \fBstderr\fR and is used for
|
||||
reporting errors. In addition, the standard channels are inherited by any
|
||||
child processes created using \fBexec\fR or \fBopen\fR in the absence of any
|
||||
other redirections.
|
||||
.PP
|
||||
The standard channels are actually aliases for other normal channels. The
|
||||
current channel associated with a standard channel can be retrieved by calling
|
||||
\fBTcl_GetStdChannel\fR with one of
|
||||
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, or \fBTCL_STDERR\fR as the \fItype\fR. The
|
||||
return value will be a valid channel, or NULL.
|
||||
.PP
|
||||
A new channel can be set for the standard channel specified by \fItype\fR
|
||||
by calling \fBTcl_SetStdChannel\fR with a new channel or NULL in the
|
||||
\fIchannel\fR argument. If the specified channel is closed by a later call to
|
||||
\fBTcl_Close\fR, then the corresponding standard channel will automatically be
|
||||
set to NULL.
|
||||
.PP
|
||||
If \fBTcl_GetStdChannel\fR is called before \fBTcl_SetStdChannel\fR, Tcl will
|
||||
construct a new channel to wrap the appropriate platform-specific standard
|
||||
file handle. If \fBTcl_SetStdChannel\fR is called before
|
||||
\fBTcl_GetStdChannel\fR, then the default channel will not be created.
|
||||
.PP
|
||||
If one of the standard channels is set to NULL, either by calling
|
||||
\fBTcl_SetStdChannel\fR with a null \fIchannel\fR argument, or by calling
|
||||
\fBTcl_Close\fR on the channel, then the next call to \fBTcl_CreateChannel\fR
|
||||
will automatically set the standard channel with the newly created channel. If
|
||||
more than one standard channel is NULL, then the standard channels will be
|
||||
assigned starting with standard input, followed by standard output, with
|
||||
standard error being last.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_Close(3), Tcl_CreateChannel(3)
|
||||
|
||||
.SH KEYWORDS
|
||||
standard channel, standard input, standard output, standard error
|
||||
@@ -1,208 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Hash.3 1.15 96/03/25 20:04:01
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Hash 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_InitHashTable, Tcl_DeleteHashTable, Tcl_CreateHashEntry, Tcl_DeleteHashEntry, Tcl_FindHashEntry, Tcl_GetHashValue, Tcl_SetHashValue, Tcl_GetHashKey, Tcl_FirstHashEntry, Tcl_NextHashEntry, Tcl_HashStats \- procedures to manage hash tables
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_InitHashTable\fR(\fItablePtr, keyType\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteHashTable\fR(\fItablePtr\fR)
|
||||
.sp
|
||||
Tcl_HashEntry *
|
||||
\fBTcl_CreateHashEntry\fR(\fItablePtr, key, newPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DeleteHashEntry\fR(\fIentryPtr\fR)
|
||||
.sp
|
||||
Tcl_HashEntry *
|
||||
\fBTcl_FindHashEntry\fR(\fItablePtr, key\fR)
|
||||
.sp
|
||||
ClientData
|
||||
\fBTcl_GetHashValue\fR(\fIentryPtr\fR)
|
||||
.sp
|
||||
\fBTcl_SetHashValue\fR(\fIentryPtr, value\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetHashKey\fR(\fItablePtr, entryPtr\fR)
|
||||
.sp
|
||||
Tcl_HashEntry *
|
||||
\fBTcl_FirstHashEntry\fR(\fItablePtr, searchPtr\fR)
|
||||
.sp
|
||||
Tcl_HashEntry *
|
||||
\fBTcl_NextHashEntry\fR(\fIsearchPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_HashStats\fR(\fItablePtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_HashSearch *searchPtr
|
||||
.AP Tcl_HashTable *tablePtr in
|
||||
Address of hash table structure (for all procedures but
|
||||
\fBTcl_InitHashTable\fR, this must have been initialized by
|
||||
previous call to \fBTcl_InitHashTable\fR).
|
||||
.AP int keyType in
|
||||
Kind of keys to use for new hash table. Must be either
|
||||
TCL_STRING_KEYS, TCL_ONE_WORD_KEYS, or an integer value
|
||||
greater than 1.
|
||||
.AP char *key in
|
||||
Key to use for probe into table. Exact form depends on
|
||||
\fIkeyType\fR used to create table.
|
||||
.AP int *newPtr out
|
||||
The word at \fI*newPtr\fR is set to 1 if a new entry was created
|
||||
and 0 if there was already an entry for \fIkey\fR.
|
||||
.AP Tcl_HashEntry *entryPtr in
|
||||
Pointer to hash table entry.
|
||||
.AP ClientData value in
|
||||
New value to assign to hash table entry. Need not have type
|
||||
ClientData, but must fit in same space as ClientData.
|
||||
.AP Tcl_HashSearch *searchPtr in
|
||||
Pointer to record to use to keep track of progress in enumerating
|
||||
all the entries in a hash table.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
A hash table consists of zero or more entries, each consisting of
|
||||
a key and a value.
|
||||
Given the key for an entry, the hashing routines can very quickly
|
||||
locate the entry, and hence its value.
|
||||
There may be at most one entry in a hash table with a
|
||||
particular key, but many entries may have the same value.
|
||||
Keys can take one of three forms: strings,
|
||||
one-word values, or integer arrays.
|
||||
All of the keys in a given table have the same form, which is
|
||||
specified when the table is initialized.
|
||||
.PP
|
||||
The value of a hash table entry can be anything that fits in
|
||||
the same space as a ``char *'' pointer.
|
||||
Values for hash table entries are managed entirely by clients,
|
||||
not by the hash module itself.
|
||||
Typically each entry's value is a pointer to a data structure
|
||||
managed by client code.
|
||||
.PP
|
||||
Hash tables grow gracefully as the number of entries increases,
|
||||
so that there are always less than three entries per hash bucket,
|
||||
on average.
|
||||
This allows for fast lookups regardless of the number of entries
|
||||
in a table.
|
||||
.PP
|
||||
\fBTcl_InitHashTable\fR initializes a structure that describes
|
||||
a new hash table.
|
||||
The space for the structure is provided by the caller, not by
|
||||
the hash module.
|
||||
The value of \fIkeyType\fR indicates what kinds of keys will
|
||||
be used for all entries in the table. \fIKeyType\fR must have
|
||||
one of the following values:
|
||||
.IP \fBTCL_STRING_KEYS\fR 25
|
||||
Keys are null-terminated ASCII strings.
|
||||
They are passed to hashing routines using the address of the
|
||||
first character of the string.
|
||||
.IP \fBTCL_ONE_WORD_KEYS\fR 25
|
||||
Keys are single-word values; they are passed to hashing routines
|
||||
and stored in hash table entries as ``char *'' values.
|
||||
The pointer value is the key; it need not (and usually doesn't)
|
||||
actually point to a string.
|
||||
.IP \fIother\fR 25
|
||||
If \fIkeyType\fR is not TCL_STRING_KEYS or TCL_ONE_WORD_KEYS,
|
||||
then it must be an integer value greater than 1.
|
||||
In this case the keys will be arrays of ``int'' values, where
|
||||
\fIkeyType\fR gives the number of ints in each key.
|
||||
This allows structures to be used as keys.
|
||||
All keys must have the same size.
|
||||
Array keys are passed into hashing functions using the address
|
||||
of the first int in the array.
|
||||
.PP
|
||||
\fBTcl_DeleteHashTable\fR deletes all of the entries in a hash
|
||||
table and frees up the memory associated with the table's
|
||||
bucket array and entries.
|
||||
It does not free the actual table structure (pointed to
|
||||
by \fItablePtr\fR), since that memory is assumed to be managed
|
||||
by the client.
|
||||
\fBTcl_DeleteHashTable\fR also does not free or otherwise
|
||||
manipulate the values of the hash table entries.
|
||||
If the entry values point to dynamically-allocated memory, then
|
||||
it is the client's responsibility to free these structures
|
||||
before deleting the table.
|
||||
.PP
|
||||
\fBTcl_CreateHashEntry\fR locates the entry corresponding to a
|
||||
particular key, creating a new entry in the table if there
|
||||
wasn't already one with the given key.
|
||||
If an entry already existed with the given key then \fI*newPtr\fR
|
||||
is set to zero.
|
||||
If a new entry was created, then \fI*newPtr\fR is set to a non-zero
|
||||
value and the value of the new entry will be set to zero.
|
||||
The return value from \fBTcl_CreateHashEntry\fR is a pointer to
|
||||
the entry, which may be used to retrieve and modify the entry's
|
||||
value or to delete the entry from the table.
|
||||
.PP
|
||||
\fBTcl_DeleteHashEntry\fR will remove an existing entry from a
|
||||
table.
|
||||
The memory associated with the entry itself will be freed, but
|
||||
the client is responsible for any cleanup associated with the
|
||||
entry's value, such as freeing a structure that it points to.
|
||||
.PP
|
||||
\fBTcl_FindHashEntry\fR is similar to \fBTcl_CreateHashEntry\fR
|
||||
except that it doesn't create a new entry if the key doesn't exist;
|
||||
instead, it returns NULL as result.
|
||||
.PP
|
||||
\fBTcl_GetHashValue\fR and \fBTcl_SetHashValue\fR are used to
|
||||
read and write an entry's value, respectively.
|
||||
Values are stored and retrieved as type ``ClientData'', which is
|
||||
large enough to hold a pointer value. On almost all machines this is
|
||||
large enough to hold an integer value too.
|
||||
.PP
|
||||
\fBTcl_GetHashKey\fR returns the key for a given hash table entry,
|
||||
either as a pointer to a string, a one-word (``char *'') key, or
|
||||
as a pointer to the first word of an array of integers, depending
|
||||
on the \fIkeyType\fR used to create a hash table.
|
||||
In all cases \fBTcl_GetHashKey\fR returns a result with type
|
||||
``char *''.
|
||||
When the key is a string or array, the result of \fBTcl_GetHashKey\fR
|
||||
points to information in the table entry; this information will
|
||||
remain valid until the entry is deleted or its table is deleted.
|
||||
.PP
|
||||
\fBTcl_FirstHashEntry\fR and \fBTcl_NextHashEntry\fR may be used
|
||||
to scan all of the entries in a hash table.
|
||||
A structure of type ``Tcl_HashSearch'', provided by the client,
|
||||
is used to keep track of progress through the table.
|
||||
\fBTcl_FirstHashEntry\fR initializes the search record and
|
||||
returns the first entry in the table (or NULL if the table is
|
||||
empty).
|
||||
Each subsequent call to \fBTcl_NextHashEntry\fR returns the
|
||||
next entry in the table or
|
||||
NULL if the end of the table has been reached.
|
||||
A call to \fBTcl_FirstHashEntry\fR followed by calls to
|
||||
\fBTcl_NextHashEntry\fR will return each of the entries in
|
||||
the table exactly once, in an arbitrary order.
|
||||
It is unadvisable to modify the structure of the table, e.g.
|
||||
by creating or deleting entries, while the search is in
|
||||
progress.
|
||||
.PP
|
||||
\fBTcl_HashStats\fR returns a dynamically-allocated string with
|
||||
overall information about a hash table, such as the number of
|
||||
entries it contains, the number of buckets in its hash array,
|
||||
and the utilization of the buckets.
|
||||
It is the caller's responsibility to free the result string
|
||||
by passing it to \fBfree\fR.
|
||||
.PP
|
||||
The header file \fBtcl.h\fR defines the actual data structures
|
||||
used to implement hash tables.
|
||||
This is necessary so that clients can allocate Tcl_HashTable
|
||||
structures and so that macros can be used to read and write
|
||||
the values of entries.
|
||||
However, users of the hashing routines should never refer directly
|
||||
to any of the fields of any of the hash-related data structures;
|
||||
use the procedures and macros defined here.
|
||||
|
||||
.SH KEYWORDS
|
||||
hash table, key, lookup, search, value
|
||||
@@ -1,104 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) IntObj.3 1.7 97/05/08 19:49:22
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_IntObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_NewIntObj, Tcl_NewLongObj, Tcl_SetIntObj, Tcl_SetLongObj, Tcl_GetIntFromObj, Tcl_GetLongFromObj \- manipulate Tcl objects as integers
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewIntObj\fR(\fIintValue\fR)
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewLongObj\fR(\fIlongValue\fR)
|
||||
.sp
|
||||
\fBTcl_SetIntObj\fR(\fIobjPtr, intValue\fR)
|
||||
.sp
|
||||
\fBTcl_SetLongObj\fR(\fIobjPtr, longValue\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetIntFromObj\fR(\fIinterp, objPtr, intPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetLongFromObj\fR(\fIinterp, objPtr, longPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP int intValue in
|
||||
Integer value used to initialize or set an integer object.
|
||||
.AP long longValue in
|
||||
Long integer value used to initialize or set an integer object.
|
||||
.AP Tcl_Obj *objPtr in/out
|
||||
For \fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR,
|
||||
this points to the object to be converted to integer type.
|
||||
For \fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR,
|
||||
this refers to the object
|
||||
from which to get an integer or long integer value;
|
||||
if \fIobjPtr\fR does not already point to an integer object,
|
||||
an attempt will be made to convert it to one.
|
||||
.AP Tcl_Interp *interp in/out
|
||||
If an error occurs during conversion,
|
||||
an error message is left in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
.AP int *intPtr out
|
||||
Points to place to store the integer value
|
||||
obtained by \fBTcl_GetIntFromObj\fR from \fIobjPtr\fR.
|
||||
.AP long *longPtr out
|
||||
Points to place to store the long integer value
|
||||
obtained by \fBTcl_GetLongFromObj\fR from \fIobjPtr\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures are used to create, modify, and read
|
||||
integer Tcl objects from C code.
|
||||
\fBTcl_NewIntObj\fR, \fBTcl_NewLongObj\fR,
|
||||
\fBTcl_SetIntObj\fR, and \fBTcl_SetLongObj\fR
|
||||
create a new object of integer type
|
||||
or modify an existing object to have integer type.
|
||||
\fBTcl_NewIntObj\fR and \fBTcl_SetIntObj\fR set the object to have the
|
||||
integer value given by \fIintValue\fR,
|
||||
while \fBTcl_NewLongObj\fR and \fBTcl_SetLongObj\fR
|
||||
set the object to have the
|
||||
long integer value given by \fIlongValue\fR.
|
||||
\fBTcl_NewIntObj\fR and \fBTcl_NewLongObj\fR
|
||||
return a pointer to a newly created object with reference count zero.
|
||||
These procedures set the object's type to be integer
|
||||
and assign the integer value to the object's internal representation
|
||||
\fIlongValue\fR member.
|
||||
\fBTcl_SetIntObj\fR and \fBTcl_SetLongObj\fR
|
||||
invalidate any old string representation and,
|
||||
if the object is not already an integer object,
|
||||
free any old internal representation.
|
||||
.PP
|
||||
\fBTcl_GetIntFromObj\fR and \fBTcl_GetLongFromObj\fR
|
||||
attempt to return an integer value from the Tcl object \fIobjPtr\fR.
|
||||
If the object is not already an integer object,
|
||||
they will attempt to convert it to one.
|
||||
If an error occurs during conversion, they return \fBTCL_ERROR\fR
|
||||
and leave an error message in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
Also, if the long integer held in the object's internal representation
|
||||
\fIlongValue\fR member can not be represented in a (non-long) integer,
|
||||
\fBTcl_GetIntFromObj\fR returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
Otherwise, both procedures return \fBTCL_OK\fR and
|
||||
store the integer or the long integer value
|
||||
in the address given by \fIintPtr\fR and \fIlongPtr\fR respectively.
|
||||
If the object is not already an integer object,
|
||||
the conversion will free any old internal representation.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
integer, integer object, integer type, internal representation, object, object type, string representation
|
||||
@@ -1,125 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Interp.3 1.16 96/06/06 13:48:02
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Interp 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Interp \- client-visible fields of interpreter structures
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
typedef struct {
|
||||
char *\fIresult\fR;
|
||||
Tcl_FreeProc *\fIfreeProc\fR;
|
||||
int \fIerrorLine\fR;
|
||||
} Tcl_Interp;
|
||||
|
||||
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The \fBTcl_CreateInterp\fR procedure returns a pointer to a Tcl_Interp
|
||||
structure. This pointer is then passed into other Tcl procedures
|
||||
to process commands in the interpreter and perform other operations
|
||||
on the interpreter. Interpreter structures contain many many fields
|
||||
that are used by Tcl, but only three that may be accessed by
|
||||
clients: \fIresult\fR, \fIfreeProc\fR, and \fIerrorLine\fR.
|
||||
.PP
|
||||
The \fIresult\fR and \fIfreeProc\fR fields are used to return
|
||||
results or error messages from commands.
|
||||
This information is returned by command procedures back to \fBTcl_Eval\fR,
|
||||
and by \fBTcl_Eval\fR back to its callers.
|
||||
The \fIresult\fR field points to the string that represents the
|
||||
result or error message, and the \fIfreeProc\fR field tells how
|
||||
to dispose of the storage for the string when it isn't needed anymore.
|
||||
The easiest way for command procedures to manipulate these
|
||||
fields is to call procedures like \fBTcl_SetResult\fR
|
||||
or \fBTcl_AppendResult\fR; they
|
||||
will hide all the details of managing the fields.
|
||||
The description below is for those procedures that manipulate the
|
||||
fields directly.
|
||||
.PP
|
||||
Whenever a command procedure returns, it must ensure
|
||||
that the \fIresult\fR field of its interpreter points to the string
|
||||
being returned by the command.
|
||||
The \fIresult\fR field must always point to a valid string.
|
||||
If a command wishes to return no result then \fIinterp->result\fR
|
||||
should point to an empty string.
|
||||
Normally, results are assumed to be statically allocated,
|
||||
which means that the contents will not change before the next time
|
||||
\fBTcl_Eval\fR is called or some other command procedure is invoked.
|
||||
.VS
|
||||
In this case, the \fIfreeProc\fR field must be zero.
|
||||
Alternatively, a command procedure may dynamically
|
||||
allocate its return value (e.g. using \fBTcl_Alloc\fR)
|
||||
and store a pointer to it in \fIinterp->result\fR.
|
||||
In this case, the command procedure must also set \fIinterp->freeProc\fR
|
||||
to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
|
||||
if the storage was allocated directly by Tcl or by a call to
|
||||
\fBTcl_Alloc\fR.
|
||||
.VE
|
||||
If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
|
||||
to free the space pointed to by \fIinterp->result\fR before it
|
||||
invokes the next command.
|
||||
If a client procedure overwrites \fIinterp->result\fR when
|
||||
\fIinterp->freeProc\fR is non-zero, then it is responsible for calling
|
||||
\fIfreeProc\fR to free the old \fIinterp->result\fR (the \fBTcl_FreeResult\fR
|
||||
macro should be used for this purpose).
|
||||
.PP
|
||||
\fIFreeProc\fR should have arguments and result that match the
|
||||
\fBTcl_FreeProc\fR declaration above: it receives a single
|
||||
argument which is a pointer to the result value to free.
|
||||
.VS
|
||||
In most applications \fBTCL_DYNAMIC\fR is the only non-zero value ever
|
||||
used for \fIfreeProc\fR.
|
||||
.VE
|
||||
However, an application may store a different procedure address
|
||||
in \fIfreeProc\fR in order to use an alternate memory allocator
|
||||
or in order to do other cleanup when the result memory is freed.
|
||||
.PP
|
||||
As part of processing each command, \fBTcl_Eval\fR initializes
|
||||
\fIinterp->result\fR
|
||||
and \fIinterp->freeProc\fR just before calling the command procedure for
|
||||
the command. The \fIfreeProc\fR field will be initialized to zero,
|
||||
and \fIinterp->result\fR will point to an empty string. Commands that
|
||||
do not return any value can simply leave the fields alone.
|
||||
Furthermore, the empty string pointed to by \fIresult\fR is actually
|
||||
part of an array of \fBTCL_RESULT_SIZE\fR characters (approximately 200).
|
||||
If a command wishes to return a short string, it can simply copy
|
||||
it to the area pointed to by \fIinterp->result\fR. Or, it can use
|
||||
the sprintf procedure to generate a short result string at the location
|
||||
pointed to by \fIinterp->result\fR.
|
||||
.PP
|
||||
It is a general convention in Tcl-based applications that the result
|
||||
of an interpreter is normally in the initialized state described
|
||||
in the previous paragraph.
|
||||
Procedures that manipulate an interpreter's result (e.g. by
|
||||
returning an error) will generally assume that the result
|
||||
has been initialized when the procedure is called.
|
||||
If such a procedure is to be called after the result has been
|
||||
changed, then \fBTcl_ResetResult\fR should be called first to
|
||||
reset the result to its initialized state.
|
||||
.PP
|
||||
The \fIerrorLine\fR
|
||||
field is valid only after \fBTcl_Eval\fR returns
|
||||
a \fBTCL_ERROR\fR return code. In this situation the \fIerrorLine\fR
|
||||
field identifies the line number of the command being executed when
|
||||
the error occurred. The line numbers are relative to the command
|
||||
being executed: 1 means the first line of the command passed to
|
||||
\fBTcl_Eval\fR, 2 means the second line, and so on.
|
||||
The \fIerrorLine\fR field is typically used in conjunction with
|
||||
\fBTcl_AddErrorInfo\fR to report information about where an error
|
||||
occurred.
|
||||
\fIErrorLine\fR should not normally be modified except by \fBTcl_Eval\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
free, initialized, interpreter, malloc, result
|
||||
@@ -1,115 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) LinkVar.3 1.15 96/09/05 17:16:57
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_LinkVar 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_LinkVar, Tcl_UnlinkVar, Tcl_UpdateLinkedVar \- link Tcl variable to C variable
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_LinkVar\fR(\fIinterp, varName, addr, type\fR)
|
||||
.sp
|
||||
\fBTcl_UnlinkVar\fR(\fIinterp, varName\fR)
|
||||
.sp
|
||||
\fBTcl_UpdateLinkedVar\fR(\fIinterp, varName\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp writable
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter that contains \fIvarName\fR.
|
||||
Also used by \fBTcl_LinkVar\fR to return error messages.
|
||||
.AP char *varName in
|
||||
Name of global variable. Must be in writable memory: Tcl may make
|
||||
temporary modifications to it while parsing the variable name.
|
||||
.AP char *addr in
|
||||
Address of C variable that is to be linked to \fIvarName\fR.
|
||||
.AP int type in
|
||||
Type of C variable. Must be one of TCL_LINK_INT, TCL_LINK_DOUBLE,
|
||||
TCL_LINK_BOOLEAN, or TCL_LINK_STRING, optionally OR'ed with
|
||||
TCL_LINK_READ_ONLY to make Tcl variable read-only.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_LinkVar\fR uses variable traces to keep the Tcl variable
|
||||
named by \fIvarName\fR in sync with the C variable at the address
|
||||
given by \fIaddr\fR.
|
||||
Whenever the Tcl variable is read the value of the C variable will
|
||||
be returned, and whenever the Tcl variable is written the C
|
||||
variable will be updated to have the same value.
|
||||
\fBTcl_LinkVar\fR normally returns TCL_OK; if an error occurs
|
||||
while setting up the link (e.g. because \fIvarName\fR is the
|
||||
name of array) then TCL_ERROR is returned and \fIinterp->result\fR
|
||||
contains an error message.
|
||||
.PP
|
||||
The \fItype\fR argument specifies the type of the C variable,
|
||||
and must have one of the following values, optionally OR'ed with
|
||||
TCL_LINK_READ_ONLY:
|
||||
.TP
|
||||
\fBTCL_LINK_INT\fR
|
||||
The C variable is of type \fBint\fR.
|
||||
Any value written into the Tcl variable must have a proper integer
|
||||
form acceptable to \fBTcl_GetInt\fR; attempts to write
|
||||
non-integer values into \fIvarName\fR will be rejected with
|
||||
Tcl errors.
|
||||
.TP
|
||||
\fBTCL_LINK_DOUBLE\fR
|
||||
The C variable is of type \fBdouble\fR.
|
||||
Any value written into the Tcl variable must have a proper real
|
||||
form acceptable to \fBTcl_GetDouble\fR; attempts to write
|
||||
non-real values into \fIvarName\fR will be rejected with
|
||||
Tcl errors.
|
||||
.TP
|
||||
\fBTCL_LINK_BOOLEAN\fR
|
||||
The C variable is of type \fBint\fR.
|
||||
If its value is zero then it will read from Tcl as ``0'';
|
||||
otherwise it will read from Tcl as ``1''.
|
||||
Whenever \fIvarName\fR is
|
||||
modified, the C variable will be set to a 0 or 1 value.
|
||||
Any value written into the Tcl variable must have a proper boolean
|
||||
form acceptable to \fBTcl_GetBoolean\fR; attempts to write
|
||||
non-boolean values into \fIvarName\fR will be rejected with
|
||||
Tcl errors.
|
||||
.TP
|
||||
\fBTCL_LINK_STRING\fR
|
||||
The C variable is of type \fBchar *\fR.
|
||||
.VS
|
||||
If its value is not null then it must be a pointer to a string
|
||||
allocated with \fBTcl_Alloc\fR.
|
||||
.VE
|
||||
Whenever the Tcl variable is modified the current C string will be
|
||||
freed and new memory will be allocated to hold a copy of the variable's
|
||||
new value.
|
||||
If the C variable contains a null pointer then the Tcl variable
|
||||
will read as ``NULL''.
|
||||
.PP
|
||||
If the TCL_LINK_READ_ONLY flag is present in \fItype\fR then the
|
||||
variable will be read-only from Tcl, so that its value can only be
|
||||
changed by modifying the C variable.
|
||||
Attempts to write the variable from Tcl will be rejected with errors.
|
||||
.PP
|
||||
\fBTcl_UnlinkVar\fR removes the link previously set up for the
|
||||
variable given by \fIvarName\fR. If there does not exist a link
|
||||
for \fIvarName\fR then the procedure has no effect.
|
||||
.PP
|
||||
\fBTcl_UpdateLinkedVar\fR may be invoked after the C variable has
|
||||
changed to force the Tcl variable to be updated immediately.
|
||||
In many cases this procedure is not needed, since any attempt to
|
||||
read the Tcl variable will return the latest value of the C variable.
|
||||
However, if a trace has been set on the Tcl variable (such as a
|
||||
Tk widget that wishes to display the value of the variable), the
|
||||
trace will not trigger when the C variable has changed.
|
||||
\fBTcl_UpdateLinkedVar\fR ensures that any traces on the Tcl
|
||||
variable are invoked.
|
||||
|
||||
.SH KEYWORDS
|
||||
boolean, integer, link, read-only, real, string, traces, variable
|
||||
@@ -1,249 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) ListObj.3 1.10 97/10/08 11:36:58
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_ListObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_ListObjAppendList, Tcl_ListObjAppendElement, Tcl_NewListObj, Tcl_SetListObj, Tcl_ListObjGetElements, Tcl_ListObjLength, Tcl_ListObjIndex, Tcl_ListObjReplace \- manipulate Tcl objects as lists
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjAppendList\fR(\fIinterp, listPtr, elemListPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjAppendElement\fR(\fIinterp, listPtr, objPtr\fR)
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewListObj\fR(\fIobjc, objv\fR)
|
||||
.sp
|
||||
\fBTcl_SetListObj\fR(\fIobjPtr, objc, objv\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjGetElements\fR(\fIinterp, listPtr, objcPtr, objvPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjLength\fR(\fIinterp, listPtr, intPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjIndex\fR(\fIinterp, listPtr, index, objPtrPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ListObjReplace\fR(\fIinterp, listPtr, first, count, objc, objv\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp "*CONST objv[]" out
|
||||
.AP Tcl_Interp *interp in
|
||||
If an error occurs while converting an object to be a list object,
|
||||
an error message is left in the interpreter's result object
|
||||
unless \fIinterp\fR is NULL.
|
||||
.AP Tcl_Obj *listPtr in/out
|
||||
Points to the list object to be manipulated.
|
||||
If \fIlistPtr\fR does not already point to a list object,
|
||||
an attempt will be made to convert it to one.
|
||||
.AP Tcl_Obj *elemListPtr in/out
|
||||
For \fBTcl_ListObjAppendList\fR, this points to a list object
|
||||
containing elements to be appended onto \fIlistPtr\fR.
|
||||
Each element of *\fIelemListPtr\fR will
|
||||
become a new element of \fIlistPtr\fR.
|
||||
If *\fIelemListPtr\fR is not NULL and
|
||||
does not already point to a list object,
|
||||
an attempt will be made to convert it to one.
|
||||
.AP Tcl_Obj *objPtr in
|
||||
For \fBTcl_ListObjAppendElement\fR,
|
||||
points to the Tcl object that will be appended to \fIlistPtr\fR.
|
||||
For \fBTcl_SetListObj\fR,
|
||||
this points to the Tcl object that will be converted to a list object
|
||||
containing the \fIobjc\fR elements of the array referenced by \fIobjv\fR.
|
||||
.AP int *objcPtr in
|
||||
Points to location where \fBTcl_ListObjGetElements\fR
|
||||
stores the number of element objects in \fIlistPtr\fR.
|
||||
.AP Tcl_Obj ***objvPtr out
|
||||
A location where \fBTcl_ListObjGetElements\fR stores a pointer to an array
|
||||
of pointers to the element objects of \fIlistPtr\fR.
|
||||
.AP int objc in
|
||||
The number of Tcl objects that \fBTcl_NewListObj\fR
|
||||
will insert into a new list object,
|
||||
and \fBTcl_ListObjReplace\fR will insert into \fIlistPtr\fR.
|
||||
For \fBTcl_SetListObj\fR,
|
||||
the number of Tcl objects to insert into \fIobjPtr\fR.
|
||||
.VS
|
||||
.TP
|
||||
Tcl_Obj *CONST \fIobjv\fR[] (in)
|
||||
.
|
||||
An array of pointers to objects.
|
||||
\fBTcl_NewListObj\fR will insert these objects into a new list object
|
||||
and \fBTcl_ListObjReplace\fR will insert them into an existing \fIlistPtr\fR.
|
||||
Each object will become a separate list element.
|
||||
.VE
|
||||
.AP int *intPtr out
|
||||
Points to location where \fBTcl_ListObjLength\fR
|
||||
stores the length of the list.
|
||||
.AP int index in
|
||||
Index of the list element that \fBTcl_ListObjIndex\fR
|
||||
is to return.
|
||||
The first element has index 0.
|
||||
.AP Tcl_Obj **objPtrPtr out
|
||||
Points to place where \fBTcl_ListObjIndex\fR is to store
|
||||
a pointer to the resulting list element object.
|
||||
.AP int first in
|
||||
Index of the starting list element that \fBTcl_ListObjReplace\fR
|
||||
is to replace.
|
||||
The list's first element has index 0.
|
||||
.AP int count in
|
||||
The number of elements that \fBTcl_ListObjReplace\fR
|
||||
is to replace.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Tcl list objects have an internal representation that supports
|
||||
the efficient indexing and appending.
|
||||
The procedures described in this man page are used to
|
||||
create, modify, index, and append to Tcl list objects from C code.
|
||||
.PP
|
||||
\fBTcl_ListObjAppendList\fR and \fBTcl_ListObjAppendElement\fR
|
||||
both add one or more objects
|
||||
to the end of the list object referenced by \fIlistPtr\fR.
|
||||
\fBTcl_ListObjAppendList\fR appends each element of the list object
|
||||
referenced by \fIelemListPtr\fR while
|
||||
\fBTcl_ListObjAppendElement\fR appends the single object
|
||||
referenced by \fIobjPtr\fR.
|
||||
Both procedures will convert the object referenced by \fIlistPtr\fR
|
||||
to a list object if necessary.
|
||||
If an error occurs during conversion,
|
||||
both procedures return \fBTCL_ERROR\fR and leave an error message
|
||||
in the interpreter's result object if \fIinterp\fR is not NULL.
|
||||
Similarly, if \fIelemListPtr\fR does not already refer to a list object,
|
||||
\fBTcl_ListObjAppendList\fR will attempt to convert it to one
|
||||
and if an error occurs during conversion,
|
||||
will return \fBTCL_ERROR\fR
|
||||
and leave an error message in the interpreter's result object
|
||||
if interp is not NULL.
|
||||
Both procedures invalidate any old string representation of \fIlistPtr\fR
|
||||
and, if it was converted to a list object,
|
||||
free any old internal representation.
|
||||
Similarly, \fBTcl_ListObjAppendList\fR frees any old internal representation
|
||||
of \fIelemListPtr\fR if it converts it to a list object.
|
||||
After appending each element in \fIelemListPtr\fR,
|
||||
\fBTcl_ListObjAppendList\fR increments the element's reference count
|
||||
since \fIlistPtr\fR now also refers to it.
|
||||
For the same reason, \fBTcl_ListObjAppendElement\fR
|
||||
increments \fIobjPtr\fR's reference count.
|
||||
If no error occurs,
|
||||
the two procedures return \fBTCL_OK\fR after appending the objects.
|
||||
.PP
|
||||
\fBTcl_NewListObj\fR and \fBTcl_SetListObj\fR
|
||||
create a new object or modify an existing object to hold
|
||||
the \fIobjc\fR elements of the array referenced by \fIobjv\fR
|
||||
where each element is a pointer to a Tcl object.
|
||||
If \fIobjc\fR is less than or equal to zero,
|
||||
they return an empty object.
|
||||
The new object's string representation is left invalid.
|
||||
The two procedures increment the reference counts
|
||||
of the elements in \fIobjc\fR since the list object now refers to them.
|
||||
The new list object returned by \fBTcl_NewListObj\fR
|
||||
has reference count zero.
|
||||
.PP
|
||||
\fBTcl_ListObjGetElements\fR returns a count and
|
||||
a pointer to an array of the elements in a list object.
|
||||
It returns the count by storing it in the address \fIobjcPtr\fR.
|
||||
Similarly, it returns the array pointer by storing it
|
||||
in the address \fIobjvPtr\fR.
|
||||
If \fIlistPtr\fR is not already a list object,
|
||||
\fBTcl_ListObjGetElements\fR will attempt to convert it to one;
|
||||
if the conversion fails, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
if \fIinterp\fR is not NULL.
|
||||
Otherwise it returns \fBTCL_OK\fR after storing the count and array pointer.
|
||||
.PP
|
||||
\fBTcl_ListObjLength\fR returns the number of elements in the list object
|
||||
referenced by \fIlistPtr\fR.
|
||||
It returns this count by storing an integer in the address \fIintPtr\fR.
|
||||
If the object is not already a list object,
|
||||
\fBTcl_ListObjLength\fR will attempt to convert it to one;
|
||||
if the conversion fails, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
if \fIinterp\fR is not NULL.
|
||||
Otherwise it returns \fBTCL_OK\fR after storing the list's length.
|
||||
.PP
|
||||
The procedure \fBTcl_ListObjIndex\fR returns a pointer to the object
|
||||
at element \fIindex\fR in the list referenced by \fIlistPtr\fR.
|
||||
It returns this object by storing a pointer to it
|
||||
in the address \fIobjPtrPtr\fR.
|
||||
If \fIlistPtr\fR does not already refer to a list object,
|
||||
\fBTcl_ListObjIndex\fR will attempt to convert it to one;
|
||||
if the conversion fails, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
if \fIinterp\fR is not NULL.
|
||||
If the index is out of range,
|
||||
that is, \fIindex\fR is negative or
|
||||
greater than or equal to the number of elements in the list,
|
||||
\fBTcl_ListObjIndex\fR stores a NULL in \fIobjPtrPtr\fR
|
||||
and returns \fBTCL_OK\fR.
|
||||
Otherwise it returns \fBTCL_OK\fR after storing the element's
|
||||
object pointer.
|
||||
The reference count for the list element is not incremented;
|
||||
the caller must do that if it needs to retain a pointer to the element.
|
||||
.PP
|
||||
\fBTcl_ListObjReplace\fR replaces zero or more elements
|
||||
of the list referenced by \fIlistPtr\fR
|
||||
with the \fIobjc\fR objects in the array referenced by \fIobjv\fR.
|
||||
If \fIlistPtr\fR does not point to a list object,
|
||||
\fBTcl_ListObjReplace\fR will attempt to convert it to one;
|
||||
if the conversion fails, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the interpreter's result object
|
||||
if \fIinterp\fR is not NULL.
|
||||
Otherwise, it returns \fBTCL_OK\fR after replacing the objects.
|
||||
If \fIobjv\fR is NULL, no new elements are added.
|
||||
If the argument \fIfirst\fR is zero or negative,
|
||||
it refers to the first element.
|
||||
If \fIfirst\fR is greater than or equal to the
|
||||
number of elements in the list, then no elements are deleted;
|
||||
the new elements are appended to the list.
|
||||
\fIcount\fR gives the number of elements to replace.
|
||||
If \fIcount\fR is zero or negative then no elements are deleted;
|
||||
the new elements are simply inserted before the one
|
||||
designated by \fIfirst\fR.
|
||||
\fBTcl_ListObjReplace\fR invalidates \fIlistPtr\fR's
|
||||
old string representation.
|
||||
The reference counts of any elements inserted from \fIobjv\fR
|
||||
are incremented since the resulting list now refers to them.
|
||||
Similarly, the reference counts for any replaced objects are decremented.
|
||||
.PP
|
||||
Because \fBTcl_ListObjReplace\fR combines
|
||||
both element insertion and deletion,
|
||||
it can be used to implement a number of list operations.
|
||||
For example, the following code inserts the \fIobjc\fR objects
|
||||
referenced by the array of object pointers \fIobjv\fR
|
||||
just before the element \fIindex\fR of the list referenced by \fIlistPtr\fR:
|
||||
.CS
|
||||
result = Tcl_ListObjReplace(interp, listPtr, index, 0, objc, objv);
|
||||
.CE
|
||||
Similarly, the following code appends the \fIobjc\fR objects
|
||||
referenced by the array \fIobjv\fR
|
||||
to the end of the list \fIlistPtr\fR:
|
||||
.CS
|
||||
result = Tcl_ListObjLength(interp, listPtr, &length);
|
||||
if (result == TCL_OK) {
|
||||
result = Tcl_ListObjReplace(interp, listPtr, length, 0, objc, objv);
|
||||
}
|
||||
.CE
|
||||
The \fIcount\fR list elements starting at \fIfirst\fR can be deleted
|
||||
by simply calling \fBTcl_ListObjReplace\fR
|
||||
with a NULL \fIobjvPtr\fR:
|
||||
.CS
|
||||
result = Tcl_ListObjReplace(interp, listPtr, first, count, 0, NULL);
|
||||
.CE
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
append, index, insert, internal representation, length, list, list object, list type, object, object type, replace, string representation
|
||||
@@ -1,537 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Notifier.3 1.16 97/05/17 17:03:17
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Notifier 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.VS
|
||||
.SH NAME
|
||||
Tcl_CreateEventSource, Tcl_DeleteEventSource, Tcl_SetMaxBlockTime, Tcl_QueueEvent, Tcl_DeleteEvents, Tcl_WaitForEvent, Tcl_SetTimer, Tcl_ServiceAll, Tcl_ServiceEvent, Tcl_GetServiceMode, Tcl_SetServiceMode \- the event queue and notifier interfaces
|
||||
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_CreateEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
|
||||
.sp
|
||||
\fBTcl_DeleteEventSource\fR(\fIsetupProc, checkProc, clientData\fB)\fR
|
||||
.sp
|
||||
\fBTcl_SetMaxBlockTime\fR(\fItimePtr\fB)\fR
|
||||
.sp
|
||||
\fBTcl_QueueEvent\fR(\fIevPtr, position\fR)
|
||||
.VS
|
||||
.sp
|
||||
\fBTcl_DeleteEvents\fR(\fIdeleteProc, clientData\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_WaitForEvent\fR(\fItimePtr\fR)
|
||||
.sp
|
||||
\fBTcl_SetTimer\fR(\fItimePtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ServiceAll\fR()
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ServiceEvent\fR(\fIflags\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetServiceMode\fR()
|
||||
.sp
|
||||
int
|
||||
\fBTcl_SetServiceMode\fR(\fImode\fR)
|
||||
.VE
|
||||
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_EventDeleteProc milliseconds
|
||||
.AS Tcl_EventSetupProc *setupProc
|
||||
.AP Tcl_EventSetupProc *setupProc in
|
||||
Procedure to invoke to prepare for event wait in \fBTcl_DoOneEvent\fR.
|
||||
.AP Tcl_EventCheckProc *checkProc in
|
||||
Procedure for \fBTcl_DoOneEvent\fR to invoke after waiting for
|
||||
events. Checks to see if any events have occurred and, if so,
|
||||
queues them.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIsetupProc\fR, \fIcheckProc\fR, or
|
||||
\fIdeleteProc\fR.
|
||||
.AP Tcl_Time *timePtr in
|
||||
Indicates the maximum amount of time to wait for an event. This
|
||||
is specified as an interval (how long to wait), not an absolute
|
||||
time (when to wakeup). If the pointer passed to \fBTcl_WaitForEvent\fR
|
||||
is NULL, it means there is no maximum wait time: wait forever if
|
||||
necessary.
|
||||
.AP Tcl_Event *evPtr in
|
||||
An event to add to the event queue. The storage for the event must
|
||||
have been allocated by the caller using \fBTcl_Alloc\fR or \fBckalloc\fR.
|
||||
.AP Tcl_QueuePosition position in
|
||||
Where to add the new event in the queue: \fBTCL_QUEUE_TAIL\fR,
|
||||
\fBTCL_QUEUE_HEAD\fR, or \fBTCL_QUEUE_MARK\fR.
|
||||
.AP int flags in
|
||||
What types of events to service. These flags are the same as those
|
||||
passed to \fBTcl_DoOneEvent\fR.
|
||||
.AP Tcl_EventDeleteProc *deleteProc in
|
||||
Procedure to invoke for each queued event in \fBTcl_DeleteEvents\fR.
|
||||
.VS
|
||||
.AP int mode in
|
||||
Inidicates whether events should be serviced by \fBTcl_ServiceAll\fR.
|
||||
Must be one of \fBTCL_SERVICE_NONE\fR or \fBTCL_SERVICE_ALL\fR.
|
||||
.VE
|
||||
.BE
|
||||
|
||||
.SH INTRODUCTION
|
||||
.PP
|
||||
.VS
|
||||
The interfaces described here are used to customize the Tcl event
|
||||
loop. The two most common customizations are to add new sources of
|
||||
events and to merge Tcl's event loop with some other event loop, such
|
||||
as one provided by an application in which Tcl is embedded. Each of
|
||||
these tasks is described in a separate section below.
|
||||
.VE
|
||||
.PP
|
||||
The procedures in this manual entry are the building blocks out of which
|
||||
the Tcl event notifier is constructed. The event notifier is the lowest
|
||||
layer in the Tcl event mechanism. It consists of three things:
|
||||
.IP [1]
|
||||
Event sources: these represent the ways in which events can be
|
||||
generated. For example, there is a timer event source that implements
|
||||
the \fBTcl_CreateTimerHandler\fR procedure and the \fBafter\fR
|
||||
command, and there is a file event source that implements the
|
||||
\fBTcl_CreateFileHandler\fR procedure on Unix systems. An event
|
||||
source must work with the notifier to detect events at the right
|
||||
times, record them on the event queue, and eventually notify
|
||||
higher-level software that they have occurred. The procedures
|
||||
\fBTcl_CreateEventSource\fR, \fBTcl_DeleteEventSource\fR,
|
||||
and \fBTcl_SetMaxBlockTime\fR, \fBTcl_QueueEvent\fR, and
|
||||
\fBTcl_DeleteEvents\fR are used primarily by event sources.
|
||||
.IP [2]
|
||||
The event queue: there is a single queue for the whole application,
|
||||
containing events that have been detected but not yet serviced. Event
|
||||
sources place events onto the queue so that they may be processed in
|
||||
order at appropriate times during the event loop. The event queue
|
||||
guarantees a fair discipline of event handling, so that no event
|
||||
source can starve the others. It also allows events to be saved for
|
||||
servicing at a future time.
|
||||
.VS
|
||||
\fBTcl_QueueEvent\fR is used (primarily
|
||||
by event sources) to add events to the event queue and
|
||||
\fBTcl_DeleteEvents\fR is used to remove events from the queue without
|
||||
processing them.
|
||||
.IP [3]
|
||||
The event loop: in order to detect and process events, the application
|
||||
enters a loop that waits for events to occur, places them on the event
|
||||
queue, and then processes them. Most applications will do this by
|
||||
calling the procedure \fBTcl_DoOneEvent\fR, which is described in a
|
||||
separate manual entry.
|
||||
.PP
|
||||
Most Tcl applications need not worry about any of the internals of
|
||||
the Tcl notifier. However, the notifier now has enough flexibility
|
||||
to be retargeted either for a new platform or to use an external event
|
||||
loop (such as the Motif event loop, when Tcl is embedded in a Motif
|
||||
application). The procedures \fBTcl_WaitForEvent\fR and
|
||||
\fBTcl_SetTimer\fR are normally implemented by Tcl, but may be
|
||||
replaced with new versions to retarget the notifier (the \fBTcl_Sleep\fR,
|
||||
\fBTcl_CreateFileHandler\fR, and \fBTcl_DeleteFileHandler\fR must
|
||||
also be replaced; see CREATING A NEW NOTIFIER below for details).
|
||||
The procedures \fBTcl_ServiceAll\fR, \fBTcl_ServiceEvent\fR,
|
||||
\fBTcl_GetServiceMode\fR, and \fBTcl_SetServiceMode\fR are provided
|
||||
to help connect Tcl's event loop to an external event loop such as
|
||||
Motif's.
|
||||
.SH "NOTIFIER BASICS"
|
||||
.VE
|
||||
.PP
|
||||
The easiest way to understand how the notifier works is to consider
|
||||
what happens when \fBTcl_DoOneEvent\fR is called.
|
||||
\fBTcl_DoOneEvent\fR is passed a \fIflags\fR argument that indicates
|
||||
what sort of events it is OK to process and also whether or not to
|
||||
block if no events are ready. \fBTcl_DoOneEvent\fR does the following
|
||||
things:
|
||||
.IP [1]
|
||||
Check the event queue to see if it contains any events that can
|
||||
be serviced. If so, service the first possible event, remove it
|
||||
.VS
|
||||
from the queue, and return. It does this by calling
|
||||
\fBTcl_ServiceEvent\fR and passing in the \fIflags\fR argument.
|
||||
.VE
|
||||
.IP [2]
|
||||
Prepare to block for an event. To do this, \fBTcl_DoOneEvent\fR
|
||||
invokes a \fIsetup procedure\fR in each event source.
|
||||
The event source will perform event-source specific initialization and
|
||||
.VS
|
||||
possibly call \fBTcl_SetMaxBlockTime\fR to limit how long
|
||||
.VE
|
||||
\fBTcl_WaitForEvent\fR will block if no new events occur.
|
||||
.IP [3]
|
||||
Call \fBTcl_WaitForEvent\fR. This procedure is implemented differently
|
||||
on different platforms; it waits for an event to occur, based on the
|
||||
information provided by the event sources.
|
||||
It may cause the application to block if \fItimePtr\fR specifies
|
||||
an interval other than 0.
|
||||
\fBTcl_WaitForEvent\fR returns when something has happened,
|
||||
such as a file becoming readable or the interval given by \fItimePtr\fR
|
||||
expiring. If there are no events for \fBTcl_WaitForEvent\fR to
|
||||
wait for, so that it would block forever, then it returns immediately
|
||||
and \fBTcl_DoOneEvent\fR returns 0.
|
||||
.IP [4]
|
||||
Call a \fIcheck procedure\fR in each event source. The check
|
||||
procedure determines whether any events of interest to this source
|
||||
occurred. If so, the events are added to the event queue.
|
||||
.IP [5]
|
||||
Check the event queue to see if it contains any events that can
|
||||
be serviced. If so, service the first possible event, remove it
|
||||
from the queue, and return.
|
||||
.IP [6]
|
||||
See if there are idle callbacks pending. If so, invoke all of them and
|
||||
return.
|
||||
.IP [7]
|
||||
Either return 0 to indicate that no events were ready, or go back to
|
||||
step [2] if blocking was requested by the caller.
|
||||
|
||||
.SH "CREATING A NEW EVENT SOURCE"
|
||||
.PP
|
||||
An event source consists of three procedures invoked by the notifier,
|
||||
plus additional C procedures that are invoked by higher-level code
|
||||
to arrange for event-driven callbacks. The three procedures called
|
||||
by the notifier consist of the setup and check procedures described
|
||||
above, plus an additional procedure that is invoked when an event
|
||||
is removed from the event queue for servicing.
|
||||
.PP
|
||||
The procedure \fBTcl_CreateEventSource\fR creates a new event source.
|
||||
Its arguments specify the setup procedure and check procedure for
|
||||
the event source.
|
||||
\fISetupProc\fR should match the following prototype:
|
||||
.CS
|
||||
typedef void Tcl_EventSetupProc(
|
||||
ClientData \fIclientData\fR,
|
||||
int \fIflags\fR);
|
||||
.CE
|
||||
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||||
argument to \fBTcl_CreateEventSource\fR; it is typically used to
|
||||
point to private information managed by the event source.
|
||||
The \fIflags\fR argument will be the same as the \fIflags\fR
|
||||
argument passed to \fBTcl_DoOneEvent\fR except that it will never
|
||||
be 0 (\fBTcl_DoOneEvent\fR replaces 0 with \fBTCL_ALL_EVENTS\fR).
|
||||
\fIFlags\fR indicates what kinds of events should be considered;
|
||||
if the bit corresponding to this event source isn't set, the event
|
||||
source should return immediately without doing anything. For
|
||||
example, the file event source checks for the \fBTCL_FILE_EVENTS\fR
|
||||
bit.
|
||||
.PP
|
||||
\fISetupProc\fR's job is to make sure that the application wakes up
|
||||
when events of the desired type occur. This is typically done in a
|
||||
platform-dependent fashion. For example, under Unix an event source
|
||||
might call \fBTcl_CreateFileHandler\fR; under Windows it might
|
||||
request notification with a Windows event. For timer-driven event
|
||||
sources such as timer events or any polled event, the event source
|
||||
can call \fBTcl_SetMaxBlockTime\fR to force the application to wake
|
||||
up after a specified time even if no events have occurred.
|
||||
.VS
|
||||
If no event source calls \fBTcl_SetMaxBlockTime\fR
|
||||
then \fBTcl_WaitForEvent\fR will wait as long as necessary for an
|
||||
event to occur; otherwise, it will only wait as long as the shortest
|
||||
interval passed to \fBTcl_SetMaxBlockTime\fR by one of the event
|
||||
sources. If an event source knows that it already has events ready to
|
||||
report, it can request a zero maximum block time. For example, the
|
||||
setup procedure for the X event source looks to see if there are
|
||||
events already queued. If there are, it calls
|
||||
\fBTcl_SetMaxBlockTime\fR with a 0 block time so that
|
||||
\fBTcl_WaitForEvent\fR does not block if there is no new data on the X
|
||||
connection.
|
||||
.VE
|
||||
The \fItimePtr\fR argument to \fBTcl_WaitForEvent\fR points to
|
||||
a structure that describes a time interval in seconds and
|
||||
microseconds:
|
||||
.CS
|
||||
typedef struct Tcl_Time {
|
||||
long \fIsec\fR;
|
||||
long \fIusec\fR;
|
||||
} Tcl_Time;
|
||||
.CE
|
||||
The \fIusec\fR field should be less than 1000000.
|
||||
.PP
|
||||
.VS
|
||||
Information provided to \fBTcl_SetMaxBlockTime\fR
|
||||
is only used for the next call to \fBTcl_WaitForEvent\fR; it is
|
||||
discarded after \fBTcl_WaitForEvent\fR returns.
|
||||
.VE
|
||||
The next time an event wait is done each of the event sources'
|
||||
setup procedures will be called again, and they can specify new
|
||||
information for that event wait.
|
||||
.PP
|
||||
.VS
|
||||
If the application uses an external event loop rather than
|
||||
\fBTcl_DoOneEvent\fR, the event sources may need to call
|
||||
\fBTcl_SetMaxBlockTime\fR at other times. For example, if a new event
|
||||
handler is registered that needs to poll for events, the event source
|
||||
may call \fBTcl_SetMaxBlockTime\fR to set the block time to zero to
|
||||
force the external event loop to call Tcl. In this case,
|
||||
\fBTcl_SetMaxBlockTime\fR invokes \fBTcl_SetTimer\fR with the shortest
|
||||
interval seen since the last call to \fBTcl_DoOneEvent\fR or
|
||||
\fBTcl_ServiceAll\fR.
|
||||
.PP
|
||||
In addition to the generic procedure \fBTcl_SetMaxBlockTime\fR, other
|
||||
platform-specific procedures may also be available for
|
||||
\fIsetupProc\fR, if there is additional information needed by
|
||||
\fBTcl_WaitForEvent\fR on that platform. For example, on Unix systems
|
||||
the \fBTcl_CreateFileHandler\fR interface can be used to wait for file events.
|
||||
.VE
|
||||
.PP
|
||||
The second procedure provided by each event source is its check
|
||||
procedure, indicated by the \fIcheckProc\fR argument to
|
||||
\fBTcl_CreateEventSource\fR. \fICheckProc\fR must match the
|
||||
following prototype:
|
||||
.CS
|
||||
typedef void Tcl_EventCheckProc(
|
||||
ClientData \fIclientData\fR,
|
||||
int \fIflags\fR);
|
||||
.CE
|
||||
The arguments to this procedure are the same as those for \fIsetupProc\fR.
|
||||
\fBCheckProc\fR is invoked by \fBTcl_DoOneEvent\fR after it has waited
|
||||
for events. Presumably at least one event source is now prepared to
|
||||
queue an event. \fBTcl_DoOneEvent\fR calls each of the event sources
|
||||
in turn, so they all have a chance to queue any events that are ready.
|
||||
The check procedure does two things. First, it must see if any events
|
||||
have triggered. Different event sources do this in different ways.
|
||||
.PP
|
||||
If an event source's check procedure detects an interesting event, it
|
||||
must add the event to Tcl's event queue. To do this, the event source
|
||||
calls \fBTcl_QueueEvent\fR. The \fIevPtr\fR argument is a pointer to
|
||||
a dynamically allocated structure containing the event (see below for
|
||||
more information on memory management issues). Each event source can
|
||||
define its own event structure with whatever information is relevant
|
||||
to that event source. However, the first element of the structure
|
||||
must be a structure of type \fBTcl_Event\fR, and the address of this
|
||||
structure is used when communicating between the event source and the
|
||||
rest of the notifier. A \fBTcl_Event\fR has the following definition:
|
||||
.CS
|
||||
typedef struct Tcl_Event {
|
||||
Tcl_EventProc *\fIproc\fR;
|
||||
struct Tcl_Event *\fInextPtr\fR;
|
||||
};
|
||||
.CE
|
||||
The event source must fill in the \fIproc\fR field of
|
||||
the event before calling \fBTcl_QueueEvent\fR.
|
||||
The \fInextPtr\fR is used to link together the events in the queue
|
||||
and should not be modified by the event source.
|
||||
.PP
|
||||
An event may be added to the queue at any of three positions, depending
|
||||
on the \fIposition\fR argument to \fBTcl_QueueEvent\fR:
|
||||
.IP \fBTCL_QUEUE_TAIL\fR 24
|
||||
Add the event at the back of the queue, so that all other pending
|
||||
events will be serviced first. This is almost always the right
|
||||
place for new events.
|
||||
.IP \fBTCL_QUEUE_HEAD\fR 24
|
||||
Add the event at the front of the queue, so that it will be serviced
|
||||
before all other queued events.
|
||||
.IP \fBTCL_QUEUE_MARK\fR 24
|
||||
Add the event at the front of the queue, unless there are other
|
||||
events at the front whose position is \fBTCL_QUEUE_MARK\fR; if so,
|
||||
add the new event just after all other \fBTCL_QUEUE_MARK\fR events.
|
||||
This value of \fIposition\fR is used to insert an ordered sequence of
|
||||
events at the front of the queue, such as a series of
|
||||
Enter and Leave events synthesized during a grab or ungrab operation
|
||||
in Tk.
|
||||
.PP
|
||||
.VS
|
||||
When it is time to handle an event from the queue (steps 1 and 4
|
||||
above) \fBTcl_ServiceEvent\fR will invoke the \fIproc\fR specified
|
||||
.VE
|
||||
in the first queued \fBTcl_Event\fR structure.
|
||||
\fIProc\fR must match the following prototype:
|
||||
.CS
|
||||
typedef int Tcl_EventProc(
|
||||
Tcl_Event *\fIevPtr\fR,
|
||||
int \fIflags\fR);
|
||||
.CE
|
||||
The first argument to \fIproc\fR is a pointer to the event, which will
|
||||
be the same as the first argument to the \fBTcl_QueueEvent\fR call that
|
||||
added the event to the queue.
|
||||
The second argument to \fIproc\fR is the \fIflags\fR argument for the
|
||||
.VS
|
||||
current call to \fBTcl_ServiceEvent\fR; this is used by the event source
|
||||
.VE
|
||||
to return immediately if its events are not relevant.
|
||||
.PP
|
||||
It is up to \fIproc\fR to handle the event, typically by invoking
|
||||
one or more Tcl commands or C-level callbacks.
|
||||
Once the event source has finished handling the event it returns 1
|
||||
to indicate that the event can be removed from the queue.
|
||||
If for some reason the event source decides that the event cannot
|
||||
be handled at this time, it may return 0 to indicate that the event
|
||||
.VS
|
||||
should be deferred for processing later; in this case \fBTcl_ServiceEvent\fR
|
||||
.VE
|
||||
will go on to the next event in the queue and attempt to service it.
|
||||
There are several reasons why an event source might defer an event.
|
||||
One possibility is that events of this type are excluded by the
|
||||
\fIflags\fR argument.
|
||||
For example, the file event source will always return 0 if the
|
||||
\fBTCL_FILE_EVENTS\fR bit isn't set in \fIflags\fR.
|
||||
Another example of deferring events happens in Tk if
|
||||
\fBTk_RestrictEvents\fR has been invoked to defer certain kinds
|
||||
of window events.
|
||||
.PP
|
||||
.VS
|
||||
When \fIproc\fR returns 1, \fBTcl_ServiceEvent\fR will remove the
|
||||
event from the event queue and free its storage.
|
||||
Note that the storage for an event must be allocated by
|
||||
the event source (using \fBTcl_Alloc\fR or the Tcl macro \fBckalloc\fR)
|
||||
before calling \fBTcl_QueueEvent\fR, but it
|
||||
will be freed by \fBTcl_ServiceEvent\fR, not by the event source.
|
||||
.PP
|
||||
\fBTcl_DeleteEvents\fR can be used to explicitly remove one or more
|
||||
events from the event queue. \fBTcl_DeleteEvents\fR calls \fIproc\fR
|
||||
for each event in the queue, deleting those for with the procedure
|
||||
returns 1. Events for which the procedure returns 0 are left in the
|
||||
queue. \fIProc\fR should match the following prototype:
|
||||
.CS
|
||||
typedef int Tcl_EventDeleteProc(
|
||||
Tcl_Event *\fIevPtr\fR,
|
||||
ClientData \fIclientData\fR);
|
||||
.CE
|
||||
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||||
argument to \fBTcl_DeleteEvents\fR; it is typically used to point to
|
||||
private information managed by the event source. The \fIevPtr\fR will
|
||||
point to the next event in the queue.
|
||||
.VE
|
||||
|
||||
.SH "CREATING A NEW NOTIFIER"
|
||||
.PP
|
||||
The notifier consists of all the procedures described in this manual
|
||||
entry, plus \fBTcl_DoOneEvent\fR and \fBTcl_Sleep\fR, which are
|
||||
.VS
|
||||
available on all platforms, and \fBTcl_CreateFileHandler\fR and
|
||||
\fBTcl_DeleteFileHandler\fR, which are Unix-specific. Most of these
|
||||
procedures are generic, in that they are the same for all notifiers.
|
||||
However, five of the procedures are notifier-dependent:
|
||||
\fBTcl_SetTimer\fR, \fBTcl_Sleep\fR, \fBTcl_WaitForEvent\fR,
|
||||
\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR. To
|
||||
support a new platform or to integrate Tcl with an
|
||||
application-specific event loop, you must write new versions of these
|
||||
procedures.
|
||||
.PP
|
||||
\fBTcl_WaitForEvent\fR is the lowest-level procedure in the notifier;
|
||||
it is responsible for waiting for an ``interesting'' event to occur or
|
||||
for a given time to elapse. Before \fBTcl_WaitForEvent\fR is invoked,
|
||||
each of the event sources' setup procedure will have been invoked.
|
||||
The \fItimePtr\fR argument to
|
||||
\fBTcl_WaitForEvent\fR gives the maximum time to block for an event,
|
||||
based on calls to \fBTcl_SetMaxBlockTime\fR made by setup procedures
|
||||
and on other information (such as the \fBTCL_DONT_WAIT\fR bit in
|
||||
\fIflags\fR).
|
||||
.PP
|
||||
Ideally, \fBTcl_WaitForEvent\fR should only wait for an event
|
||||
to occur; it should not actually process the event in any way.
|
||||
Later on, the
|
||||
event sources will process the raw events and create Tcl_Events on
|
||||
the event queue in their \fIcheckProc\fR procedures.
|
||||
However, on some platforms (such as Windows) this isn't possible;
|
||||
events may be processed in \fBTcl_WaitForEvent\fR, including queuing
|
||||
Tcl_Events and more (for example, callbacks for native widgets may be
|
||||
invoked). The return value from \fBTcl_WaitForEvent\fR must be either
|
||||
0, 1, or \-1. On platforms such as Windows where events get processed in
|
||||
\fBTcl_WaitForEvent\fR, a return value of 1 means that there may be more
|
||||
events still pending that haven't been processed. This is a sign to the
|
||||
caller that it must call \fBTcl_WaitForEvent\fR again if it wants all
|
||||
pending events to be processed. A 0 return value means that calling
|
||||
\fBTcl_WaitForEvent\fR again will not have any effect: either this is a
|
||||
platform where \fBTcl_WaitForEvent\fR only waits without doing any event
|
||||
processing, or \fBTcl_WaitForEvent\fR knows for sure that there are no
|
||||
additional events to process (e.g. it returned because the time
|
||||
elapsed). Finally, a return value of \-1 means that the event loop is
|
||||
no longer operational and the application should probably unwind and
|
||||
terminate. Under Windows this happens when a WM_QUIT message is received;
|
||||
under Unix it happens when \fBTcl_WaitForEvent\fR would have waited
|
||||
forever because there were no active event sources and the timeout was
|
||||
infinite.
|
||||
.PP
|
||||
If the notifier will be used with an external event loop, then it must
|
||||
also support the \fBTcl_SetTimer\fR interface. \fBTcl_SetTimer\fR is
|
||||
invoked by \fBTcl_SetMaxBlockTime\fR whenever the maximum blocking
|
||||
time has been reduced. \fBTcl_SetTimer\fR should arrange for the
|
||||
external event loop to invoke \fBTcl_ServiceAll\fR after the specified
|
||||
interval even if no events have occurred. This interface is needed
|
||||
because \fBTcl_WaitForEvent\fR isn't invoked when there is an external
|
||||
event loop. If the
|
||||
notifier will only be used from \fBTcl_DoOneEvent\fR, then
|
||||
\fBTcl_SetTimer\fR need not do anything.
|
||||
.PP
|
||||
On Unix systems, the file event source also needs support from the
|
||||
notifier. The file event source consists of the
|
||||
\fBTcl_CreateFileHandler\fR and \fBTcl_DeleteFileHandler\fR
|
||||
procedures, which are described elsewhere.
|
||||
.PP
|
||||
The \fBTcl_Sleep\fR and \fBTcl_DoOneEvent\fR interfaces are described
|
||||
elsewhere.
|
||||
.PP
|
||||
The easiest way to create a new notifier is to look at the code
|
||||
for an existing notifier, such as the files \fBunix/tclUnixNotfy.c\fR
|
||||
or \fBwin/tclWinNotify.c\fR in the Tcl source distribution.
|
||||
|
||||
.SH "EXTERNAL EVENT LOOPS"
|
||||
.PP
|
||||
The notifier interfaces are designed so that Tcl can be embedded into
|
||||
applications that have their own private event loops. In this case,
|
||||
the application does not call \fBTcl_DoOneEvent\fR except in the case
|
||||
of recursive event loops such as calls to the Tcl commands \fBupdate\fR
|
||||
or \fBvwait\fR. Most of the time is spent in the external event loop
|
||||
of the application. In this case the notifier must arrange for the
|
||||
external event loop to call back into Tcl when something
|
||||
happens on the various Tcl event sources. These callbacks should
|
||||
arrange for appropriate Tcl events to be placed on the Tcl event queue.
|
||||
.PP
|
||||
Because the external event loop is not calling \fBTcl_DoOneEvent\fR on
|
||||
a regular basis, it is up to the notifier to arrange for
|
||||
\fBTcl_ServiceEvent\fR to be called whenever events are pending on the
|
||||
Tcl event queue. The easiest way to do this is to invoke
|
||||
\fBTcl_ServiceAll\fR at the end of each callback from the external
|
||||
event loop. This will ensure that all of the event sources are
|
||||
polled, any queued events are serviced, and any pending idle handlers
|
||||
are processed before returning control to the application. In
|
||||
addition, event sources that need to poll for events can call
|
||||
\fBTcl_SetMaxBlockTime\fR to force the external event loop to call
|
||||
Tcl even if no events are available on the system event queue.
|
||||
.PP
|
||||
As a side effect of processing events detected in the main external
|
||||
event loop, Tcl may invoke \fBTcl_DoOneEvent\fR to start a recursive event
|
||||
loop in commands like \fBvwait\fR. \fBTcl_DoOneEvent\fR will invoke
|
||||
the external event loop, which will result in callbacks as described
|
||||
in the preceding paragraph, which will result in calls to
|
||||
\fBTcl_ServiceAll\fR. However, in these cases it is undesirable to
|
||||
service events in \fBTcl_ServiceAll\fR. Servicing events there is
|
||||
unnecessary because control will immediately return to the
|
||||
external event loop and hence to \fBTcl_DoOneEvent\fR, which can
|
||||
service the events itself. Furthermore, \fBTcl_DoOneEvent\fR is
|
||||
supposed to service only a single event, whereas \fBTcl_ServiceAll\fR
|
||||
normally services all pending events. To handle this situation,
|
||||
\fBTcl_DoOneEvent\fR sets a flag for \fBTcl_ServiceAll\fR
|
||||
that causes it to return without servicing any events.
|
||||
This flag is called the \fIservice mode\fR;
|
||||
\fBTcl_DoOneEvent\fR restores it to its previous value before it returns.
|
||||
.PP
|
||||
In some cases, however, it may be necessary for \fBTcl_ServiceAll\fR
|
||||
to service events
|
||||
even when it has been invoked from \fBTcl_DoOneEvent\fR. This happens
|
||||
when there is yet another recursive event loop invoked via an
|
||||
event handler called by \fBTcl_DoOneEvent\fR (such as one that is
|
||||
part of a native widget). In this case, \fBTcl_DoOneEvent\fR may not
|
||||
have a chance to service events so \fBTcl_ServiceAll\fR must service
|
||||
them all. Any recursive event loop that calls an external event
|
||||
loop rather than \fBTcl_DoOneEvent\fR must reset the service mode so
|
||||
that all events get processed in \fBTcl_ServiceAll\fR. This is done
|
||||
by invoking the \fBTcl_SetServiceMode\fR procedure. If
|
||||
\fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_NONE\fR, then calls
|
||||
to \fBTcl_ServiceAll\fR will return immediately without processing any
|
||||
events. If \fBTcl_SetServiceMode\fR is passed \fBTCL_SERVICE_ALL\fR,
|
||||
then calls to \fBTcl_ServiceAll\fR will behave normally.
|
||||
\fBTcl_SetServiceMode\fR returns the previous value of the service
|
||||
mode, which should be restored when the recursive loop exits.
|
||||
\fBTcl_GetServiceMode\fR returns the current value of the service
|
||||
mode.
|
||||
.VE
|
||||
|
||||
.SH KEYWORDS
|
||||
event, notifier, event queue, event sources, file events, timer, idle, service mode
|
||||
@@ -1,162 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) ObjSetVar.3 1.6 97/05/19 17:35:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_ObjSetVar2 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_ObjSetVar2, Tcl_ObjGetVar2 \- manipulate Tcl variables
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_ObjSetVar2\fR(\fIinterp, part1Ptr, part2Ptr, newValuePtr, flags\fR)
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_ObjGetVar2\fR(\fIinterp, part1Ptr, part2Ptr, flags\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *newValuePtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter containing variable.
|
||||
.AP Tcl_Obj *part1Ptr in
|
||||
Points to a Tcl object containing the variable's name.
|
||||
The name may include a series of \fB::\fR namespace qualifiers
|
||||
to specify a variable in a particular namespace.
|
||||
May refer to a scalar variable or an element of an array variable.
|
||||
.AP Tcl_Obj *part2Ptr in
|
||||
If non-NULL, points to an object containing the name of an element
|
||||
within an array and \fIpart1Ptr\fR must refer to an array variable.
|
||||
.AP Tcl_Obj *newValuePtr in
|
||||
Points to a Tcl object containing the new value for the variable.
|
||||
.AP int flags in
|
||||
OR-ed combination of bits providing additional information for
|
||||
operation. See below for valid values.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These two procedures may be used to read and modify
|
||||
Tcl variables from C code.
|
||||
\fBTcl_ObjSetVar2\fR will create a new variable or modify an existing one.
|
||||
It sets the specified variable to
|
||||
the object referenced by \fInewValuePtr\fR
|
||||
and returns a pointer to the object which is the variable's new value.
|
||||
The returned object may not be the same one
|
||||
referenced by \fInewValuePtr\fR;
|
||||
this might happen because variable traces may modify the variable's value.
|
||||
The reference count for the variable's old value is decremented
|
||||
and the reference count for its new value is incremented.
|
||||
If the new value for the variable
|
||||
is not the same one referenced by \fInewValuePtr\fR
|
||||
(perhaps as a result of a variable trace),
|
||||
then \fInewValuePtr\fR's reference count is left unchanged.
|
||||
The reference count for the returned object is not incremented
|
||||
to reflect the returned reference.
|
||||
If the caller needs to keep a reference to the object,
|
||||
say in a data structure,
|
||||
it must increment its reference count using \fBTcl_IncrRefCount\fR.
|
||||
If an error occurs in setting the variable
|
||||
(e.g. an array variable is referenced
|
||||
without giving an index into the array),
|
||||
then NULL is returned.
|
||||
.PP
|
||||
The variable name specified to \fBTcl_ObjSetVar2\fR consists of two parts.
|
||||
\fIpart1Ptr\fR contains the name of a scalar or array variable.
|
||||
If \fIpart2Ptr\fR is NULL, the variable must be a scalar.
|
||||
If \fIpart2Ptr\fR is not NULL,
|
||||
it contains the name of an element in the array named by \fIpart2Ptr\fR.
|
||||
As a special case, if the flag TCL_PARSE_PART1 is specified,
|
||||
\fIpart1Ptr\fR may contain both an array and an element name:
|
||||
if the name contains an open parenthesis and ends with a
|
||||
close parenthesis, then the value between the parentheses is
|
||||
treated as an element name (which can have any string value) and
|
||||
the characters before the first open
|
||||
parenthesis are treated as the name of an array variable.
|
||||
If the flag TCL_PARSE_PART1 is given,
|
||||
\fIpart2Ptr\fR should be NULL since the array and element names
|
||||
are taken from \fIpart2Ptr\fR.
|
||||
.PP
|
||||
The \fIflags\fR argument may be used to specify any of several
|
||||
options to the procedures.
|
||||
It consists of an OR-ed combination of any of the following
|
||||
bits:
|
||||
.TP
|
||||
\fBTCL_GLOBAL_ONLY\fR
|
||||
Under normal circumstances the procedures look up variables as follows:
|
||||
If a procedure call is active in \fIinterp\fR,
|
||||
a variable is looked up at the current level of procedure call.
|
||||
Otherwise, a variable is looked up first in the current namespace,
|
||||
then in the global namespace.
|
||||
However, if this bit is set in \fIflags\fR then the variable
|
||||
is looked up only in the global namespace
|
||||
even if there is a procedure call active.
|
||||
If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
|
||||
\fBTCL_GLOBAL_ONLY\fR is ignored.
|
||||
.TP
|
||||
\fBTCL_NAMESPACE_ONLY\fR
|
||||
Under normal circumstances the procedures look up variables as follows:
|
||||
If a procedure call is active in \fIinterp\fR,
|
||||
a variable is looked up at the current level of procedure call.
|
||||
Otherwise, a variable is looked up first in the current namespace,
|
||||
then in the global namespace.
|
||||
However, if this bit is set in \fIflags\fR then the variable
|
||||
is looked up only in the current namespace
|
||||
even if there is a procedure call active.
|
||||
.TP
|
||||
\fBTCL_LEAVE_ERR_MSG\fR
|
||||
If an error is returned and this bit is set in \fIflags\fR, then
|
||||
an error message will be left in the interpreter's result,
|
||||
where it can be retrieved with \fBTcl_GetObjResult\fR
|
||||
or \fBTcl_GetStringResult\fR.
|
||||
If this flag bit isn't set then no error message is left
|
||||
and the interpreter's result will not be modified.
|
||||
.TP
|
||||
\fBTCL_APPEND_VALUE\fR
|
||||
If this bit is set then \fInewValuePtr\fR is appended to the current
|
||||
value, instead of replacing it.
|
||||
If the variable is currently undefined, then this bit is ignored.
|
||||
.TP
|
||||
\fBTCL_LIST_ELEMENT\fR
|
||||
If this bit is set, then \fInewValuePtr\fR is converted to a valid
|
||||
Tcl list element before setting (or appending to) the variable.
|
||||
A separator space is appended before the new list element unless
|
||||
the list element is going to be the first element in a list or
|
||||
sublist (i.e. the variable's current value is empty, or contains
|
||||
the single character ``{'', or ends in `` }'').
|
||||
.TP
|
||||
\fBTCL_PARSE_PART1\fR
|
||||
If this bit is set,
|
||||
then \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR
|
||||
will parse \fIpart1Ptr\fR
|
||||
to obtain both an array name and an element name.
|
||||
If the name in \fIpart1Ptr\fR contains an open parenthesis
|
||||
and ends with a close parenthesis,
|
||||
the name is treated as the name of an element of an array;
|
||||
otherwise, the name in \fIpart1Ptr\fR
|
||||
is interpreted as the name of a scalar variable.
|
||||
When this bit is set,
|
||||
\fIpart2Ptr\fR is ignored.
|
||||
.PP
|
||||
\fBTcl_ObjGetVar2\fR returns the value of the specified variable.
|
||||
Its arguments are treated the same way as those for \fBTcl_ObjSetVar2\fR.
|
||||
It returns a pointer to the object which is the variable's value.
|
||||
The reference count for the returned object is not incremented.
|
||||
If the caller needs to keep a reference to the object,
|
||||
say in a data structure,
|
||||
it must increment the reference count using \fBTcl_IncrRefCount\fR.
|
||||
If an error occurs in setting the variable
|
||||
(e.g. an array variable is referenced
|
||||
without giving an index into the array),
|
||||
then NULL is returned.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_GetObjResult, Tcl_GetStringResult, Tcl_GetVar, Tcl_GetVar2, Tcl_SetVar, Tcl_SetVar2, Tcl_TraceVar, Tcl_UnsetVar, Tcl_UnsetVar2
|
||||
|
||||
.SH KEYWORDS
|
||||
array, interpreter, object, scalar, set, unset, variable
|
||||
@@ -1,336 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) Object.3 1.10 97/07/22 11:40:10
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Obj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_NewObj, Tcl_DuplicateObj, Tcl_IncrRefCount, Tcl_DecrRefCount, Tcl_IsShared \- manipulate Tcl objects
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewObj\fR()
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_DuplicateObj\fR(\fIobjPtr\fR)
|
||||
.sp
|
||||
\fBTcl_IncrRefCount\fR(\fIobjPtr\fR)
|
||||
.sp
|
||||
\fBTcl_DecrRefCount\fR(\fIobjPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_IsShared\fR(\fIobjPtr\fR)
|
||||
.sp
|
||||
\fBTcl_InvalidateStringRep\fR(\fIobjPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Obj *objPtr in
|
||||
.AP Tcl_Obj *objPtr in
|
||||
Points to an object;
|
||||
must have been the result of a previous call to \fBTcl_NewObj\fR.
|
||||
.BE
|
||||
|
||||
.SH INTRODUCTION
|
||||
.PP
|
||||
This man page presents an overview of Tcl objects and how they are used.
|
||||
It also describes generic procedures for managing Tcl objects.
|
||||
These procedures are used to create and copy objects,
|
||||
and increment and decrement the count of references (pointers) to objects.
|
||||
The procedures are used in conjunction with ones
|
||||
that operate on specific types of objects such as
|
||||
\fBTcl_GetIntFromObj\fR and \fBTcl_ListObjAppendElement\fR.
|
||||
The individual procedures are described along with the data structures
|
||||
they manipulate.
|
||||
.PP
|
||||
Tcl's \fIdual-ported\fR objects provide a general-purpose mechanism
|
||||
for storing and exchanging Tcl values.
|
||||
They largely replace the use of strings in Tcl.
|
||||
For example, they are used to store variable values,
|
||||
command arguments, command results, and scripts.
|
||||
Tcl objects behave like strings but also hold an internal representation
|
||||
that can be manipulated more efficiently.
|
||||
For example, a Tcl list is now represented as an object
|
||||
that holds the list's string representation
|
||||
as well as an array of pointers to the objects for each list element.
|
||||
Dual-ported objects avoid most runtime type conversions.
|
||||
They also improve the speed of many operations
|
||||
since an appropriate representation is immediately available.
|
||||
The compiler itself uses Tcl objects to
|
||||
cache the instruction bytecodes resulting from compiling scripts.
|
||||
.PP
|
||||
The two representations are a cache of each other and are computed lazily.
|
||||
That is, each representation is only computed when necessary,
|
||||
it is computed from the other representation,
|
||||
and, once computed, it is saved.
|
||||
In addition, a change in one representation invalidates the other one.
|
||||
As an example, a Tcl program doing integer calculations can
|
||||
operate directly on a variable's internal machine integer
|
||||
representation without having to constantly convert
|
||||
between integers and strings.
|
||||
Only when it needs a string representing the variable's value,
|
||||
say to print it,
|
||||
will the program regenerate the string representation from the integer.
|
||||
Although objects contain an internal representation,
|
||||
their semantics are defined in terms of strings:
|
||||
an up-to-date string can always be obtained,
|
||||
and any change to the object will be reflected in that string
|
||||
when the object's string representation is fetched.
|
||||
Because of this representation invalidation and regeneration,
|
||||
it is dangerous for extension writers to access
|
||||
\fBTcl_Obj\fR fields directly.
|
||||
It is better to access Tcl_Obj information using
|
||||
procedures like \fBTcl_GetStringFromObj\fR.
|
||||
.PP
|
||||
Objects are allocated on the heap
|
||||
and are referenced using a pointer to their \fBTcl_Obj\fR structure.
|
||||
Objects are shared as much as possible.
|
||||
This significantly reduces storage requirements
|
||||
because some objects such as long lists are very large.
|
||||
Also, most Tcl values are only read and never modified.
|
||||
This is especially true for procedure arguments,
|
||||
which can be shared between the caller and the called procedure.
|
||||
Assignment and argument binding is done by
|
||||
simply assigning a pointer to the value.
|
||||
Reference counting is used to determine when it is safe to
|
||||
reclaim an object's storage.
|
||||
.PP
|
||||
Tcl objects are typed.
|
||||
An object's internal representation is controlled by its type.
|
||||
Seven types are predefined in the Tcl core
|
||||
including integer, double, list, and bytecode.
|
||||
Extension writers can extend the set of types
|
||||
by using the procedure \fBTcl_RegisterObjType\fR .
|
||||
|
||||
.SH "THE TCL_OBJ STRUCTURE"
|
||||
.PP
|
||||
Each Tcl object is represented by a \fBTcl_Obj\fR structure
|
||||
which is defined as follows.
|
||||
.CS
|
||||
typedef struct Tcl_Obj {
|
||||
int \fIrefCount\fR;
|
||||
char *\fIbytes\fR;
|
||||
int \fIlength\fR;
|
||||
Tcl_ObjType *\fItypePtr\fR;
|
||||
union {
|
||||
long \fIlongValue\fR;
|
||||
double \fIdoubleValue\fR;
|
||||
VOID *\fIotherValuePtr\fR;
|
||||
struct {
|
||||
VOID *\fIptr1\fR;
|
||||
VOID *\fIptr2\fR;
|
||||
} \fItwoPtrValue\fR;
|
||||
} \fIinternalRep\fR;
|
||||
} Tcl_Obj;
|
||||
.CE
|
||||
The \fIbytes\fR and the \fIlength\fR members together hold
|
||||
an object's string representation,
|
||||
which is a \fIcounted\fR or \fIbinary string\fR
|
||||
that may contain binary data with embedded null bytes.
|
||||
\fIbytes\fR points to the first byte of the string representation.
|
||||
The \fIlength\fR member gives the number of bytes.
|
||||
The byte array must always have a null after the last byte,
|
||||
at offset \fIlength\fR;
|
||||
this allows string representations that do not contain nulls
|
||||
to be treated as conventional null-terminated C strings.
|
||||
C programs use \fBTcl_GetStringFromObj\fR to get
|
||||
an object's string representation.
|
||||
If \fIbytes\fR is NULL,
|
||||
the string representation is invalid.
|
||||
.PP
|
||||
An object's type manages its internal representation.
|
||||
The member \fItypePtr\fR points to the Tcl_ObjType structure
|
||||
that describes the type.
|
||||
If \fItypePtr\fR is NULL,
|
||||
the internal representation is invalid.
|
||||
.PP
|
||||
The \fIinternalRep\fR union member holds
|
||||
an object's internal representation.
|
||||
This is either a (long) integer, a double-precision floating point number,
|
||||
a pointer to a value containing additional information
|
||||
needed by the object's type to represent the object,
|
||||
or two arbitrary pointers.
|
||||
.PP
|
||||
The \fIrefCount\fR member is used to tell when it is safe to free
|
||||
an object's storage.
|
||||
It holds the count of active references to the object.
|
||||
Maintaining the correct reference count is a key responsibility
|
||||
of extension writers.
|
||||
Reference counting is discussed below
|
||||
in the section \fBSTORAGE MANAGEMENT OF OBJECTS\fR.
|
||||
.PP
|
||||
Although extension writers can directly access
|
||||
the members of a Tcl_Obj structure,
|
||||
it is much better to use the appropriate procedures and macros.
|
||||
For example, extension writers should never
|
||||
read or update \fIrefCount\fR directly;
|
||||
they should use macros such as
|
||||
\fBTcl_IncrRefCount\fR and \fBTcl_IsShared\fR instead.
|
||||
.PP
|
||||
A key property of Tcl objects is that they hold two representations.
|
||||
An object typically starts out containing only a string representation:
|
||||
it is untyped and has a NULL \fItypePtr\fR.
|
||||
An object containing an empty string or a copy of a specified string
|
||||
is created using \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR respectively.
|
||||
An object's string value is gotten with \fBTcl_GetStringFromObj\fR
|
||||
and changed with \fBTcl_SetStringObj\fR.
|
||||
If the object is later passed to a procedure like \fBTcl_GetIntFromObj\fR
|
||||
that requires a specific internal representation,
|
||||
the procedure will create one and set the object's \fItypePtr\fR.
|
||||
The internal representation is computed from the string representation.
|
||||
An object's two representations are duals of each other:
|
||||
changes made to one are reflected in the other.
|
||||
For example, \fBTcl_ListObjReplace\fR will modify an object's
|
||||
internal representation and the next call to \fBTcl_GetStringFromObj\fR
|
||||
will reflect that change.
|
||||
.PP
|
||||
Representations are recomputed lazily for efficiency.
|
||||
A change to one representation made by a procedure
|
||||
such as \fBTcl_ListObjReplace\fR is not reflected immediately
|
||||
in the other representation.
|
||||
Instead, the other representation is marked invalid
|
||||
so that it is only regenerated if it is needed later.
|
||||
Most C programmers never have to be concerned with how this is done
|
||||
and simply use procedures such as \fBTcl_GetBooleanFromObj\fR or
|
||||
\fBTcl_ListObjIndex\fR.
|
||||
Programmers that implement their own object types
|
||||
must check for invalid representations
|
||||
and mark representations invalid when necessary.
|
||||
The procedure \fBTcl_InvalidateStringRep\fR is used
|
||||
to mark an object's string representation invalid and to
|
||||
free any storage associated with the old string representation.
|
||||
.PP
|
||||
Objects usually remain one type over their life,
|
||||
but occasionally an object must be converted from one type to another.
|
||||
For example, a C program might build up a string in an object
|
||||
with repeated calls to \fBTcl_StringObjAppend\fR,
|
||||
and then call \fBTcl_ListObjIndex\fR to extract a list element from
|
||||
the object.
|
||||
The same object holding the same string value
|
||||
can have several different internal representations
|
||||
at different times.
|
||||
Extension writers can also force an object to be converted from one type
|
||||
to another using the \fBTcl_ConvertToType\fR procedure.
|
||||
Only programmers that create new object types need to be concerned
|
||||
about how this is done.
|
||||
A procedure defined as part of the object type's implementation
|
||||
creates a new internal representation for an object
|
||||
and changes its \fItypePtr\fR.
|
||||
See the man page for \fBTcl_RegisterObjType\fR
|
||||
to see how to create a new object type.
|
||||
|
||||
.SH "EXAMPLE OF THE LIFETIME OF AN OBJECT"
|
||||
.PP
|
||||
As an example of the lifetime of an object,
|
||||
consider the following sequence of commands:
|
||||
.CS
|
||||
\fBset x 123\fR
|
||||
.CE
|
||||
This assigns to \fIx\fR an untyped object whose
|
||||
\fIbytes\fR member points to \fB123\fR and \fIlength\fR member contains 3.
|
||||
The object's \fItypePtr\fR member is NULL.
|
||||
.CS
|
||||
\fBputs "x is $x"\fR
|
||||
.CE
|
||||
\fIx\fR's string representation is valid (since \fIbytes\fR is non-NULL)
|
||||
and is fetched for the command.
|
||||
.CS
|
||||
\fBincr x\fR
|
||||
.CE
|
||||
The \fBincr\fR command first gets an integer from \fIx\fR's object
|
||||
by calling \fBTcl_GetIntFromObj\fR.
|
||||
This procedure checks whether the object is already an integer object.
|
||||
Since it is not, it converts the object
|
||||
by setting the object's \fIinternalRep.longValue\fR member
|
||||
to the integer \fB123\fR
|
||||
and setting the object's \fItypePtr\fR
|
||||
to point to the integer Tcl_ObjType structure.
|
||||
Both representations are now valid.
|
||||
\fBincr\fR increments the object's integer internal representation
|
||||
then invalidates its string representation
|
||||
(by calling \fBTcl_InvalidateStringRep\fR)
|
||||
since the string representation
|
||||
no longer corresponds to the internal representation.
|
||||
.CS
|
||||
\fBputs "x is now $x"\fR
|
||||
.CE
|
||||
The string representation of \fIx\fR's object is needed
|
||||
and is recomputed.
|
||||
The string representation is now \fB124\fR.
|
||||
and both representations are again valid.
|
||||
|
||||
.SH "STORAGE MANAGEMENT OF OBJECTS"
|
||||
.PP
|
||||
Tcl objects are allocated on the heap and are shared as much as possible
|
||||
to reduce storage requirements.
|
||||
Reference counting is used to determine when an object is
|
||||
no longer needed and can safely be freed.
|
||||
An object just created by \fBTcl_NewObj\fR or \fBTcl_NewStringObj\fR
|
||||
has \fIrefCount\fR 0.
|
||||
The macro \fBTcl_IncrRefCount\fR increments the reference count
|
||||
when a new reference to the object is created.
|
||||
The macro \fBTcl_DecrRefCount\fR decrements the count
|
||||
when a reference is no longer needed and,
|
||||
if the object's reference count drops to zero, frees its storage.
|
||||
An object shared by different code or data structures has
|
||||
\fIrefCount\fR greater than 1.
|
||||
Incrementing an object's reference count ensures that
|
||||
it won't be freed too early or have its value change accidently.
|
||||
.PP
|
||||
As an example, the bytecode interpreter shares argument objects
|
||||
between calling and called Tcl procedures to avoid having to copy objects.
|
||||
It assigns the call's argument objects to the procedure's
|
||||
formal parameter variables.
|
||||
In doing so, it calls \fBTcl_IncrRefCount\fR to increment
|
||||
the reference count of each argument since there is now a new
|
||||
reference to it from the formal parameter.
|
||||
When the called procedure returns,
|
||||
the interpreter calls \fBTcl_DecrRefCount\fR to decrement
|
||||
each argument's reference count.
|
||||
When an object's reference count drops to zero,
|
||||
\fBTcl_DecrRefCount\fR reclaims its storage.
|
||||
Most command procedures do not have to be concerned about
|
||||
reference counting since they use an object's value immediately
|
||||
and don't retain a pointer to the object after they return.
|
||||
However, if they do retain a pointer to an object in a data structure,
|
||||
they must be careful to increment its reference count
|
||||
since the retained pointer is a new reference.
|
||||
.PP
|
||||
Command procedures that directly modify objects
|
||||
such as those for \fBlappend\fR and \fBlinsert\fR must be careful to
|
||||
copy a shared object before changing it.
|
||||
They must first check whether the object is shared
|
||||
by calling \fBTcl_IsShared\fR.
|
||||
If the object is shared they must copy the object
|
||||
by using \fBTcl_DuplicateObj\fR;
|
||||
this returns a new duplicate of the original object
|
||||
that has \fIrefCount\fR 0.
|
||||
If the object is not shared,
|
||||
the command procedure "owns" the object and can safely modify it directly.
|
||||
For example, the following code appears in the command procedure
|
||||
that implements \fBlinsert\fR.
|
||||
This procedure modifies the list object passed to it in \fIobjv[1]\fR
|
||||
by inserting \fIobjc-3\fR new elements before \fIindex\fR.
|
||||
.CS
|
||||
listPtr = objv[1];
|
||||
if (Tcl_IsShared(listPtr)) {
|
||||
listPtr = Tcl_DuplicateObj(listPtr);
|
||||
}
|
||||
result = Tcl_ListObjReplace(interp, listPtr, index, 0, (objc-3), &(objv[3]));
|
||||
.CE
|
||||
As another example, \fBincr\fR's command procedure
|
||||
must check whether the variable's object is shared before
|
||||
incrementing the integer in its internal representation.
|
||||
If it is shared, it needs to duplicate the object
|
||||
in order to avoid accidently changing values in other data structures.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_ConvertToType, Tcl_GetIntFromObj, Tcl_ListObjAppendElement, Tcl_ListObjIndex, Tcl_ListObjReplace, Tcl_RegisterObjType
|
||||
|
||||
.SH KEYWORDS
|
||||
internal representation, object, object creation, object type, reference counting, string representation, type conversion
|
||||
@@ -1,198 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) ObjectType.3 1.8 97/04/30 15:42:29
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType \- manipulate Tcl object types
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_RegisterObjType\fR(\fItypePtr\fR)
|
||||
.sp
|
||||
Tcl_ObjType *
|
||||
\fBTcl_GetObjType\fR(\fItypeName\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ObjType *typeName in
|
||||
.AP Tcl_ObjType *typePtr in
|
||||
Points to the structure containing information about the Tcl object type.
|
||||
This storage must must live forever,
|
||||
typically by being statically allocated.
|
||||
.AP char *typeName in
|
||||
The name of a Tcl object type that \fBTcl_GetObjType\fR should look up.
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter to use for error reporting.
|
||||
.AP Tcl_Obj *objPtr in
|
||||
For \fBTcl_AppendAllObjTypes\fR, this points to the object onto which
|
||||
it appends the name of each object type as a list element.
|
||||
For \fBTcl_ConvertToType\fR, this points to an object that
|
||||
must have been the result of a previous call to \fBTcl_NewObj\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The procedures in this man page manage Tcl object types.
|
||||
The are used to register new object types,
|
||||
look up types,
|
||||
and force conversions from one type to another.
|
||||
.PP
|
||||
\fBTcl_RegisterObjType\fR registers a new Tcl object type
|
||||
in the table of all object types supported by Tcl.
|
||||
The argument \fItypePtr\fR points to a Tcl_ObjType structure that
|
||||
describes the new type by giving its name
|
||||
and by supplying pointers to four procedures
|
||||
that implement the type.
|
||||
If the type table already containes a type
|
||||
with the same name as in \fItypePtr\fR,
|
||||
it is replaced with the new type.
|
||||
The Tcl_ObjType structure is described
|
||||
in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
|
||||
.PP
|
||||
\fBTcl_GetObjType\fR returns a pointer to the Tcl_ObjType
|
||||
with name \fItypeName\fR.
|
||||
It returns NULL if no type with that name is registered.
|
||||
.PP
|
||||
\fBTcl_AppendAllObjTypes\fR appends the name of each object type
|
||||
as a list element onto the Tcl object referenced by \fIobjPtr\fR.
|
||||
The return value is \fBTCL_OK\fR unless there was an error
|
||||
converting \fIobjPtr\fR to a list object;
|
||||
in that case \fBTCL_ERROR\fR is returned.
|
||||
.PP
|
||||
\fBTcl_ConvertToType\fR converts an object from one type to another
|
||||
if possible.
|
||||
It creates a new internal representation for \fIobjPtr\fR
|
||||
appropriate for the target type \fItypePtr\fR
|
||||
and sets its \fItypePtr\fR member to that type.
|
||||
Any internal representation for \fIobjPtr\fR's old type is freed.
|
||||
If an error occurs during conversion, it returns \fBTCL_ERROR\fR
|
||||
and leaves an error message in the result object for \fIinterp\fR
|
||||
unless \fIinterp\fR is NULL.
|
||||
Otherwise, it returns \fBTCL_OK\fR.
|
||||
Passing a NULL \fIinterp\fR allows this procedure to be used
|
||||
as a test whether the conversion can be done (and in fact was done).
|
||||
|
||||
.SH "THE TCL_OBJTYPE STRUCTURE"
|
||||
.PP
|
||||
Extension writers can define new object types by defining four
|
||||
procedures,
|
||||
initializing a Tcl_ObjType structure to describe the type,
|
||||
and calling \fBTcl_RegisterObjType\fR.
|
||||
The \fBTcl_ObjType\fR structure is defined as follows:
|
||||
.CS
|
||||
typedef struct Tcl_ObjType {
|
||||
char *\fIname\fR;
|
||||
Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
|
||||
Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
|
||||
Tcl_UpdateStringProc *\fIupdateStringProc\fR;
|
||||
Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
|
||||
} Tcl_ObjType;
|
||||
.CE
|
||||
.PP
|
||||
The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
|
||||
Extension writers can look up an object type using its name
|
||||
with the \fBTcl_GetObjType\fR procedure.
|
||||
The remaining four members are pointers to procedures
|
||||
called by the generic Tcl object code:
|
||||
.PP
|
||||
The \fIsetFromAnyProc\fR member contains the address of a function
|
||||
called to create a valid internal representation
|
||||
from an object's string representation.
|
||||
.CS
|
||||
typedef int (Tcl_SetFromAnyProc) (Tcl_Interp *\fIinterp\fR, Tcl_Obj *\fIobjPtr\fR);
|
||||
.CE
|
||||
If an internal representation can't be created from the string,
|
||||
it returns \fBTCL_ERROR\fR and puts a message
|
||||
describing the error in the result object for \fIinterp\fR
|
||||
unless \fIinterp\fR is NULL.
|
||||
If \fIsetFromAnyProc\fR is successful,
|
||||
it stores the new internal representation,
|
||||
sets \fIobjPtr\fR's \fItypePtr\fR member to point to
|
||||
\fIsetFromAnyProc\fR's \fBTcl_ObjType\fR, and returns \fBTCL_OK\fR.
|
||||
Before setting the new internal representation,
|
||||
the \fIsetFromAnyProc\fR must free any internal representation
|
||||
of \fIobjPtr\fR's old type;
|
||||
it does this by calling the old type's \fIfreeIntRepProc\fR
|
||||
if it is not NULL.
|
||||
As an example, the \fIsetFromAnyProc\fR for the builtin Tcl integer type
|
||||
gets an up-to-date string representation for \fIobjPtr\fR
|
||||
by calling \fBTcl_GetStringFromObj\fR.
|
||||
It parses the string to obtain an integer and,
|
||||
if this succeeds,
|
||||
stores the integer in \fIobjPtr\fR's internal representation
|
||||
and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the integer type's
|
||||
Tcl_ObjType structure.
|
||||
.PP
|
||||
The \fIupdateStringProc\fR member contains the address of a function
|
||||
called to create a valid string representation
|
||||
from an object's internal representation.
|
||||
.CS
|
||||
typedef void (Tcl_UpdateStringProc) (Tcl_Obj *\fIobjPtr\fR);
|
||||
.CE
|
||||
\fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
|
||||
It must always set \fIbytes\fR non-NULL before returning.
|
||||
We require the string representation's byte array
|
||||
to have a null after the last byte, at offset \fIlength\fR;
|
||||
this allows string representations that do not contain null bytes
|
||||
to be treated as conventional null character-terminated C strings.
|
||||
Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
|
||||
Note that \fIupdateStringProc\fRs must allocate
|
||||
enough storage for the string's bytes and the terminating null byte.
|
||||
The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
|
||||
builds an array of strings for each element object
|
||||
and then calls \fBTcl_Merge\fR
|
||||
to construct a string with proper Tcl list structure.
|
||||
It stores this string as the list object's string representation.
|
||||
.PP
|
||||
The \fIdupIntRepProc\fR member contains the address of a function
|
||||
called to copy an internal representation from one object to another.
|
||||
.CS
|
||||
typedef void (Tcl_DupInternalRepProc) (Tcl_Obj *\fIsrcPtr\fR, Tcl_Obj *\fIdupPtr\fR);
|
||||
.CE
|
||||
\fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
|
||||
internal representation.
|
||||
Before the call,
|
||||
\fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
|
||||
\fIsrcPtr\fR's object type determines what
|
||||
copying its internal representation means.
|
||||
For example, the \fIdupIntRepProc\fR for the Tcl integer type
|
||||
simply copies an integer.
|
||||
The builtin list type's \fIdupIntRepProc\fR
|
||||
allocates a new array that points at the original element objects;
|
||||
the elements are shared between the two lists
|
||||
(and their reference counts are incremented to reflect the new references).
|
||||
.PP
|
||||
The \fIfreeIntRepProc\fR member contains the address of a function
|
||||
that is called when an object is freed.
|
||||
.CS
|
||||
typedef void (Tcl_FreeInternalRepProc) (Tcl_Obj *\fIobjPtr\fR);
|
||||
.CE
|
||||
The \fIfreeIntRepProc\fR function can deallocate the storage
|
||||
for the object's internal representation
|
||||
and do other type-specific processing necessary when an object is freed.
|
||||
For example, Tcl list objects have an \fIinternalRep.otherValuePtr\fR
|
||||
that points to an array of pointers to each element in the list.
|
||||
The list type's \fIfreeIntRepProc\fR decrements
|
||||
the reference count for each element object
|
||||
(since the list will no longer refer to those objects),
|
||||
then deallocates the storage for the array of pointers.
|
||||
The \fIfreeIntRepProc\fR member can be set to NULL
|
||||
to indicate that the internal representation does not require freeing.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_DecrRefCount, Tcl_IncrRefCount
|
||||
|
||||
.SH KEYWORDS
|
||||
internal representation, object, object type, string representation, type conversion
|
||||
@@ -1,499 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) OpenFileChnl.3 1.40 97/09/29 11:22:49
|
||||
.so man.macros
|
||||
.TH Tcl_OpenFileChannel 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_OpenFileChannel, Tcl_OpenCommandChannel, Tcl_MakeFileChannel, Tcl_GetChannel, Tcl_RegisterChannel, Tcl_UnregisterChannel, Tcl_Close, Tcl_Read, Tcl_Gets, Tcl_Write, Tcl_Flush, Tcl_Seek, Tcl_Tell, Tcl_Eof, Tcl_InputBlocked, Tcl_InputBuffered, Tcl_GetChannelOption, Tcl_SetChannelOption \- buffered I/O facilities using channels
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
typedef ... Tcl_Channel;
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_OpenFileChannel\fR(\fIinterp, fileName, mode, permissions\fR)
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_OpenCommandChannel\fR(\fIinterp, argc, argv, flags\fR)
|
||||
.VS
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_MakeFileChannel\fR(\fIhandle, readOrWrite\fR)
|
||||
.VE
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_GetChannel\fR(\fIinterp, channelName, modePtr\fR)
|
||||
.sp
|
||||
void
|
||||
\fBTcl_RegisterChannel\fR(\fIinterp, channel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_UnregisterChannel\fR(\fIinterp, channel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Close\fR(\fIinterp, channel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Read\fR(\fIchannel, buf, toRead\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Gets\fR(\fIchannel, lineRead\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetsObj\fR(\fIchannel, lineObjPtr\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Write\fR(\fIchannel, buf, toWrite\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Flush\fR(\fIchannel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Seek\fR(\fIchannel, offset, seekMode\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Tell\fR(\fIchannel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetChannelOption\fR(\fIinterp, channel, optionName, optionValue\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_SetChannelOption\fR(\fIinterp, channel, optionName, newValue\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_Eof\fR(\fIchannel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_InputBlocked\fR(\fIchannel\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_InputBuffered\fR(\fIchannel\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ChannelType newClientProcPtr in
|
||||
.AP Tcl_Interp *interp in
|
||||
Used for error reporting and to look up a channel registered in it.
|
||||
.AP char *fileName in
|
||||
The name of a local or network file.
|
||||
.AP char *mode in
|
||||
Specifies how the file is to be accessed. May have any of the
|
||||
values allowed for the \fImode\fR argument to the Tcl
|
||||
\fBopen\fR command.
|
||||
For \fBTcl_OpenCommandChannel\fR, may be NULL.
|
||||
.AP int permissions in
|
||||
POSIX-style permission flags such as 0644.
|
||||
If a new file is created, these permissions will be set on the
|
||||
created file.
|
||||
.AP int argc in
|
||||
The number of elements in \fIargv\fR.
|
||||
.AP char **argv in
|
||||
Arguments for constructing a command pipeline.
|
||||
These values have the same meaning as the non-switch arguments
|
||||
to the Tcl \fBexec\fR command.
|
||||
.AP int flags in
|
||||
Specifies the disposition of the stdio handles in pipeline: OR-ed
|
||||
combination of \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, \fBTCL_STDERR\fR,
|
||||
and \fBTCL_ENFORCE_MODE\fR. If \fBTCL_STDIN\fR is set, stdin for
|
||||
the first child in the pipe is the pipe channel, otherwise it is the same
|
||||
as the standard input of the invoking process; likewise for
|
||||
\fBTCL_STDOUT\fR and \fBTCL_STDERR\fR. If \fBTCL_ENFORCE_MODE\fR is not set,
|
||||
then the pipe can redirect stdio handles to override the stdio handles for
|
||||
which \fBTCL_STDIN\fR, \fBTCL_STDOUT\fR and \fBTCL_STDERR\fR have been set.
|
||||
If it is set, then such redirections cause an error.
|
||||
.VS
|
||||
.AP ClientData handle in
|
||||
Operating system specific handle for I/O to a file. For Unix this is a
|
||||
file descriptor, for Windows it is a HANDLE.
|
||||
.AP int readOrWrite in
|
||||
OR-ed combination of \fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR to indicate
|
||||
what operations are valid on \fIhandle\fR.
|
||||
.VE
|
||||
.AP int *modePtr out
|
||||
Points at an integer variable that will receive an OR-ed combination of
|
||||
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR denoting whether the channel is
|
||||
open for reading and writing.
|
||||
.AP Tcl_Channel channel in
|
||||
A Tcl channel for input or output. Must have been the return value
|
||||
from a procedure such as \fBTcl_OpenFileChannel\fR.
|
||||
.AP char *buf in
|
||||
An array of bytes in which to store channel input, or from which
|
||||
to read channel output.
|
||||
.AP int len in
|
||||
The length of the input or output.
|
||||
.AP int atEnd in
|
||||
If nonzero, store the input at the end of the input queue, otherwise store
|
||||
it at the head of the input queue.
|
||||
.AP int toRead in
|
||||
The number of bytes to read from the channel.
|
||||
.AP Tcl_DString *lineRead in
|
||||
A pointer to a Tcl dynamic string in which to store the line read from the
|
||||
channel. Must have been initialized by the caller. The line read
|
||||
will be appended to any data already in the dynamic string.
|
||||
.AP Tcl_Obj *linePtrObj in
|
||||
A pointer to a Tcl object in which to store the line read from the
|
||||
channel. The line read will be appended to the current value of the
|
||||
object.
|
||||
.AP int toWrite in
|
||||
The number of bytes to read from \fIbuf\fR and output to the channel.
|
||||
.AP int offset in
|
||||
How far to move the access point in the channel at which the next input or
|
||||
output operation will be applied, measured in bytes from the position
|
||||
given by \fIseekMode\fR. May be either positive or negative.
|
||||
.AP int seekMode in
|
||||
Relative to which point to seek; used with \fIoffset\fR to calculate the new
|
||||
access point for the channel. Legal values are \fBSEEK_SET\fR,
|
||||
\fBSEEK_CUR\fR, and \fBSEEK_END\fR.
|
||||
.AP char *optionName in
|
||||
The name of an option applicable to this channel, such as \fB\-blocking\fR.
|
||||
May have any of the values accepted by the \fBfconfigure\fR command.
|
||||
.AP Tcl_DString *optionValue in
|
||||
Where to store the value of an option or a list of all options and their
|
||||
values. Must have been initialized by the caller.
|
||||
.AP char *newValue in
|
||||
New value for the option given by \fIoptionName\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The Tcl channel mechanism provides a device-independent and
|
||||
platform-independent mechanism for performing buffered input
|
||||
and output operations on a variety of file, socket, and device
|
||||
types.
|
||||
The channel mechanism is extensible to new channel types, by
|
||||
providing a low level channel driver for the new type; the channel driver
|
||||
interface is described in the manual entry for \fBTcl_CreateChannel\fR. The
|
||||
channel mechanism provides a buffering scheme modelled after
|
||||
Unix's standard I/O, and it also allows for nonblocking I/O on
|
||||
channels.
|
||||
.PP
|
||||
The procedures described in this manual entry comprise the C APIs of the
|
||||
generic layer of the channel architecture. For a description of the channel
|
||||
driver architecture and how to implement channel drivers for new types of
|
||||
channels, see the manual entry for \fBTcl_CreateChannel\fR.
|
||||
|
||||
.SH TCL_OPENFILECHANNEL
|
||||
.PP
|
||||
\fBTcl_OpenFileChannel\fR opens a file specified by \fIfileName\fR and
|
||||
returns a channel handle that can be used to perform input and output on
|
||||
the file. This API is modelled after the \fBfopen\fR procedure of
|
||||
the Unix standard I/O library.
|
||||
The syntax and meaning of all arguments is similar to those
|
||||
given in the Tcl \fBopen\fR command when opening a file.
|
||||
If an error occurs while opening the channel, \fBTcl_OpenFileChannel\fR
|
||||
returns NULL and records a POSIX error code that can be
|
||||
retrieved with \fBTcl_GetErrno\fR.
|
||||
In addition, if \fIinterp\fR is non-NULL, \fBTcl_OpenFileChannel\fR
|
||||
leaves an error message in \fIinterp->result\fR after any error.
|
||||
.PP
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR, described below.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.SH TCL_OPENCOMMANDCHANNEL
|
||||
.PP
|
||||
\fBTcl_OpenCommandChannel\fR provides a C-level interface to the
|
||||
functions of the \fBexec\fR and \fBopen\fR commands.
|
||||
It creates a sequence of subprocesses specified
|
||||
by the \fIargv\fR and \fIargc\fR arguments and returns a channel that can
|
||||
be used to communicate with these subprocesses.
|
||||
The \fIflags\fR argument indicates what sort of communication will
|
||||
exist with the command pipeline.
|
||||
.PP
|
||||
If the \fBTCL_STDIN\fR flag is set then the standard input for the
|
||||
first subprocess will be tied to the channel: writing to the channel
|
||||
will provide input to the subprocess. If \fBTCL_STDIN\fR is not set,
|
||||
then standard input for the first subprocess will be the same as this
|
||||
application's standard input. If \fBTCL_STDOUT\fR is set then
|
||||
standard output from the last subprocess can be read from the channel;
|
||||
otherwise it goes to this application's standard output. If
|
||||
\fBTCL_STDERR\fR is set, standard error output for all subprocesses is
|
||||
returned to the channel and results in an error when the channel is
|
||||
closed; otherwise it goes to this application's standard error. If
|
||||
\fBTCL_ENFORCE_MODE\fR is not set, then \fIargc\fR and \fIargv\fR can
|
||||
redirect the stdio handles to override \fBTCL_STDIN\fR,
|
||||
\fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR; if it is set, then it is an
|
||||
error for argc and argv to override stdio channels for which
|
||||
\fBTCL_STDIN\fR, \fBTCL_STDOUT\fR, and \fBTCL_STDERR\fR have been set.
|
||||
.PP
|
||||
If an error occurs while opening the channel, \fBTcl_OpenCommandChannel\fR
|
||||
returns NULL and records a POSIX error code that can be retrieved with
|
||||
\fBTcl_GetErrno\fR.
|
||||
In addition, \fBTcl_OpenCommandChannel\fR leaves an error message in
|
||||
\fIinterp->result\fR if \fIinterp\fR is not NULL.
|
||||
.PP
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR, described below.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.SH TCL_MAKEFILECHANNEL
|
||||
.PP
|
||||
\fBTcl_MakeFileChannel\fR makes a \fBTcl_Channel\fR from an existing,
|
||||
platform-specific, file handle.
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR, described below.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.SH TCL_GETCHANNEL
|
||||
.PP
|
||||
\fBTcl_GetChannel\fR returns a channel given the \fIchannelName\fR used to
|
||||
create it with \fBTcl_CreateChannel\fR and a pointer to a Tcl interpreter in
|
||||
\fIinterp\fR. If a channel by that name is not registered in that interpreter,
|
||||
the procedure returns NULL. If the \fImode\fR argument is not NULL, it
|
||||
points at an integer variable that will receive an OR-ed combination of
|
||||
\fBTCL_READABLE\fR and \fBTCL_WRITABLE\fR describing whether the channel is
|
||||
open for reading and writing.
|
||||
|
||||
.SH TCL_REGISTERCHANNEL
|
||||
.PP
|
||||
\fBTcl_RegisterChannel\fR adds a channel to the set of channels accessible
|
||||
in \fIinterp\fR. After this call, Tcl programs executing in that
|
||||
interpreter can refer to the channel in input or output operations using
|
||||
the name given in the call to \fBTcl_CreateChannel\fR. After this call,
|
||||
the channel becomes the property of the interpreter, and the caller should
|
||||
not call \fBTcl_Close\fR for the channel; the channel will be closed
|
||||
automatically when it is unregistered from the interpreter.
|
||||
.PP
|
||||
Code executing outside of any Tcl interpreter can call
|
||||
\fBTcl_RegisterChannel\fR with \fIinterp\fR as NULL, to indicate that it
|
||||
wishes to hold a reference to this channel. Subsequently, the channel can
|
||||
be registered in a Tcl interpreter and it will only be closed when the
|
||||
matching number of calls to \fBTcl_UnregisterChannel\fR have been made.
|
||||
This allows code executing outside of any interpreter to safely hold a
|
||||
reference to a channel that is also registered in a Tcl interpreter.
|
||||
|
||||
.SH TCL_UNREGISTERCHANNEL
|
||||
.PP
|
||||
\fBTcl_UnregisterChannel\fR removes a channel from the set of channels
|
||||
accessible in \fIinterp\fR. After this call, Tcl programs will no longer be
|
||||
able to use the channel's name to refer to the channel in that interpreter.
|
||||
If this operation removed the last registration of the channel in any
|
||||
interpreter, the channel is also closed and destroyed.
|
||||
.PP
|
||||
Code not associated with a Tcl interpreter can call
|
||||
\fBTcl_UnregisterChannel\fR with \fIinterp\fR as NULL, to indicate to Tcl
|
||||
that it no longer holds a reference to that channel. If this is the last
|
||||
reference to the channel, it will now be closed.
|
||||
|
||||
.SH TCL_CLOSE
|
||||
.PP
|
||||
\fBTcl_Close\fR destroys the channel \fIchannel\fR, which must denote a
|
||||
currently open channel. The channel should not be registered in any
|
||||
interpreter when \fBTcl_Close\fR is called. Buffered output is flushed to
|
||||
the channel's output device prior to destroying the channel, and any
|
||||
buffered input is discarded. If this is a blocking channel, the call does
|
||||
not return until all buffered data is successfully sent to the channel's
|
||||
output device. If this is a nonblocking channel and there is buffered
|
||||
output that cannot be written without blocking, the call returns
|
||||
immediately; output is flushed in the background and the channel will be
|
||||
closed once all of the buffered data has been output. In this case errors
|
||||
during flushing are not reported.
|
||||
.PP
|
||||
If the channel was closed successfully, \fBTcl_Close\fR returns \fBTCL_OK\fR.
|
||||
If an error occurs, \fBTcl_Close\fR returns \fBTCL_ERROR\fR and records a
|
||||
POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
If the channel is being closed synchronously and an error occurs during
|
||||
closing of the channel and \fIinterp\fR is not NULL, an error message is
|
||||
left in \fIinterp->result\fR.
|
||||
.PP
|
||||
Note: it is not safe to call \fBTcl_Close\fR on a channel that has been
|
||||
registered using \fBTcl_RegisterChannel\fR; see the documentation for
|
||||
\fBTcl_RegisterChannel\fR, above, for details. If the channel has ever been
|
||||
given as the \fBchan\fR argument in a call to \fBTcl_RegisterChannel\fR,
|
||||
you should instead use \fBTcl_UnregisterChannel\fR, which will internally
|
||||
call \fBTcl_Close\fR when all calls to \fBTcl_RegisterChannel\fR have been
|
||||
matched by corresponding calls to \fBTcl_UnregisterChannel\fR.
|
||||
|
||||
.SH TCL_READ
|
||||
.PP
|
||||
\fBTcl_Read\fR consumes up to \fItoRead\fR bytes of data from
|
||||
\fIchannel\fR and stores it at \fIbuf\fR.
|
||||
The return value of \fBTcl_Read\fR is the number of characters written
|
||||
at \fIbuf\fR.
|
||||
The buffer produced by \fBTcl_Read\fR is not NULL terminated. Its contents
|
||||
are valid from the zeroth position up to and excluding the position
|
||||
indicated by the return value.
|
||||
If an error occurs, the return value is -1 and \fBTcl_Read\fR records
|
||||
a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
.PP
|
||||
The return value may be smaller than the value of \fItoRead\fR, indicating
|
||||
that less data than requested was available, also called a \fIshort
|
||||
read\fR.
|
||||
In blocking mode, this can only happen on an end-of-file.
|
||||
In nonblocking mode, a short read can also occur if there is not
|
||||
enough input currently available: \fBTcl_Read\fR returns a short
|
||||
count rather than waiting for more data.
|
||||
.PP
|
||||
If the channel is in blocking mode, a return value of zero indicates an end
|
||||
of file condition. If the channel is in nonblocking mode, a return value of
|
||||
zero indicates either that no input is currently available or an end of
|
||||
file condition. Use \fBTcl_Eof\fR and \fBTcl_InputBlocked\fR
|
||||
to tell which of these conditions actually occurred.
|
||||
.PP
|
||||
\fBTcl_Read\fR translates platform-specific end-of-line representations
|
||||
into the canonical \fB\en\fR internal representation according to the
|
||||
current end-of-line recognition mode. End-of-line recognition and the
|
||||
various platform-specific modes are described in the manual entry for the
|
||||
Tcl \fBfconfigure\fR command.
|
||||
|
||||
.SH TCL_GETS AND TCL_GETSOBJ
|
||||
.PP
|
||||
\fBTcl_Gets\fR reads a line of input from a channel and appends all of
|
||||
the characters of the line except for the terminating end-of-line character(s)
|
||||
to the dynamic string given by \fIdsPtr\fR.
|
||||
The end-of-line character(s) are read and discarded.
|
||||
.PP
|
||||
If a line was successfully read, the return value is greater than or
|
||||
equal to zero, and it indicates the number of characters stored
|
||||
in the dynamic string.
|
||||
If an error occurs, \fBTcl_Gets\fR returns -1 and records a POSIX error
|
||||
code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
\fBTcl_Gets\fR also returns -1 if the end of the file is reached;
|
||||
the \fBTcl_Eof\fR procedure can be used to distinguish an error
|
||||
from an end-of-file condition.
|
||||
.PP
|
||||
If the channel is in nonblocking mode, the return value can also
|
||||
be -1 if no data was available or the data that was available
|
||||
did not contain an end-of-line character.
|
||||
When -1 is returned, the \fBTcl_InputBlocked\fR procedure may be
|
||||
invoked to determine if the channel is blocked because of input
|
||||
unavailability.
|
||||
.PP
|
||||
\fBTcl_GetsObj\fR is the same as \fBTcl_Gets\fR except the resulting
|
||||
characters are appended to a Tcl object \fBlineObjPtr\fR rather than a
|
||||
dynamic string.
|
||||
.SH TCL_WRITE
|
||||
.PP
|
||||
\fBTcl_Write\fR accepts \fItoWrite\fR bytes of data at \fIbuf\fR for output
|
||||
on \fIchannel\fR. This data may not appear on the output device
|
||||
immediately. If the data should appear immediately, call \fBTcl_Flush\fR
|
||||
after the call to \fBTcl_Write\fR, or set the \fB-buffering\fR option on
|
||||
the channel to \fBnone\fR. If you wish the data to appear as soon as an end
|
||||
of line is accepted for output, set the \fB\-buffering\fR option on the
|
||||
channel to \fBline\fR mode.
|
||||
.PP
|
||||
The \fItoWrite\fR argument specifies how many bytes of data are provided in
|
||||
the \fIbuf\fR argument. If it is negative, \fBTcl_Write\fR expects the data
|
||||
to be NULL terminated and it outputs everything up to the NULL.
|
||||
.PP
|
||||
The return value of \fBTcl_Write\fR is a count of how many
|
||||
characters were accepted for output to the channel. This is either equal to
|
||||
\fItoWrite\fR or -1 to indicate that an error occurred.
|
||||
If an error occurs, \fBTcl_Write\fR also records a POSIX error code
|
||||
that may be retrieved with \fBTcl_GetErrno\fR.
|
||||
.PP
|
||||
Newline characters in the output data are translated to platform-specific
|
||||
end-of-line sequences according to the \fB\-translation\fR option for
|
||||
the channel.
|
||||
|
||||
.SH TCL_FLUSH
|
||||
.PP
|
||||
\fBTcl_Flush\fR causes all of the buffered output data for \fIchannel\fR
|
||||
to be written to its underlying file or device as soon as possible.
|
||||
If the channel is in blocking mode, the call does not return until
|
||||
all the buffered data has been sent to the channel or some error occurred.
|
||||
The call returns immediately if the channel is nonblocking; it starts
|
||||
a background flush that will write the buffered data to the channel
|
||||
eventually, as fast as the channel is able to absorb it.
|
||||
.PP
|
||||
The return value is normally \fBTCL_OK\fR.
|
||||
If an error occurs, \fBTcl_Flush\fR returns \fBTCL_ERROR\fR and
|
||||
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
|
||||
.SH TCL_SEEK
|
||||
.PP
|
||||
\fBTcl_Seek\fR moves the access point in \fIchannel\fR where subsequent
|
||||
data will be read or written. Buffered output is flushed to the channel and
|
||||
buffered input is discarded, prior to the seek operation.
|
||||
.PP
|
||||
\fBTcl_Seek\fR normally returns the new access point.
|
||||
If an error occurs, \fBTcl_Seek\fR returns -1 and records a POSIX error
|
||||
code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
After an error, the access point may or may not have been moved.
|
||||
|
||||
.SH TCL_TELL
|
||||
.PP
|
||||
\fBTcl_Tell\fR returns the current access point for a channel. The returned
|
||||
value is -1 if the channel does not support seeking.
|
||||
|
||||
.SH TCL_GETCHANNELOPTION
|
||||
.PP
|
||||
\fBTcl_GetChannelOption\fR retrieves, in \fIdsPtr\fR, the value of one of
|
||||
the options currently in effect for a channel, or a list of all options and
|
||||
their values. The \fIchannel\fR argument identifies the channel for which
|
||||
to query an option or retrieve all options and their values.
|
||||
If \fIoptionName\fR is not NULL, it is the name of the
|
||||
option to query; the option's value is copied to the Tcl dynamic string
|
||||
denoted by \fIoptionValue\fR. If
|
||||
\fIoptionName\fR is NULL, the function stores an alternating list of option
|
||||
names and their values in \fIoptionValue\fR, using a series of calls to
|
||||
\fBTcl_DStringAppendElement\fR. The various preexisting options and
|
||||
their possible values are described in the manual entry for the Tcl
|
||||
\fBfconfigure\fR command. Other options can be added by each channel type.
|
||||
These channel type specific options are described in the manual entry for
|
||||
the Tcl command that creates a channel of that type; for example, the
|
||||
additional options for TCP based channels are described in the manual entry
|
||||
for the Tcl \fBsocket\fR command.
|
||||
The procedure normally returns \fBTCL_OK\fR. If an error occurs, it returns
|
||||
\fBTCL_ERROR\fR and calls \fBTcl_SetErrno\fR to store an appropriate POSIX
|
||||
error code.
|
||||
|
||||
.SH TCL_SETCHANNELOPTION
|
||||
.PP
|
||||
\fBTcl_SetChannelOption\fR sets a new value for an option on \fIchannel\fR.
|
||||
\fIOptionName\fR is the option to set and \fInewValue\fR is the value to
|
||||
set.
|
||||
The procedure normally returns \fBTCL_OK\fR. If an error occurs,
|
||||
it returns \fBTCL_ERROR\fR; in addition, if \fIinterp\fR is non-NULL,
|
||||
\fBTcl_SetChannelOption\fR leaves an error message in \fIinterp->result\fR.
|
||||
|
||||
.SH TCL_EOF
|
||||
.PP
|
||||
\fBTcl_Eof\fR returns a nonzero value if \fIchannel\fR encountered
|
||||
an end of file during the last input operation.
|
||||
|
||||
.SH TCL_INPUTBLOCKED
|
||||
.PP
|
||||
\fBTcl_InputBlocked\fR returns a nonzero value if \fIchannel\fR is in
|
||||
nonblocking mode and the last input operation returned less data than
|
||||
requested because there was insufficient data available.
|
||||
The call always returns zero if the channel is in blocking mode.
|
||||
|
||||
.SH TCL_INPUTBUFFERED
|
||||
.PP
|
||||
\fBTcl_InputBuffered\fR returns the number of bytes of input currently
|
||||
buffered in the internal buffers for a channel. If the channel is not open
|
||||
for reading, this function always returns zero.
|
||||
|
||||
.VS
|
||||
.SH "PLATFORM ISSUES"
|
||||
.PP
|
||||
The handles returned from \fBTcl_GetChannelHandle\fR depend on the
|
||||
platform and the channel type. On Unix platforms, the handle is
|
||||
always a Unix file descriptor as returned from the \fBopen\fR system
|
||||
call. On Windows platforms, the handle is a file \fBHANDLE\fR when
|
||||
the channel was created with \fBTcl_OpenFileChannel\fR,
|
||||
\fBTcl_OpenCommandChannel\fR, or \fBTcl_MakeFileChannel\fR. Other
|
||||
channel types may return a different type of handle on Windows
|
||||
platforms. On the Macintosh platform, the handle is a file reference
|
||||
number as returned from \fBHOpenDF\fR.
|
||||
.VE
|
||||
|
||||
.SH "SEE ALSO"
|
||||
DString(3), fconfigure(n), filename(n), fopen(2), Tcl_CreateChannel(3)
|
||||
|
||||
.SH KEYWORDS
|
||||
access point, blocking, buffered I/O, channel, channel driver, end of file,
|
||||
flush, input, nonblocking, output, read, seek, write
|
||||
@@ -1,179 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996-7 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) OpenTcp.3 1.19 97/06/25 14:44:00
|
||||
.so man.macros
|
||||
.TH Tcl_OpenTcpClient 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
Tcl_OpenTcpClient, Tcl_MakeTcpClientChannel, Tcl_OpenTcpServer \- procedures to open channels using TCP sockets
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h> \fR
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_OpenTcpClient\fR(\fIinterp, port, host, myaddr, myport, async\fR)
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_MakeTcpClientChannel\fR(\fIsock\fR)
|
||||
.sp
|
||||
Tcl_Channel
|
||||
\fBTcl_OpenTcpServer\fR(\fIinterp, port, myaddr, proc, clientData\fR)
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_ChannelType newClientProcPtr in
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter to use for error reporting. If non-NULL and an
|
||||
error occurs, an error message is left in \fIinterp->result\fR.
|
||||
.AP int port in
|
||||
A port number to connect to as a client or to listen on as a server.
|
||||
.AP char *host in
|
||||
A string specifying a host name or address for the remote end of the connection.
|
||||
.AP int myport in
|
||||
A port number for the client's end of the socket. If 0, a port number
|
||||
is allocated at random.
|
||||
.AP char *myaddr in
|
||||
A string specifying the host name or address for network interface to use
|
||||
for the local end of the connection. If NULL, a default interface is
|
||||
chosen.
|
||||
.AP int async in
|
||||
If nonzero, the client socket is connected asynchronously to the server.
|
||||
.AP ClientData sock in
|
||||
Platform-specific handle for client TCP socket.
|
||||
.AP Tcl_TcpAcceptProc *proc in
|
||||
Pointer to a procedure to invoke each time a new connection is
|
||||
accepted via the socket.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These functions are convenience procedures for creating
|
||||
channels that communicate over TCP sockets.
|
||||
The operations on a channel
|
||||
are described in the manual entry for \fBTcl_OpenFileChannel\fR.
|
||||
|
||||
.SH TCL_OPENTCPCLIENT
|
||||
.PP
|
||||
\fBTcl_OpenTcpClient\fR opens a client TCP socket connected to a \fIport\fR
|
||||
on a specific \fIhost\fR, and returns a channel that can be used to
|
||||
communicate with the server. The host to connect to can be specified either
|
||||
as a domain name style name (e.g. \fBwww.sunlabs.com\fR), or as a string
|
||||
containing the alphanumeric representation of its four-byte address (e.g.
|
||||
\fB127.0.0.1\fR). Use the string \fBlocalhost\fR to connect to a TCP socket on
|
||||
the host on which the function is invoked.
|
||||
.PP
|
||||
The \fImyaddr\fR and \fImyport\fR arguments allow a client to specify an
|
||||
address for the local end of the connection. If \fImyaddr\fR is NULL, then
|
||||
an interface is chosen automatically by the operating system.
|
||||
If \fImyport\fR is 0, then a port number is chosen at random by
|
||||
the operating system.
|
||||
.PP
|
||||
If \fIasync\fR is zero, the call to \fBTcl_OpenTcpClient\fR returns only
|
||||
after the client socket has either successfully connected to the server, or
|
||||
the attempted connection has failed.
|
||||
If \fIasync\fR is nonzero the socket is connected asynchronously and the
|
||||
returned channel may not yet be connected to the server when the call to
|
||||
\fBTcl_OpenTcpClient\fR returns. If the channel is in blocking mode and an
|
||||
input or output operation is done on the channel before the connection is
|
||||
completed or fails, that operation will wait until the connection either
|
||||
completes successfully or fails. If the channel is in nonblocking mode, the
|
||||
input or output operation will return immediately and a subsequent call to
|
||||
\fBTcl_InputBlocked\fR on the channel will return nonzero.
|
||||
.PP
|
||||
The returned channel is opened for reading and writing.
|
||||
If an error occurs in opening the socket, \fBTcl_OpenTcpClient\fR returns
|
||||
NULL and records a POSIX error code that can be retrieved
|
||||
with \fBTcl_GetErrno\fR.
|
||||
In addition, if \fIinterp\fR is non-NULL, an error message
|
||||
is left in \fIinterp->result\fR.
|
||||
.PP
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.SH TCL_MAKETCPCLIENTCHANNEL
|
||||
.PP
|
||||
\fBTcl_MakeTcpClientChannel\fR creates a \fBTcl_Channel\fR around an
|
||||
existing, platform specific, handle for a client TCP socket.
|
||||
.PP
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.SH TCL_OPENTCPSERVER
|
||||
.PP
|
||||
\fBTcl_OpenTcpServer\fR opens a TCP socket on the local host on a specified
|
||||
\fIport\fR and uses the Tcl event mechanism to accept requests from clients
|
||||
to connect to it. The \fImyaddr\fP argument specifies the network interface.
|
||||
If \fImyaddr\fP is NULL the special address INADDR_ANY should be used to
|
||||
allow connections from any network interface.
|
||||
Each time a client connects to this socket, Tcl creates a channel
|
||||
for the new connection and invokes \fIproc\fR with information about
|
||||
the channel. \fIProc\fR must match the following prototype:
|
||||
.CS
|
||||
typedef void Tcl_TcpAcceptProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Channel \fIchannel\fR,
|
||||
char *\fIhostName\fR,
|
||||
int \fIport\fP);
|
||||
.CE
|
||||
.PP
|
||||
The \fIclientData\fR argument will be the same as the \fIclientData\fR
|
||||
argument to \fBTcl_OpenTcpServer\fR, \fIchannel\fR will be the handle
|
||||
for the new channel, \fIhostName\fR points to a string containing
|
||||
the name of the client host making the connection, and \fIport\fP
|
||||
will contain the client's port number.
|
||||
The new channel
|
||||
is opened for both input and output.
|
||||
If \fIproc\fR raises an error, the connection is closed automatically.
|
||||
\fIProc\fR has no return value, but if it wishes to reject the
|
||||
connection it can close \fIchannel\fR.
|
||||
.PP
|
||||
\fBTcl_OpenTcpServer\fR normally returns a pointer to a channel
|
||||
representing the server socket.
|
||||
If an error occurs, \fBTcl_OpenTcpServer\fR returns NULL and
|
||||
records a POSIX error code that can be retrieved with \fBTcl_GetErrno\fR.
|
||||
In addition, if \fIinterp->result\fR is non-NULL, an error message
|
||||
is left in \fIinterp->result\fR.
|
||||
.PP
|
||||
The channel returned by \fBTcl_OpenTcpServer\fR cannot be used for
|
||||
either input or output.
|
||||
It is simply a handle for the socket used to accept connections.
|
||||
The caller can close the channel to shut down the server and disallow
|
||||
further connections from new clients.
|
||||
.PP
|
||||
TCP server channels operate correctly only in applications that dispatch
|
||||
events through \fBTcl_DoOneEvent\fR or through Tcl commands such as
|
||||
\fBvwait\fR; otherwise Tcl will never notice that a connection request from
|
||||
a remote client is pending.
|
||||
.PP
|
||||
The newly created channel is not registered in the supplied interpreter; to
|
||||
register it, use \fBTcl_RegisterChannel\fR.
|
||||
If one of the standard channels, \fBstdin, stdout\fR or \fBstderr\fR was
|
||||
previously closed, the act of creating the new channel also assigns it as a
|
||||
replacement for the standard channel.
|
||||
|
||||
.VS
|
||||
.SH "PLATFORM ISSUES"
|
||||
.PP
|
||||
On Unix platforms, the socket handle is a Unix file descriptor as
|
||||
returned by the \fBsocket\fR system call. On the Windows platform, the
|
||||
socket handle is a \fBSOCKET\fR as defined in the WinSock API. On the
|
||||
Macintosh platform, the socket handle is a \fBStreamPtr\fR.
|
||||
.VE
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_OpenFileChannel(3), Tcl_RegisterChannel(3), vwait(n)
|
||||
|
||||
.SH KEYWORDS
|
||||
client, server, TCP
|
||||
@@ -1,59 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) PkgRequire.3 1.4 96/02/15 20:03:16
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_PkgRequire, Tcl_PkgProvide \- package version control
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_PkgProvide\fR(\fIinterp, name, version\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_FreeProc clientData
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter where package is needed or available.
|
||||
.AP char *name in
|
||||
Name of package.
|
||||
.AP char *version in
|
||||
A version string consisting of one or more decimal numbers
|
||||
separated by dots.
|
||||
.AP int exact in
|
||||
Non-zero means that only the particular version specified by
|
||||
\fIversion\fR is acceptable.
|
||||
Zero means that newer versions than \fIversion\fR are also
|
||||
acceptable as long as they have the same major version number
|
||||
as \fIversion\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures provide C-level interfaces to Tcl's package and
|
||||
version management facilities.
|
||||
\fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR
|
||||
command, and \fBTcl_PkgProvide\fR is equivalent to the
|
||||
\fBpackage provide\fR command.
|
||||
See the documentation for the Tcl commands for details on what these
|
||||
procedures do.
|
||||
If \fBTcl_PkgRequire\fR completes successfully it returns a pointer
|
||||
to the version string for the version of the package that is provided
|
||||
in the interpreter (which may be different than \fIversion\fR); if
|
||||
an error occurs it returns NULL and leaves an error message in
|
||||
\fIinterp->result\fR.
|
||||
\fBTcl_PkgProvide\fR returns TCL_OK if it completes successfully;
|
||||
if an error occurs it returns TCL_ERROR and leaves an error message
|
||||
in \fIinterp->result\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
package, provide, require, version
|
||||
@@ -1,103 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Preserve.3 1.13 96/05/28 09:26:12
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Preserve 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Preserve, Tcl_Release, Tcl_EventuallyFree \- avoid freeing storage while it's being used
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_Preserve\fR(\fIclientData\fR)
|
||||
.sp
|
||||
\fBTcl_Release\fR(\fIclientData\fR)
|
||||
.sp
|
||||
\fBTcl_EventuallyFree\fR(\fIclientData, freeProc\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_FreeProc clientData
|
||||
.AP ClientData clientData in
|
||||
Token describing structure to be freed or reallocated. Usually a pointer
|
||||
to memory for structure.
|
||||
.AP Tcl_FreeProc *freeProc in
|
||||
Procedure to invoke to free \fIclientData\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These three procedures help implement a simple reference count mechanism
|
||||
for managing storage. They are designed to solve a problem
|
||||
having to do with widget deletion, but are also useful in many other
|
||||
situations. When a widget is deleted, its
|
||||
widget record (the structure holding information specific to the
|
||||
widget) must be returned to the storage allocator.
|
||||
However, it's possible that the widget record is in active use
|
||||
by one of the procedures on the stack at the time of the deletion.
|
||||
This can happen, for example, if the command associated with a button
|
||||
widget causes the button to be destroyed: an X event causes an
|
||||
event-handling C procedure in the button to be invoked, which in
|
||||
turn causes the button's associated Tcl command to be executed,
|
||||
which in turn causes the button to be deleted, which in turn causes
|
||||
the button's widget record to be de-allocated.
|
||||
Unfortunately, when the Tcl command returns, the button's
|
||||
event-handling procedure will need to reference the
|
||||
button's widget record.
|
||||
Because of this, the widget record must not be freed as part of the
|
||||
deletion, but must be retained until the event-handling procedure has
|
||||
finished with it.
|
||||
In other situations where the widget is deleted, it may be possible
|
||||
to free the widget record immediately.
|
||||
.PP
|
||||
\fBTcl_Preserve\fR and \fBTcl_Release\fR
|
||||
implement short-term reference counts for their \fIclientData\fR
|
||||
argument.
|
||||
The \fIclientData\fR argument identifies an object and usually
|
||||
consists of the address of a structure.
|
||||
The reference counts guarantee that an object will not be freed
|
||||
until each call to \fBTcl_Preserve\fR for the object has been
|
||||
matched by calls to \fBTcl_Release\fR.
|
||||
There may be any number of unmatched \fBTcl_Preserve\fR calls
|
||||
in effect at once.
|
||||
.PP
|
||||
\fBTcl_EventuallyFree\fR is invoked to free up its \fIclientData\fR
|
||||
argument.
|
||||
It checks to see if there are unmatched \fBTcl_Preserve\fR calls
|
||||
for the object.
|
||||
If not, then \fBTcl_EventuallyFree\fR calls \fIfreeProc\fR immediately.
|
||||
Otherwise \fBTcl_EventuallyFree\fR records the fact that \fIclientData\fR
|
||||
needs eventually to be freed.
|
||||
When all calls to \fBTcl_Preserve\fR have been matched with
|
||||
calls to \fBTcl_Release\fR then \fIfreeProc\fR will be called by
|
||||
\fBTcl_Release\fR to do the cleanup.
|
||||
.PP
|
||||
All the work of freeing the object is carried out by \fIfreeProc\fR.
|
||||
\fIFreeProc\fR must have arguments and result that match the
|
||||
type \fBTcl_FreeProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
|
||||
.CE
|
||||
The \fIblockPtr\fR argument to \fIfreeProc\fR will be the
|
||||
same as the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR.
|
||||
The type of \fIblockPtr\fR (\fBchar *\fR) is different than the type of the
|
||||
\fIclientData\fR argument to \fBTcl_EventuallyFree\fR for historical
|
||||
reasons, but the value is the same.
|
||||
.PP
|
||||
This mechanism can be used to solve the problem described above
|
||||
by placing \fBTcl_Preserve\fR and \fBTcl_Release\fR calls around
|
||||
actions that may cause undesired storage re-allocation. The
|
||||
mechanism is intended only for short-term use (i.e. while procedures
|
||||
are pending on the stack); it will not work efficiently as a
|
||||
mechanism for long-term reference counts.
|
||||
The implementation does not depend in any way on the internal
|
||||
structure of the objects being freed; it keeps the reference
|
||||
counts in a separate structure.
|
||||
|
||||
.SH KEYWORDS
|
||||
free, reference count, storage
|
||||
@@ -1,47 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) PrintDbl.3 1.9 97/08/22 13:30:22
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_PrintDouble 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_PrintDouble \- Convert floating value to string
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_PrintDouble\fR(\fIinterp, value, dst\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
.VS
|
||||
Before Tcl 8.0, the \fBtcl_precision\fR variable in this interpreter
|
||||
controlled the conversion. As of Tcl 8.0, this argument is ignored and
|
||||
the conversion is controlled by the \fBtcl_precision\fR variable
|
||||
that is now shared by all interpreters.
|
||||
.VE
|
||||
.AP double value in
|
||||
Floating-point value to be converted.
|
||||
.AP char *dst out
|
||||
Where to store string representing \fIvalue\fR. Must have at
|
||||
least TCL_DOUBLE_SPACE characters of storage.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_PrintDouble\fR generates a string that represents the value
|
||||
of \fIvalue\fR and stores it in memory at the location given by
|
||||
\fIdst\fR. It uses \fB%g\fR format to generate the string, with one
|
||||
special twist: the string is guaranteed to contain either
|
||||
a ``.'' or an ``e'' so that it doesn't look like an integer. Where
|
||||
\fB%g\fR would generate an integer with no decimal point, \fBTcl_PrintDouble\fR
|
||||
adds ``.0''.
|
||||
|
||||
.SH KEYWORDS
|
||||
conversion, double-precision, floating-point, string
|
||||
@@ -1,55 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: SCCS: @(#) RecEvalObj.3 1.1 97/07/29 18:31:21
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_RecordAndEvalObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_RecordAndEvalObj \- save command on history list before evaluating
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_RecordAndEvalObj\fR(\fIinterp, cmdPtr, flags\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp;
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter in which to evaluate command.
|
||||
.AP Tcl_Obj *cmdPtr in
|
||||
Points to a Tcl object containing a command (or sequence of commands)
|
||||
to execute.
|
||||
.AP int flags in
|
||||
An OR'ed combination of flag bits. TCL_NO_EVAL means record the
|
||||
command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
|
||||
the command at global level instead of the current stack level.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_RecordAndEvalObj\fR is invoked to record a command as an event
|
||||
on the history list and then execute it using \fBTcl_EvalObj\fR
|
||||
(or \fBTcl_GlobalEvalObj\fR if the TCL_EVAL_GLOBAL bit is set
|
||||
in \fIflags\fR).
|
||||
It returns a completion code such as TCL_OK just like \fBTcl_EvalObj\fR,
|
||||
as well as a result object containing additional information
|
||||
(a result value or error message)
|
||||
that can be retrieved using \fBTcl_GetObjResult\fR.
|
||||
If you don't want the command recorded on the history list then
|
||||
you should invoke \fBTcl_EvalObj\fR instead of \fBTcl_RecordAndEvalObj\fR.
|
||||
Normally \fBTcl_RecordAndEvalObj\fR is only called with top-level
|
||||
commands typed by the user, since the purpose of history is to
|
||||
allow the user to re-issue recently-invoked commands.
|
||||
If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
|
||||
the command is recorded without being evaluated.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_EvalObj, Tcl_GetObjResult
|
||||
|
||||
.SH KEYWORDS
|
||||
command, event, execute, history, interpreter, object, record
|
||||
@@ -1,57 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) RecordEval.3 1.18 97/07/29 18:25:13
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_RecordAndEval 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_RecordAndEval \- save command on history list before evaluating
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_RecordAndEval\fR(\fIinterp, cmd, flags\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp;
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter in which to evaluate command.
|
||||
.AP char *cmd in
|
||||
Command (or sequence of commands) to execute.
|
||||
.AP int flags in
|
||||
An OR'ed combination of flag bits. TCL_NO_EVAL means record the
|
||||
command but don't evaluate it. TCL_EVAL_GLOBAL means evaluate
|
||||
the command at global level instead of the current stack level.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_RecordAndEval\fR is invoked to record a command as an event
|
||||
on the history list and then execute it using \fBTcl_Eval\fR
|
||||
(or \fBTcl_GlobalEval\fR if the TCL_EVAL_GLOBAL bit is set in \fIflags\fR).
|
||||
It returns a completion code such as TCL_OK just like \fBTcl_Eval\fR
|
||||
and it leaves information in \fIinterp->result\fR.
|
||||
If you don't want the command recorded on the history list then
|
||||
you should invoke \fBTcl_Eval\fR instead of \fBTcl_RecordAndEval\fR.
|
||||
Normally \fBTcl_RecordAndEval\fR is only called with top-level
|
||||
commands typed by the user, since the purpose of history is to
|
||||
allow the user to re-issue recently-invoked commands.
|
||||
If the \fIflags\fR argument contains the TCL_NO_EVAL bit then
|
||||
the command is recorded without being evaluated.
|
||||
.PP
|
||||
Note that \fBTcl_RecordAndEval\fR has been largely replaced by the
|
||||
object-based procedure \fBTcl_RecordAndEvalObj\fR.
|
||||
That object-based procedure records and optionally executes
|
||||
a command held in a Tcl object instead of a string.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_RecordAndEvalObj
|
||||
|
||||
.SH KEYWORDS
|
||||
command, event, execute, history, interpreter, record
|
||||
@@ -1,116 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) RegExp.3 1.9 96/08/26 12:59:48
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_RegExpMatch 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_RegExpMatch, Tcl_RegExpCompile, Tcl_RegExpExec, Tcl_RegExpRange \- Pattern matching with regular expressions
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_RegExpMatch\fR(\fIinterp\fR, \fIstring\fR, \fIpattern\fR)
|
||||
.sp
|
||||
Tcl_RegExp
|
||||
\fBTcl_RegExpCompile\fR(\fIinterp\fR, \fIpattern\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_RegExpExec\fR(\fIinterp\fR, \fIregexp\fR, \fIstring\fR, \fIstart\fR)
|
||||
.sp
|
||||
\fBTcl_RegExpRange\fR(\fIregexp\fR, \fIindex\fR, \fIstartPtr\fR, \fIendPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
Tcl interpreter to use for error reporting.
|
||||
.AP char *string in
|
||||
String to check for a match with a regular expression.
|
||||
.AP char *pattern in
|
||||
String in the form of a regular expression pattern.
|
||||
.AP Tcl_RegExp regexp in
|
||||
Compiled regular expression. Must have been returned previously
|
||||
by \fBTcl_RegExpCompile\fR.
|
||||
.AP char *start in
|
||||
If \fIstring\fR is just a portion of some other string, this argument
|
||||
identifies the beginning of the larger string.
|
||||
If it isn't the same as \fIstring\fR, then no \fB^\fR matches
|
||||
will be allowed.
|
||||
.AP int index in
|
||||
Specifies which range is desired: 0 means the range of the entire
|
||||
match, 1 or greater means the range that matched a parenthesized
|
||||
sub-expression.
|
||||
.AP char **startPtr out
|
||||
The address of the first character in the range is stored here, or
|
||||
NULL if there is no such range.
|
||||
.AP char **endPtr out
|
||||
The address of the character just after the last one in the range
|
||||
is stored here, or NULL if there is no such range.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_RegExpMatch\fR determines whether its \fIpattern\fR argument
|
||||
matches \fIregexp\fR, where \fIregexp\fR is interpreted
|
||||
as a regular expression using the same rules as for the
|
||||
\fBregexp\fR Tcl command.
|
||||
If there is a match then \fBTcl_RegExpMatch\fR returns 1.
|
||||
If there is no match then \fBTcl_RegExpMatch\fR returns 0.
|
||||
If an error occurs in the matching process (e.g. \fIpattern\fR
|
||||
is not a valid regular expression) then \fBTcl_RegExpMatch\fR
|
||||
returns \-1 and leaves an error message in \fIinterp->result\fR.
|
||||
.PP
|
||||
\fBTcl_RegExpCompile\fR, \fBTcl_RegExpExec\fR, and \fBTcl_RegExpRange\fR
|
||||
provide lower-level access to the regular expression pattern matcher.
|
||||
\fBTcl_RegExpCompile\fR compiles a regular expression string into
|
||||
the internal form used for efficient pattern matching.
|
||||
The return value is a token for this compiled form, which can be
|
||||
used in subsequent calls to \fBTcl_RegExpExec\fR or \fBTcl_RegExpRange\fR.
|
||||
If an error occurs while compiling the regular expression then
|
||||
\fBTcl_RegExpCompile\fR returns NULL and leaves an error message
|
||||
in \fIinterp->result\fR.
|
||||
Note: the return value from \fBTcl_RegExpCompile\fR is only valid
|
||||
up to the next call to \fBTcl_RegExpCompile\fR; it is not safe to
|
||||
retain these values for long periods of time.
|
||||
.PP
|
||||
\fBTcl_RegExpExec\fR executes the regular expression pattern matcher.
|
||||
It returns 1 if \fIstring\fR contains a range of characters that
|
||||
match \fIregexp\fR, 0 if no match is found, and
|
||||
\-1 if an error occurs.
|
||||
In the case of an error, \fBTcl_RegExpExec\fR leaves an error
|
||||
message in \fIinterp->result\fR.
|
||||
When searching a string for multiple matches of a pattern,
|
||||
it is important to distinguish between the start of the original
|
||||
string and the start of the current search.
|
||||
For example, when searching for the second occurrence of a
|
||||
match, the \fIstring\fR argument might point to the character
|
||||
just after the first match; however, it is important for the
|
||||
pattern matcher to know that this is not the start of the entire string,
|
||||
so that it doesn't allow \fB^\fR atoms in the pattern to match.
|
||||
The \fIstart\fR argument provides this information by pointing
|
||||
to the start of the overall string containing \fIstring\fR.
|
||||
\fIStart\fR will be less than or equal to \fIstring\fR; if it
|
||||
is less than \fIstring\fR then no \fB^\fR matches will be allowed.
|
||||
.PP
|
||||
\fBTcl_RegExpRange\fR may be invoked after \fBTcl_RegExpExec\fR
|
||||
returns; it provides detailed information about what ranges of
|
||||
the string matched what parts of the pattern.
|
||||
\fBTcl_RegExpRange\fR returns a pair of pointers in \fI*startPtr\fR
|
||||
and \fI*endPtr\fR that identify a range of characters in
|
||||
the source string for the most recent call to \fBTcl_RegExpExec\fR.
|
||||
\fIIndex\fR indicates which of several ranges is desired:
|
||||
if \fIindex\fR is 0, information is returned about the overall range
|
||||
of characters that matched the entire pattern; otherwise,
|
||||
information is returned about the range of characters that matched the
|
||||
\fIindex\fR'th parenthesized subexpression within the pattern.
|
||||
If there is no range corresponding to \fIindex\fR then NULL
|
||||
is stored in \fI*firstPtr\fR and \fI*lastPtr\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
match, pattern, regular expression, string, subexpression
|
||||
@@ -1,48 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SetErrno.3 1.5 96/02/15 20:01:31
|
||||
.so man.macros
|
||||
.TH Tcl_SetErrno 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SetErrno, Tcl_GetErrno \- manipulate errno to store and retrieve error codes
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
void
|
||||
\fBTcl_SetErrno\fR(\fIerrorCode\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_GetErrno\fR()
|
||||
.sp
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *errorCode in
|
||||
.AP int errorCode in
|
||||
A POSIX error code such as \fBENOENT\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_SetErrno\fR and \fBTcl_GetErrno\fR provide portable access
|
||||
to the \fBerrno\fR variable, which is used to record a POSIX error
|
||||
code after system calls and other operations such as \fBTcl_Gets\fR.
|
||||
These procedures are necessary because global variable accesses cannot
|
||||
be made across module boundaries on some platforms.
|
||||
.PP
|
||||
\fBTcl_SetErrno\fR sets the \fBerrno\fR variable to the value of the
|
||||
\fIerrorCode\fR argument
|
||||
C procedures that wish to return error information to their callers
|
||||
via \fBerrno\fR should call \fBTcl_SetErrno\fR rather than setting
|
||||
\fBerrno\fR directly.
|
||||
.PP
|
||||
\fBTcl_GetErrno\fR returns the current value of \fBerrno\fR.
|
||||
Procedures wishing to access \fBerrno\fR should call this procedure
|
||||
instead of accessing \fBerrno\fR directly.
|
||||
|
||||
.SH KEYWORDS
|
||||
errno, error code, global variables
|
||||
@@ -1,55 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SetRecLmt.3 1.6 96/03/25 20:06:36
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_SetRecursionLimit 3 7.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SetRecursionLimit \- set maximum allowable nesting depth in interpreter
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_SetRecursionLimit\fR(\fIinterp, depth\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *interp
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter whose recursion limit is to be set.
|
||||
Must be greater than zero.
|
||||
.AP int depth in
|
||||
New limit for nested calls to \fBTcl_Eval\fR for \fIinterp\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
At any given time Tcl enforces a limit on the number of recursive
|
||||
calls that may be active for \fBTcl_Eval\fR and related procedures
|
||||
such as \fBTcl_GlobalEval\fR.
|
||||
Any call to \fBTcl_Eval\fR that exceeds this depth is aborted with
|
||||
an error.
|
||||
By default the recursion limit is 1000.
|
||||
.PP
|
||||
\fBTcl_SetRecursionLimit\fR may be used to change the maximum
|
||||
allowable nesting depth for an interpreter.
|
||||
The \fIdepth\fR argument specifies a new limit for \fIinterp\fR,
|
||||
and \fBTcl_SetRecursionLimit\fR returns the old limit.
|
||||
To read out the old limit without modifying it, invoke
|
||||
\fBTcl_SetRecursionDepth\fR with \fIdepth\fR equal to 0.
|
||||
.PP
|
||||
The \fBTcl_SetRecursionLimit\fR only sets the size of the Tcl
|
||||
call stack: it cannot by itself prevent stack overflows on the
|
||||
C stack being used by the application. If your machine has a
|
||||
limit on the size of the C stack, you may get stack overflows
|
||||
before reaching the limit set by \fBTcl_SetRecursionLimit\fR.
|
||||
If this happens, see if there is a mechanism in your system for
|
||||
increasing the maximum size of the C stack.
|
||||
|
||||
.SH KEYWORDS
|
||||
nesting depth, recursion
|
||||
@@ -1,217 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SetResult.3 1.23 97/06/26 14:05:57
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_SetResult 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SetObjResult, Tcl_GetObjResult, Tcl_SetResult, Tcl_GetStringResult, Tcl_AppendResult, Tcl_AppendElement, Tcl_ResetResult \- manipulate Tcl result
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_SetObjResult\fR(\fIinterp, objPtr\fR)
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_GetObjResult\fR(\fIinterp\fR)
|
||||
.sp
|
||||
\fBTcl_SetResult\fR(\fIinterp, string, freeProc\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetStringResult\fR(\fIinterp\fR)
|
||||
.sp
|
||||
\fBTcl_AppendResult\fR(\fIinterp, string, string, ... , \fB(char *) NULL\fR)
|
||||
.sp
|
||||
\fBTcl_AppendElement\fR(\fIinterp, string\fR)
|
||||
.sp
|
||||
\fBTcl_ResetResult\fR(\fIinterp\fR)
|
||||
.sp
|
||||
\fBTcl_FreeResult\fR(\fIinterp\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_FreeProc freeProc
|
||||
.AP Tcl_Interp *interp out
|
||||
Interpreter whose result is to be modified or read.
|
||||
.AP Tcl_Obj *objPtr in
|
||||
Object value to become result for \fIinterp\fR.
|
||||
.AP char *string in
|
||||
String value to become result for \fIinterp\fR or to be
|
||||
appended to the existing result.
|
||||
.AP Tcl_FreeProc *freeProc in
|
||||
Address of procedure to call to release storage at
|
||||
\fIstring\fR, or \fBTCL_STATIC\fR, \fBTCL_DYNAMIC\fR, or
|
||||
\fBTCL_VOLATILE\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The procedures described here are utilities for manipulating the
|
||||
result value in a Tcl interpreter.
|
||||
The interpreter result may be either a Tcl object or a string.
|
||||
For example, \fBTcl_SetObjResult\fR and \fBTcl_SetResult\fR
|
||||
set the interpreter result to, respectively, an object and a string.
|
||||
Similarly, \fBTcl_GetObjResult\fR and \fBTcl_GetStringResult\fR
|
||||
return the interpreter result as an object and as a string.
|
||||
The procedures always keep the string and object forms
|
||||
of the interpreter result consistent.
|
||||
For example, if \fBTcl_SetObjResult\fR is called to set
|
||||
the result to an object,
|
||||
then \fBTcl_GetStringResult\fR is called,
|
||||
it will return the object's string value.
|
||||
.PP
|
||||
\fBTcl_SetObjResult\fR
|
||||
arranges for \fIobjPtr\fR to be the result for \fIinterp\fR,
|
||||
replacing any existing result.
|
||||
The result is left pointing to the object
|
||||
referenced by \fIobjPtr\fR.
|
||||
\fIobjPtr\fR's reference count is incremented
|
||||
since there is now a new reference to it from \fIinterp\fR.
|
||||
The reference count for any old result object
|
||||
is decremented and the old result object is freed if no
|
||||
references to it remain.
|
||||
.PP
|
||||
\fBTcl_GetObjResult\fR returns the result for \fIinterp\fR as an object.
|
||||
The object's reference count is not incremented;
|
||||
if the caller needs to retain a long-term pointer to the object
|
||||
they should use \fBTcl_IncrRefCount\fR to increment its reference count
|
||||
in order to keep it from being freed too early or accidently changed.
|
||||
.PP
|
||||
\fBTcl_SetResult\fR
|
||||
arranges for \fIstring\fR to be the result for the current Tcl
|
||||
command in \fIinterp\fR, replacing any existing result.
|
||||
The \fIfreeProc\fR argument specifies how to manage the storage
|
||||
for the \fIstring\fR argument;
|
||||
it is discussed in the section
|
||||
\fBTHE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT\fR below.
|
||||
If \fIstring\fR is \fBNULL\fR, then \fIfreeProc\fR is ignored
|
||||
and \fBTcl_SetResult\fR
|
||||
re-initializes \fIinterp\fR's result to point to an empty string.
|
||||
.PP
|
||||
\fBTcl_GetStringResult\fR returns the result for \fIinterp\fR as an string.
|
||||
If the result was set to an object by a \fBTcl_SetObjResult\fR call,
|
||||
the object form will be converted to a string and returned.
|
||||
If the object's string representation contains null bytes,
|
||||
this conversion will lose information.
|
||||
For this reason, programmers are encouraged to
|
||||
write their code to use the new object API procedures
|
||||
and to call \fBTcl_GetObjResult\fR instead.
|
||||
.PP
|
||||
\fBTcl_ResetResult\fR clears the result for \fIinterp\fR
|
||||
and leaves the result in its normal empty initialized state.
|
||||
If the result is an object,
|
||||
its reference count is decremented and the result is left
|
||||
pointing to an unshared object representing an empty string.
|
||||
If the result is a dynamically allocated string, its memory is free*d
|
||||
and the result is left as a empty string.
|
||||
\fBTcl_ResetResult\fR also clears the error state managed by
|
||||
\fBTcl_AddErrorInfo\fR, \fBTcl_AddObjErrorInfo\fR,
|
||||
and \fBTcl_SetErrorCode\fR.
|
||||
|
||||
.SH OLD STRING PROCEDURES
|
||||
.PP
|
||||
Use of the following procedures is deprecated
|
||||
since they manipulate the Tcl result as a string.
|
||||
Procedures such as \fBTcl_SetObjResult\fR
|
||||
that manipulate the result as an object
|
||||
can be significantly more efficient.
|
||||
.PP
|
||||
\fBTcl_AppendResult\fR makes it easy to build up Tcl results in pieces.
|
||||
It takes each of its \fIstring\fR arguments and appends them in order
|
||||
to the current result associated with \fIinterp\fR.
|
||||
If the result is in its initialized empty state (e.g. a command procedure
|
||||
was just invoked or \fBTcl_ResetResult\fR was just called),
|
||||
then \fBTcl_AppendResult\fR sets the result to the concatenation of
|
||||
its \fIstring\fR arguments.
|
||||
\fBTcl_AppendResult\fR may be called repeatedly as additional pieces
|
||||
of the result are produced.
|
||||
\fBTcl_AppendResult\fR takes care of all the
|
||||
storage management issues associated with managing \fIinterp\fR's
|
||||
result, such as allocating a larger result area if necessary.
|
||||
It also converts the current interpreter result from an object
|
||||
to a string, if necessary, before appending the argument strings.
|
||||
Any number of \fIstring\fR arguments may be passed in a single
|
||||
call; the last argument in the list must be a NULL pointer.
|
||||
.PP
|
||||
\fBTcl_AppendElement\fR is similar to \fBTcl_AppendResult\fR in
|
||||
that it allows results to be built up in pieces.
|
||||
However, \fBTcl_AppendElement\fR takes only a single \fIstring\fR
|
||||
argument and it appends that argument to the current result
|
||||
as a proper Tcl list element.
|
||||
\fBTcl_AppendElement\fR adds backslashes or braces if necessary
|
||||
to ensure that \fIinterp\fR's result can be parsed as a list and that
|
||||
\fIstring\fR will be extracted as a single element.
|
||||
Under normal conditions, \fBTcl_AppendElement\fR will add a space
|
||||
character to \fIinterp\fR's result just before adding the new
|
||||
list element, so that the list elements in the result are properly
|
||||
separated.
|
||||
However if the new list element is the first in a list or sub-list
|
||||
(i.e. \fIinterp\fR's current result is empty, or consists of the
|
||||
single character ``{'', or ends in the characters `` {'') then no
|
||||
space is added.
|
||||
.PP
|
||||
\fBTcl_FreeResult\fR performs part of the work
|
||||
of \fBTcl_ResetResult\fR.
|
||||
It frees up the memory associated with \fIinterp\fR's result.
|
||||
It also sets \fIinterp->freeProc\fR to zero, but doesn't
|
||||
change \fIinterp->result\fR or clear error state.
|
||||
\fBTcl_FreeResult\fR is most commonly used when a procedure
|
||||
is about to replace one result value with another.
|
||||
|
||||
.SH DIRECT ACCESS TO INTERP->RESULT IS DEPRECATED
|
||||
.PP
|
||||
It used to be legal for programs to
|
||||
directly read and write \fIinterp->result\fR
|
||||
to manipulate the interpreter result.
|
||||
Direct access to \fIinterp->result\fR is now strongly deprecated
|
||||
because it can make the result's string and object forms inconsistent.
|
||||
Programs should always read the result
|
||||
using the procedures \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR,
|
||||
and write the result using \fBTcl_SetObjResult\fR or \fBTcl_SetResult\fR.
|
||||
|
||||
.SH THE TCL_FREEPROC ARGUMENT TO TCL_SETRESULT
|
||||
.PP
|
||||
\fBTcl_SetResult\fR's \fIfreeProc\fR argument specifies how
|
||||
the Tcl system is to manage the storage for the \fIstring\fR argument.
|
||||
If \fBTcl_SetResult\fR or \fBTcl_SetObjResult\fR are called
|
||||
at a time when \fIinterp\fR holds a string result,
|
||||
they do whatever is necessary to dispose of the old string result
|
||||
(see the \fBTcl_Interp\fR manual entry for details on this).
|
||||
.PP
|
||||
If \fIfreeProc\fR is \fBTCL_STATIC\fR it means that \fIstring\fR
|
||||
refers to an area of static storage that is guaranteed not to be
|
||||
modified until at least the next call to \fBTcl_Eval\fR.
|
||||
If \fIfreeProc\fR
|
||||
is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
|
||||
to \fBTcl_Alloc\fR and is now the property of the Tcl system.
|
||||
\fBTcl_SetResult\fR will arrange for the string's storage to be
|
||||
released by calling \fBTcl_Free\fR when it is no longer needed.
|
||||
If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
|
||||
points to an area of memory that is likely to be overwritten when
|
||||
\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
|
||||
In this case \fBTcl_SetResult\fR will make a copy of the string in
|
||||
dynamically allocated storage and arrange for the copy to be the
|
||||
result for the current Tcl command.
|
||||
.PP
|
||||
If \fIfreeProc\fR isn't one of the values \fBTCL_STATIC\fR,
|
||||
\fBTCL_DYNAMIC\fR, and \fBTCL_VOLATILE\fR, then it is the address
|
||||
of a procedure that Tcl should call to free the string.
|
||||
This allows applications to use non-standard storage allocators.
|
||||
When Tcl no longer needs the storage for the string, it will
|
||||
call \fIfreeProc\fR. \fIFreeProc\fR should have arguments and
|
||||
result that match the type \fBTcl_FreeProc\fR:
|
||||
.CS
|
||||
typedef void Tcl_FreeProc(char *\fIblockPtr\fR);
|
||||
.CE
|
||||
When \fIfreeProc\fR is called, its \fIblockPtr\fR will be set to
|
||||
the value of \fIstring\fR passed to \fBTcl_SetResult\fR.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_AddErrorInfo, Tcl_CreateObjCommand, Tcl_SetErrorCode, Tcl_Interp
|
||||
|
||||
.SH KEYWORDS
|
||||
append, command, element, list, object, result, return value, interpreter
|
||||
@@ -1,204 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SetVar.3 1.30 97/10/10 16:10:36
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_SetVar 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SetVar, Tcl_SetVar2, Tcl_GetVar, Tcl_GetVar2, Tcl_UnsetVar, Tcl_UnsetVar2 \- manipulate Tcl variables
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_SetVar\fR(\fIinterp, varName, newValue, flags\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_SetVar2\fR(\fIinterp, name1, name2, newValue, flags\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetVar\fR(\fIinterp, varName, flags\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetVar2\fR(\fIinterp, name1, name2, flags\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_UnsetVar\fR(\fIinterp, varName, flags\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_UnsetVar2\fR(\fIinterp, name1, name2, flags\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *newValue
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter containing variable.
|
||||
.AP char *varName in
|
||||
Name of variable.
|
||||
May include a series of \fB::\fR namespace qualifiers
|
||||
to specify a variable in a particular namespace.
|
||||
May refer to a scalar variable or an element of
|
||||
an array variable.
|
||||
If the name references an element of an array, then it
|
||||
must be in writable memory: Tcl will make temporary modifications
|
||||
to it while looking up the name.
|
||||
.AP char *newValue in
|
||||
New value for variable.
|
||||
.AP int flags in
|
||||
OR-ed combination of bits providing additional information for
|
||||
operation. See below for valid values.
|
||||
.AP char *name1 in
|
||||
Name of scalar variable, or name of array variable if \fIname2\fR
|
||||
is non-NULL.
|
||||
May include a series of \fB::\fR namespace qualifiers
|
||||
to specify a variable in a particular namespace.
|
||||
.AP char *name2 in
|
||||
If non-NULL, gives name of element within array and \fIname1\fR
|
||||
must refer to an array variable.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures may be used to create, modify, read, and delete
|
||||
Tcl variables from C code.
|
||||
.PP
|
||||
Note that \fBTcl_GetVar\fR and \fBTcl_SetVar\fR
|
||||
have been largely replaced by the
|
||||
object-based procedures \fBTcl_ObjGetVar2\fR and \fBTcl_ObjSetVar2\fR.
|
||||
Those object-based procedures read, modify, and create
|
||||
a variable whose name is held in a Tcl object instead of a string.
|
||||
They also return a pointer to the object
|
||||
which is the variable's value instead of returning a string.
|
||||
Operations on objects can be faster since objects
|
||||
hold an internal representation that can be manipulated more efficiently.
|
||||
.PP
|
||||
\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR
|
||||
will create a new variable or modify an existing one.
|
||||
Both of these procedures set the given variable to the value
|
||||
given by \fInewValue\fR, and they return a pointer to a
|
||||
copy of the variable's new value, which is stored in Tcl's
|
||||
variable structure.
|
||||
Tcl keeps a private copy of the variable's value, so the caller
|
||||
may change \fInewValue\fR after these procedures return without
|
||||
affecting the value of the variable.
|
||||
If an error occurs in setting the variable (e.g. an array
|
||||
variable is referenced without giving an index into the array),
|
||||
they return NULL.
|
||||
.PP
|
||||
The name of the variable may be specified to
|
||||
\fBTcl_SetVar\fR and \fBTcl_SetVar2\fR in either of two ways.
|
||||
If \fBTcl_SetVar\fR is called, the variable name is given as
|
||||
a single string, \fIvarName\fR.
|
||||
If \fIvarName\fR contains an open parenthesis and ends with a
|
||||
close parenthesis, then the value between the parentheses is
|
||||
treated as an index (which can have any string value) and
|
||||
the characters before the first open
|
||||
parenthesis are treated as the name of an array variable.
|
||||
If \fIvarName\fR doesn't have parentheses as described above, then
|
||||
the entire string is treated as the name of a scalar variable.
|
||||
If \fBTcl_SetVar2\fR is called, then the array name and index
|
||||
have been separated by the caller into two separate strings,
|
||||
\fIname1\fR and \fIname2\fR respectively; if \fIname2\fR is
|
||||
zero it means that a scalar variable is being referenced.
|
||||
.PP
|
||||
The \fIflags\fR argument may be used to specify any of several
|
||||
options to the procedures.
|
||||
It consists of an OR-ed combination of the following bits.
|
||||
Note that the flag bit TCL_PARSE_PART1 is only meaningful
|
||||
for the procedures Tcl_SetVar2 and Tcl_GetVar2.
|
||||
.TP
|
||||
\fBTCL_GLOBAL_ONLY\fR
|
||||
Under normal circumstances the procedures look up variables as follows:
|
||||
If a procedure call is active in \fIinterp\fR,
|
||||
a variable is looked up at the current level of procedure call.
|
||||
Otherwise, a variable is looked up first in the current namespace,
|
||||
then in the global namespace.
|
||||
However, if this bit is set in \fIflags\fR then the variable
|
||||
is looked up only in the global namespace
|
||||
even if there is a procedure call active.
|
||||
If both \fBTCL_GLOBAL_ONLY\fR and \fBTCL_NAMESPACE_ONLY\fR are given,
|
||||
\fBTCL_GLOBAL_ONLY\fR is ignored.
|
||||
.TP
|
||||
\fBTCL_NAMESPACE_ONLY\fR
|
||||
Under normal circumstances the procedures look up variables as follows:
|
||||
If a procedure call is active in \fIinterp\fR,
|
||||
a variable is looked up at the current level of procedure call.
|
||||
Otherwise, a variable is looked up first in the current namespace,
|
||||
then in the global namespace.
|
||||
However, if this bit is set in \fIflags\fR then the variable
|
||||
is looked up only in the current namespace
|
||||
even if there is a procedure call active.
|
||||
.TP
|
||||
\fBTCL_LEAVE_ERR_MSG\fR
|
||||
If an error is returned and this bit is set in \fIflags\fR, then
|
||||
an error message will be left in the interpreter's result,
|
||||
where it can be retrieved with \fBTcl_GetObjResult\fR
|
||||
or \fBTcl_GetStringResult\fR.
|
||||
If this flag bit isn't set then no error message is left
|
||||
and the interpreter's result will not be modified.
|
||||
.TP
|
||||
\fBTCL_APPEND_VALUE\fR
|
||||
If this bit is set then \fInewValue\fR is appended to the current
|
||||
value, instead of replacing it.
|
||||
If the variable is currently undefined, then this bit is ignored.
|
||||
.TP
|
||||
\fBTCL_LIST_ELEMENT\fR
|
||||
If this bit is set, then \fInewValue\fR is converted to a valid
|
||||
Tcl list element before setting (or appending to) the variable.
|
||||
A separator space is appended before the new list element unless
|
||||
the list element is going to be the first element in a list or
|
||||
sublist (i.e. the variable's current value is empty, or contains
|
||||
the single character ``{'', or ends in `` }'').
|
||||
.TP
|
||||
\fBTCL_PARSE_PART1\fR
|
||||
If this bit is set when calling \fITcl_SetVar2\fR and \fITcl_GetVar2\fR,
|
||||
\fIname1\fR may contain both an array and an element name:
|
||||
if the name contains an open parenthesis and ends with a
|
||||
close parenthesis, then the value between the parentheses is
|
||||
treated as an element name (which can have any string value) and
|
||||
the characters before the first open
|
||||
parenthesis are treated as the name of an array variable.
|
||||
If the flag TCL_PARSE_PART1 is given,
|
||||
\fIname2\fR should be NULL since the array and element names
|
||||
are taken from \fIname1\fR.
|
||||
.PP
|
||||
\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR
|
||||
return the current value of a variable.
|
||||
The arguments to these procedures are treated in the same way
|
||||
as the arguments to \fBTcl_SetVar\fR and \fBTcl_SetVar2\fR.
|
||||
Under normal circumstances, the return value is a pointer
|
||||
to the variable's value (which is stored in Tcl's variable
|
||||
structure and will not change before the next call to \fBTcl_SetVar\fR
|
||||
or \fBTcl_SetVar2\fR).
|
||||
\fBTcl_GetVar\fR and \fBTcl_GetVar2\fR use the flag bits TCL_GLOBAL_ONLY
|
||||
and TCL_LEAVE_ERR_MSG, both of
|
||||
which have
|
||||
the same meaning as for \fBTcl_SetVar\fR.
|
||||
In addition, \fBTcl_GetVar2\fR uses the bit TCL_PARSE_PART1,
|
||||
which has the same meaning as for \fBTcl_SetVar2\fR.
|
||||
If an error occurs in reading the variable (e.g. the variable
|
||||
doesn't exist or an array element is specified for a scalar
|
||||
variable), then NULL is returned.
|
||||
.PP
|
||||
\fBTcl_UnsetVar\fR and \fBTcl_UnsetVar2\fR may be used to remove
|
||||
a variable, so that future calls to \fBTcl_GetVar\fR or \fBTcl_GetVar2\fR
|
||||
for the variable will return an error.
|
||||
The arguments to these procedures are treated in the same way
|
||||
as the arguments to \fBTcl_GetVar\fR and \fBTcl_GetVar2\fR.
|
||||
If the variable is successfully removed then TCL_OK is returned.
|
||||
If the variable cannot be removed because it doesn't exist then
|
||||
TCL_ERROR is returned.
|
||||
If an array element is specified, the given element is removed
|
||||
but the array remains.
|
||||
If an array name is specified without an index, then the entire
|
||||
array is removed.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_GetObjResult, Tcl_GetStringResult, Tcl_ObjGetVar2, Tcl_ObjSetVar2, Tcl_TraceVar
|
||||
|
||||
.SH KEYWORDS
|
||||
array, interpreter, object, scalar, set, unset, variable
|
||||
@@ -1,37 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Sleep.3 1.3 96/03/25 20:07:21
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Sleep 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Sleep \- delay execution for a given number of milliseconds
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_Sleep\fR(\fIms\fR)
|
||||
.SH ARGUMENTS
|
||||
.AP int ms in
|
||||
Number of milliseconds to sleep.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure delays the calling process by the number of
|
||||
milliseconds given by the \fIms\fR parameter and returns
|
||||
after that time has elapsed. It is typically used for things
|
||||
like flashing a button, where the delay is short and the
|
||||
application needn't do anything while it waits. For longer
|
||||
delays where the application needs to respond to other events
|
||||
during the delay, the procedure \fBTcl_CreateTimerHandler\fR
|
||||
should be used instead of \fBTcl_Sleep\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
sleep, time, wait
|
||||
@@ -1,191 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SplitList.3 1.21 97/04/29 14:07:10
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_SplitList 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SplitList, Tcl_Merge, Tcl_ScanElement, Tcl_ConvertElement \- manipulate Tcl lists
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_SplitList\fR(\fIinterp, list, argcPtr, argvPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_Merge\fR(\fIargc, argv\fR)
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ScanElement\fR(\fIsrc, flagsPtr\fR)
|
||||
.VS
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ScanCountedElement\fR(\fIsrc, length, flagsPtr\fR)
|
||||
.VE
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ConvertElement\fR(\fIsrc, dst, flags\fR)
|
||||
.VS
|
||||
.sp
|
||||
int
|
||||
\fBTcl_ConvertCountedElement\fR(\fIsrc, length, dst, flags\fR)
|
||||
.VE
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp ***argvPtr
|
||||
.AP Tcl_Interp *interp out
|
||||
.VS
|
||||
Interpreter to use for error reporting. If NULL, then no error message
|
||||
is left.
|
||||
.VE
|
||||
.AP char *list in
|
||||
Pointer to a string with proper list structure.
|
||||
.AP int *argcPtr out
|
||||
Filled in with number of elements in \fIlist\fR.
|
||||
.AP char ***argvPtr out
|
||||
\fI*argvPtr\fR will be filled in with the address of an array of
|
||||
pointers to the strings that are the extracted elements of \fIlist\fR.
|
||||
There will be \fI*argcPtr\fR valid entries in the array, followed by
|
||||
a NULL entry.
|
||||
.AP int argc in
|
||||
Number of elements in \fIargv\fR.
|
||||
.AP char **argv in
|
||||
Array of strings to merge together into a single list.
|
||||
Each string will become a separate element of the list.
|
||||
.AP char *src in
|
||||
String that is to become an element of a list.
|
||||
.AP int *flagsPtr in
|
||||
Pointer to word to fill in with information about \fIsrc\fR.
|
||||
The value of *\fIflagsPtr\fR must be passed to \fBTcl_ConvertElement\fR.
|
||||
.VS
|
||||
.AP int length in
|
||||
Number of bytes in string \fIsrc\fR.
|
||||
.VE
|
||||
.AP char *dst in
|
||||
Place to copy converted list element. Must contain enough characters
|
||||
to hold converted string.
|
||||
.AP int flags in
|
||||
Information about \fIsrc\fR. Must be value returned by previous
|
||||
call to \fBTcl_ScanElement\fR, possibly OR-ed
|
||||
with \fBTCL_DONT_USE_BRACES\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures may be used to disassemble and reassemble Tcl lists.
|
||||
\fBTcl_SplitList\fR breaks a list up into its constituent elements,
|
||||
returning an array of pointers to the elements using
|
||||
\fIargcPtr\fR and \fIargvPtr\fR.
|
||||
While extracting the arguments, \fBTcl_SplitList\fR obeys the usual
|
||||
rules for backslash substitutions and braces. The area of
|
||||
memory pointed to by \fI*argvPtr\fR is dynamically allocated; in
|
||||
addition to the array of pointers, it
|
||||
also holds copies of all the list elements. It is the caller's
|
||||
responsibility to free up all of this storage.
|
||||
For example, suppose that you have called \fBTcl_SplitList\fR with
|
||||
the following code:
|
||||
.CS
|
||||
int argc, code;
|
||||
char *string;
|
||||
char **argv;
|
||||
\&...
|
||||
code = Tcl_SplitList(interp, string, &argc, &argv);
|
||||
.CE
|
||||
Then you should eventually free the storage with a call like the
|
||||
following:
|
||||
.VS
|
||||
.CS
|
||||
Tcl_Free((char *) argv);
|
||||
.CE
|
||||
.VE
|
||||
.PP
|
||||
\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
|
||||
successfully parsed.
|
||||
If there was a syntax error in \fIlist\fR, then \fBTCL_ERROR\fR is returned
|
||||
and \fIinterp->result\fR will point to an error message describing the
|
||||
.VS
|
||||
problem (if \fIinterp\fR was not NULL).
|
||||
.VE
|
||||
If \fBTCL_ERROR\fR is returned then no memory is allocated and \fI*argvPtr\fR
|
||||
is not modified.
|
||||
.PP
|
||||
\fBTcl_Merge\fR is the inverse of \fBTcl_SplitList\fR: it
|
||||
takes a collection of strings given by \fIargc\fR
|
||||
and \fIargv\fR and generates a result string
|
||||
that has proper list structure.
|
||||
This means that commands like \fBindex\fR may be used to
|
||||
extract the original elements again.
|
||||
In addition, if the result of \fBTcl_Merge\fR is passed to \fBTcl_Eval\fR,
|
||||
it will be parsed into \fIargc\fR words whose values will
|
||||
be the same as the \fIargv\fR strings passed to \fBTcl_Merge\fR.
|
||||
\fBTcl_Merge\fR will modify the list elements with braces and/or
|
||||
backslashes in order to produce proper Tcl list structure.
|
||||
.VS
|
||||
The result string is dynamically allocated
|
||||
using \fBTcl_Alloc\fR; the caller must eventually release the space
|
||||
using \fBTcl_Free\fR.
|
||||
.VE
|
||||
.PP
|
||||
If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
|
||||
the elements returned by \fBTcl_SplitList\fR will be identical to
|
||||
those passed into \fBTcl_Merge\fR.
|
||||
However, the converse is not true: if \fBTcl_SplitList\fR
|
||||
is passed a given string, and the resulting \fIargc\fR and
|
||||
\fIargv\fR are passed to \fBTcl_Merge\fR, the resulting string
|
||||
may not be the same as the original string passed to \fBTcl_SplitList\fR.
|
||||
This is because \fBTcl_Merge\fR may use backslashes and braces
|
||||
differently than the original string.
|
||||
.PP
|
||||
\fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR are the
|
||||
procedures that do all of the real work of \fBTcl_Merge\fR.
|
||||
\fBTcl_ScanElement\fR scans its \fIsrc\fR argument
|
||||
and determines how to use backslashes and braces
|
||||
when converting it to a list element.
|
||||
It returns an overestimate of the number of characters
|
||||
required to represent \fIsrc\fR as a list element, and
|
||||
it stores information in \fI*flagsPtr\fR that is needed
|
||||
by \fBTcl_ConvertElement\fR.
|
||||
.PP
|
||||
\fBTcl_ConvertElement\fR is a companion procedure to \fBTcl_ScanElement\fR.
|
||||
It does the actual work of converting a string to a list element.
|
||||
Its \fIflags\fR argument must be the same as the value returned
|
||||
by \fBTcl_ScanElement\fR.
|
||||
\fBTcl_ConvertElement\fR writes a proper list element to memory
|
||||
starting at *\fIdst\fR and returns a count of the total number
|
||||
of characters written, which will be no more than the result
|
||||
returned by \fBTcl_ScanElement\fR.
|
||||
\fBTcl_ConvertElement\fR writes out only the actual list element
|
||||
without any leading or trailing spaces: it is up to the caller to
|
||||
include spaces between adjacent list elements.
|
||||
.PP
|
||||
\fBTcl_ConvertElement\fR uses one of two different approaches to
|
||||
handle the special characters in \fIsrc\fR. Wherever possible, it
|
||||
handles special characters by surrounding the string with braces.
|
||||
This produces clean-looking output, but can't be used in some situations,
|
||||
such as when \fIsrc\fR contains unmatched braces.
|
||||
In these situations, \fBTcl_ConvertElement\fR handles special
|
||||
characters by generating backslash sequences for them.
|
||||
The caller may insist on the second approach by OR-ing the
|
||||
flag value returned by \fBTcl_ScanElement\fR with
|
||||
\fBTCL_DONT_USE_BRACES\fR.
|
||||
Although this will produce an uglier result, it is useful in some
|
||||
special situations, such as when \fBTcl_ConvertElement\fR is being
|
||||
used to generate a portion of an argument for a Tcl command.
|
||||
In this case, surrounding \fIsrc\fR with curly braces would cause
|
||||
the command not to be parsed correctly.
|
||||
.PP
|
||||
.VS
|
||||
\fBTcl_ScanCountedElement\fR and \fBTcl_ConvertCountedElement\fR are
|
||||
the same as \fBTcl_ScanElement\fR and \fBTcl_ConvertElement\fR, except
|
||||
the length of string \fIsrc\fR is specified by the \fIlength\fR
|
||||
argument, and the string may contain embedded nulls.
|
||||
.VE
|
||||
|
||||
.SH KEYWORDS
|
||||
backslash, convert, element, list, merge, split, strings
|
||||
@@ -1,93 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) SplitPath.3 1.4 96/08/19 14:59:35
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_SplitPath 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_SplitPath, Tcl_JoinPath, Tcl_GetPathType \- manipulate platform-dependent file paths
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_SplitPath\fR(\fIpath, argcPtr, argvPtr\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_JoinPath\fR(\fIargc, argv, resultPtr\fR)
|
||||
.sp
|
||||
Tcl_PathType
|
||||
\fBTcl_GetPathType\fR(\fIpath\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_DString ***argvPtr
|
||||
.AP char *path in
|
||||
File path in a form appropriate for the current platform (see the
|
||||
\fBfilename\fR manual entry for acceptable forms for path names).
|
||||
.AP int *argcPtr out
|
||||
Filled in with number of path elements in \fIpath\fR.
|
||||
.AP char ***argvPtr out
|
||||
\fI*argvPtr\fR will be filled in with the address of an array of
|
||||
pointers to the strings that are the extracted elements of \fIpath\fR.
|
||||
There will be \fI*argcPtr\fR valid entries in the array, followed by
|
||||
a NULL entry.
|
||||
.AP int argc in
|
||||
Number of elements in \fIargv\fR.
|
||||
.AP char **argv in
|
||||
Array of path elements to merge together into a single path.
|
||||
.AP Tcl_DString *resultPtr in/out
|
||||
A pointer to an initialized \fBTcl_DString\fR to which the result of
|
||||
\fBTcl_JoinPath\fR will be appended.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
These procedures may be used to disassemble and reassemble file
|
||||
paths in a platform independent manner: they provide C-level access to
|
||||
the same functionality as the \fBfile split\fR, \fBfile join\fR, and
|
||||
\fBfile pathtype\fR commands.
|
||||
.PP
|
||||
\fBTcl_SplitPath\fR breaks a path into its constituent elements,
|
||||
returning an array of pointers to the elements using \fIargcPtr\fR and
|
||||
\fIargvPtr\fR. The area of memory pointed to by \fI*argvPtr\fR is
|
||||
dynamically allocated; in addition to the array of pointers, it also
|
||||
holds copies of all the path elements. It is the caller's
|
||||
responsibility to free all of this storage.
|
||||
For example, suppose that you have called \fBTcl_SplitPath\fR with the
|
||||
following code:
|
||||
.CS
|
||||
int argc;
|
||||
char *path;
|
||||
char **argv;
|
||||
\&...
|
||||
Tcl_SplitPath(string, &argc, &argv);
|
||||
.CE
|
||||
Then you should eventually free the storage with a call like the
|
||||
following:
|
||||
.CS
|
||||
Tcl_Free((char *) argv);
|
||||
.CE
|
||||
.PP
|
||||
\fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a
|
||||
collection of path elements given by \fIargc\fR and \fIargv\fR and
|
||||
generates a result string that is a properly constructed path. The
|
||||
result string is appended to \fIresultPtr\fR. \fIResultPtr\fR must
|
||||
refer to an initialized \fBTcl_DString\fR.
|
||||
.PP
|
||||
If the result of \fBTcl_SplitPath\fR is passed to \fBTcl_JoinPath\fR,
|
||||
the result will refer to the same location, but may not be in the same
|
||||
form. This is because \fBTcl_SplitPath\fR and \fBTcl_JoinPath\fR
|
||||
eliminate duplicate path separators and return a normalized form for
|
||||
each platform.
|
||||
.PP
|
||||
\fBTcl_GetPathType\fR returns the type of the specified \fIpath\fR,
|
||||
where \fBTcl_PathType\fR is one of \fBTCL_PATH_ABSOLUTE\fR,
|
||||
\fBTCL_PATH_RELATIVE\fR, or \fBTCL_PATH_VOLUME_RELATIVE\fR. See the
|
||||
\fBfilename\fR manual entry for a description of the path types for
|
||||
each platform.
|
||||
|
||||
.SH KEYWORDS
|
||||
file, filename, join, path, split, type
|
||||
@@ -1,70 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) StaticPkg.3 1.4 96/09/04 11:21:26
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_StaticPackage 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_StaticPackage \- make a statically linked package available via the \fBload\fR command
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_StaticPackage\fR(\fIinterp, pkgName, initProc, safeInitProc\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_PackageInitProc *safeInitProc
|
||||
.AP Tcl_Interp *interp in
|
||||
If not NULL, points to an interpreter into which the package has
|
||||
already been loaded (i.e., the caller has already invoked the
|
||||
appropriate initialization procedure). NULL means the package
|
||||
hasn't yet been incorporated into any interpreter.
|
||||
.AP char *pkgName in
|
||||
Name of the package; should be properly capitalized (first letter
|
||||
upper-case, all others lower-case).
|
||||
.AP Tcl_PackageInitProc *initProc in
|
||||
Procedure to invoke to incorporate this package into a trusted
|
||||
interpreter.
|
||||
.AP Tcl_PackageInitProc *safeInitProc in
|
||||
Procedure to call to incorporate this package into a safe interpreter
|
||||
(one that will execute untrusted scripts). NULL means the package
|
||||
can't be used in safe interpreters.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This procedure may be invoked to announce that a package has been
|
||||
linked statically with a Tcl application and, optionally, that it
|
||||
has already been loaded into an interpreter.
|
||||
Once \fBTcl_StaticPackage\fR has been invoked for a package, it
|
||||
may be loaded into interpreters using the \fBload\fR command.
|
||||
\fBTcl_StaticPackage\fR is normally invoked only by the \fBTcl_AppInit\fR
|
||||
procedure for the application, not by packages for themselves
|
||||
(\fBTcl_StaticPackage\fR should only be invoked for statically
|
||||
loaded packages, and code in the package itself should not need
|
||||
to know whether the package is dynamically or statically loaded).
|
||||
.PP
|
||||
When the \fBload\fR command is used later to load the package into
|
||||
an interpreter, one of \fIinitProc\fR and \fIsafeInitProc\fR will
|
||||
be invoked, depending on whether the target interpreter is safe
|
||||
or not.
|
||||
\fIinitProc\fR and \fIsafeInitProc\fR must both match the
|
||||
following prototype:
|
||||
.CS
|
||||
typedef int Tcl_PackageInitProc(Tcl_Interp *\fIinterp\fR);
|
||||
.CE
|
||||
The \fIinterp\fR argument identifies the interpreter in which the
|
||||
package is to be loaded. The initialization procedure must return
|
||||
\fBTCL_OK\fR or \fBTCL_ERROR\fR to indicate whether or not it completed
|
||||
successfully; in the event of an error it should set \fIinterp->result\fR
|
||||
to point to an error message.
|
||||
The result or error from the initialization procedure will be returned
|
||||
as the result of the \fBload\fR command that caused the
|
||||
initialization procedure to be invoked.
|
||||
|
||||
.SH KEYWORDS
|
||||
initialization procedure, package, static linking
|
||||
@@ -1,39 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) StrMatch.3 1.11 96/03/25 20:08:06
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_StringMatch 3 "" Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_StringMatch \- test whether a string matches a pattern
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_StringMatch\fR(\fIstring\fR, \fIpattern\fR)
|
||||
.SH ARGUMENTS
|
||||
.AP char *string in
|
||||
String to test.
|
||||
.AP char *pattern in
|
||||
Pattern to match against string. May contain special
|
||||
characters from the set *?\e[].
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This utility procedure determines whether a string matches
|
||||
a given pattern. If it does, then \fBTcl_StringMatch\fR returns
|
||||
1. Otherwise \fBTcl_StringMatch\fR returns 0. The algorithm
|
||||
used for matching is the same algorithm used in the ``string match''
|
||||
Tcl command and is similar to the algorithm used by the C-shell
|
||||
for file name matching; see the Tcl manual entry for details.
|
||||
|
||||
.SH KEYWORDS
|
||||
match, pattern, string
|
||||
@@ -1,132 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) StringObj.3 1.13 97/06/25 13:40:25
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_StringObj 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_NewStringObj, Tcl_SetStringObj, Tcl_GetStringFromObj, Tcl_AppendToObj, Tcl_AppendStringsToObj, Tcl_SetObjLength, TclConcatObj \- manipulate Tcl objects as strings
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_NewStringObj\fR(\fIbytes, length\fR)
|
||||
.sp
|
||||
\fBTcl_SetStringObj\fR(\fIobjPtr, bytes, length\fR)
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_GetStringFromObj\fR(\fIobjPtr, lengthPtr\fR)
|
||||
.sp
|
||||
\fBTcl_AppendToObj\fR(\fIobjPtr, bytes, length\fR)
|
||||
.sp
|
||||
\fBTcl_AppendStringsToObj\fR(\fIobjPtr, string, string, ... \fB(char *) NULL\fR)
|
||||
.sp
|
||||
\fBTcl_SetObjLength\fR(\fIobjPtr, newLength\fR)
|
||||
.sp
|
||||
Tcl_Obj *
|
||||
\fBTcl_ConcatObj\fR(\fIobjc, objv\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp *lengthPtr out
|
||||
.AP char *bytes in
|
||||
Points to the first byte of an array of bytes
|
||||
used to set or append to a string object.
|
||||
This byte array may contain embedded null bytes
|
||||
unless \fIlength\fR is negative.
|
||||
.AP int length in
|
||||
The number of bytes to copy from \fIbytes\fR when
|
||||
initializing, setting, or appending to a string object.
|
||||
If negative, all bytes up to the first null are used.
|
||||
.AP Tcl_Obj *objPtr in/out
|
||||
Points to an object to manipulate.
|
||||
.AP int *lengthPtr out
|
||||
If non-NULL, the location where \fBTcl_GetStringFromObj\fR will store
|
||||
the the length of an object's string representation.
|
||||
.AP char *string in
|
||||
Null-terminated string value to append to \fIobjPtr\fR.
|
||||
.AP int newLength in
|
||||
New length for the string value of \fIobjPtr\fR, not including the
|
||||
final NULL character.
|
||||
.AP int objc in
|
||||
The number of elements to concatenate.
|
||||
.AP Tcl_Obj *objv[] in
|
||||
The array of objects to concatenate.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The procedures described in this manual entry allow Tcl objects to
|
||||
be manipulated as string values. They use the internal representation
|
||||
of the object to store additional information to make the string
|
||||
manipulations more efficient. In particular, they make a series of
|
||||
append operations efficient by allocating extra storage space for the
|
||||
string so that it doesn't have to be copied for each append.
|
||||
.PP
|
||||
\fBTcl_NewStringObj\fR and \fBTcl_SetStringObj\fR create a new object
|
||||
or modify an existing object to hold a copy of
|
||||
the string given by \fIbytes\fR and \fIlength\fR.
|
||||
\fBTcl_NewStringObj\fR returns a pointer to a newly created object
|
||||
with reference count zero.
|
||||
Both procedures set the object to hold a copy of the specified string.
|
||||
\fBTcl_SetStringObj\fR frees any old string representation
|
||||
as well as any old internal representation of the object.
|
||||
.PP
|
||||
\fBTcl_GetStringFromObj\fR returns an object's string representation.
|
||||
This is given by the returned byte pointer
|
||||
and length, which is stored in \fIlengthPtr\fR if it is non-NULL.
|
||||
If the object's string representation is invalid
|
||||
(its byte pointer is NULL),
|
||||
the string representation is regenerated from the
|
||||
object's internal representation.
|
||||
The storage referenced by the returned byte pointer
|
||||
is owned by the object manager and should not be modified by the caller.
|
||||
.PP
|
||||
\fBTcl_AppendToObj\fR appends the data given by \fIbytes\fR and
|
||||
\fIlength\fR to the object specified by \fIobjPtr\fR. It does this
|
||||
in a way that handles repeated calls relatively efficiently (it
|
||||
overallocates the string space to avoid repeated reallocations
|
||||
and copies of object's string value).
|
||||
.PP
|
||||
\fBTcl_AppendStringsToObj\fR is similar to \fBTcl_AppendToObj\fR
|
||||
except that it can be passed more than one value to append and
|
||||
each value must be a null-terminated string (i.e. none of the
|
||||
values may contain internal null characters). Any number of
|
||||
\fIstring\fR arguments may be provided, but the last argument
|
||||
must be a NULL pointer to indicate the end of the list.
|
||||
.PP
|
||||
The \fBTcl_SetObjLength\fR procedure changes the length of the
|
||||
string value of its \fIobjPtr\fR argument. If the \fInewLength\fR
|
||||
argument is greater than the space allocated for the object's
|
||||
string, then the string space is reallocated and the old value
|
||||
is copied to the new space; the bytes between the old length of
|
||||
the string and the new length may have arbitrary values.
|
||||
If the \fInewLength\fR argument is less than the current length
|
||||
of the object's string, with \fIobjPtr->length\fR is reduced without
|
||||
reallocating the string space; the original allocated size for the
|
||||
string is recorded in the object, so that the string length can be
|
||||
enlarged in a subsequent call to \fBTcl_SetObjLength\fR without
|
||||
reallocating storage. In all cases \fBTcl_SetObjLength\fR leaves
|
||||
a null character at \fIobjPtr->bytes[newLength]\fR.
|
||||
.PP
|
||||
The \fBTcl_ConcatObj\fR function returns a new string object whose
|
||||
value is the space-separated concatenation of the string
|
||||
representations of all of the objects in the \fIobjv\fR
|
||||
array. \fBTcl_ConcatObj\fR eliminates leading and trailing white space
|
||||
as it copies the string representations of the \fIobjv\fR array to the
|
||||
result. If an element of the \fIobjv\fR array consists of nothing but
|
||||
white space, then that object is ignored entirely. This white-space
|
||||
removal was added to make the output of the \fBconcat\fR command
|
||||
cleaner-looking. \fBTcl_ConcatObj\fR returns a pointer to a
|
||||
newly-created object whose ref count is zero.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount
|
||||
|
||||
.SH KEYWORDS
|
||||
append, internal representation, object, object type, string object,
|
||||
string type, string representation, concat, concatenate
|
||||
@@ -1,181 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Tcl.n 1.128 96/08/26 12:59:50
|
||||
'
|
||||
.so man.macros
|
||||
.TH Tcl n "" Tcl "Tcl Built-In Commands"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl \- Summary of Tcl language syntax.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
The following rules define the syntax and semantics of the Tcl language:
|
||||
.IP [1]
|
||||
A Tcl script is a string containing one or more commands.
|
||||
Semi-colons and newlines are command separators unless quoted as
|
||||
described below.
|
||||
Close brackets are command terminators during command substitution
|
||||
(see below) unless quoted.
|
||||
.IP [2]
|
||||
A command is evaluated in two steps.
|
||||
First, the Tcl interpreter breaks the command into \fIwords\fR
|
||||
and performs substitutions as described below.
|
||||
These substitutions are performed in the same way for all
|
||||
commands.
|
||||
The first word is used to locate a command procedure to
|
||||
carry out the command, then all of the words of the command are
|
||||
passed to the command procedure.
|
||||
The command procedure is free to interpret each of its words
|
||||
in any way it likes, such as an integer, variable name, list,
|
||||
or Tcl script.
|
||||
Different commands interpret their words differently.
|
||||
.IP [3]
|
||||
Words of a command are separated by white space (except for
|
||||
newlines, which are command separators).
|
||||
.IP [4]
|
||||
If the first character of a word is double-quote (``"'') then
|
||||
the word is terminated by the next double-quote character.
|
||||
If semi-colons, close brackets, or white space characters
|
||||
(including newlines) appear between the quotes then they are treated
|
||||
as ordinary characters and included in the word.
|
||||
Command substitution, variable substitution, and backslash substitution
|
||||
are performed on the characters between the quotes as described below.
|
||||
The double-quotes are not retained as part of the word.
|
||||
.IP [5]
|
||||
If the first character of a word is an open brace (``{'') then
|
||||
the word is terminated by the matching close brace (``}'').
|
||||
Braces nest within the word: for each additional open
|
||||
brace there must be an additional close brace (however,
|
||||
if an open brace or close brace within the word is
|
||||
quoted with a backslash then it is not counted in locating the
|
||||
matching close brace).
|
||||
No substitutions are performed on the characters between the
|
||||
braces except for backslash-newline substitutions described
|
||||
below, nor do semi-colons, newlines, close brackets,
|
||||
or white space receive any special interpretation.
|
||||
The word will consist of exactly the characters between the
|
||||
outer braces, not including the braces themselves.
|
||||
.IP [6]
|
||||
If a word contains an open bracket (``['') then Tcl performs
|
||||
\fIcommand substitution\fR.
|
||||
To do this it invokes the Tcl interpreter recursively to process
|
||||
the characters following the open bracket as a Tcl script.
|
||||
The script may contain any number of commands and must be terminated
|
||||
by a close bracket (``]'').
|
||||
The result of the script (i.e. the result of its last command) is
|
||||
substituted into the word in place of the brackets and all of the
|
||||
characters between them.
|
||||
There may be any number of command substitutions in a single word.
|
||||
Command substitution is not performed on words enclosed in braces.
|
||||
.IP [7]
|
||||
If a word contains a dollar-sign (``$'') then Tcl performs \fIvariable
|
||||
substitution\fR: the dollar-sign and the following characters are
|
||||
replaced in the word by the value of a variable.
|
||||
Variable substitution may take any of the following forms:
|
||||
.RS
|
||||
.TP 15
|
||||
\fB$\fIname\fR
|
||||
\fIName\fR is the name of a scalar variable; the name is terminated
|
||||
by any character that isn't a letter, digit, or underscore.
|
||||
.TP 15
|
||||
\fB$\fIname\fB(\fIindex\fB)\fR
|
||||
\fIName\fR gives the name of an array variable and \fIindex\fR gives
|
||||
the name of an element within that array.
|
||||
\fIName\fR must contain only letters, digits, and underscores.
|
||||
Command substitutions, variable substitutions, and backslash
|
||||
substitutions are performed on the characters of \fIindex\fR.
|
||||
.TP 15
|
||||
\fB${\fIname\fB}\fR
|
||||
\fIName\fR is the name of a scalar variable. It may contain any
|
||||
characters whatsoever except for close braces.
|
||||
.LP
|
||||
There may be any number of variable substitutions in a single word.
|
||||
Variable substitution is not performed on words enclosed in braces.
|
||||
.RE
|
||||
.IP [8]
|
||||
If a backslash (``\e'') appears within a word then
|
||||
\fIbackslash substitution\fR occurs.
|
||||
In all cases but those described below the backslash is dropped and
|
||||
the following character is treated as an ordinary
|
||||
character and included in the word.
|
||||
This allows characters such as double quotes, close brackets,
|
||||
and dollar signs to be included in words without triggering
|
||||
special processing.
|
||||
The following table lists the backslash sequences that are
|
||||
handled specially, along with the value that replaces each sequence.
|
||||
.RS
|
||||
.TP 6
|
||||
\e\fBa\fR
|
||||
Audible alert (bell) (0x7).
|
||||
.TP 6
|
||||
\e\fBb\fR
|
||||
Backspace (0x8).
|
||||
.TP 6
|
||||
\e\fBf\fR
|
||||
Form feed (0xc).
|
||||
.TP 6
|
||||
\e\fBn\fR
|
||||
Newline (0xa).
|
||||
.TP 6
|
||||
\e\fBr\fR
|
||||
Carriage-return (0xd).
|
||||
.TP 6
|
||||
\e\fBt\fR
|
||||
Tab (0x9).
|
||||
.TP 6
|
||||
\e\fBv\fR
|
||||
Vertical tab (0xb).
|
||||
.TP 6
|
||||
\e\fB<newline>\fIwhiteSpace\fR
|
||||
A single space character replaces the backslash, newline, and all
|
||||
spaces and tabs after the newline.
|
||||
This backslash sequence is unique in that it is replaced in a separate
|
||||
pre-pass before the command is actually parsed.
|
||||
This means that it will be replaced even when it occurs between
|
||||
braces, and the resulting space will be treated as a word separator
|
||||
if it isn't in braces or quotes.
|
||||
.TP 6
|
||||
\e\e
|
||||
Backslash (``\e'').
|
||||
.TP 6
|
||||
\e\fIooo\fR
|
||||
The digits \fIooo\fR (one, two, or three of them) give the octal value of
|
||||
the character.
|
||||
.TP 6
|
||||
\e\fBx\fIhh\fR
|
||||
The hexadecimal digits \fIhh\fR give the hexadecimal value of
|
||||
the character. Any number of digits may be present.
|
||||
.LP
|
||||
Backslash substitution is not performed on words enclosed in braces,
|
||||
except for backslash-newline as described above.
|
||||
.RE
|
||||
.IP [9]
|
||||
If a hash character (``#'') appears at a point where Tcl is
|
||||
expecting the first character of the first word of a command,
|
||||
then the hash character and the characters that follow it, up
|
||||
through the next newline, are treated as a comment and ignored.
|
||||
The comment character only has significance when it appears
|
||||
at the beginning of a command.
|
||||
.IP [10]
|
||||
Each character is processed exactly once by the Tcl interpreter
|
||||
as part of creating the words of a command.
|
||||
For example, if variable substitution occurs then no further
|
||||
substitutions are performed on the value of the variable; the
|
||||
value is inserted into the word verbatim.
|
||||
If command substitution occurs then the nested command is
|
||||
processed entirely by the recursive call to the Tcl interpreter;
|
||||
no substitutions are performed before making the recursive
|
||||
call and no additional substitutions are performed on the result
|
||||
of the nested script.
|
||||
.IP [11]
|
||||
Substitutions do not affect the word boundaries of a command.
|
||||
For example, during variable substitution the entire value of
|
||||
the variable becomes part of a single word, even if the variable's
|
||||
value contains spaces.
|
||||
@@ -1,61 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Tcl_Main.3 1.8 96/03/25 20:08:33
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_Main 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_Main \- main program for Tcl-based applications
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_Main\fR(\fIargc, argv, appInitProc\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_AppInitProc *appInitProc
|
||||
.AP int argc in
|
||||
Number of elements in \fIargv\fR.
|
||||
.AP char *argv[] in
|
||||
Array of strings containing command-line arguments.
|
||||
.AP Tcl_AppInitProc *appInitProc in
|
||||
Address of an application-specific initialization procedure.
|
||||
The value for this argument is usually \fBTcl_AppInit\fR.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_Main\fR acts as the main program for most Tcl-based applications.
|
||||
Starting with Tcl 7.4 it is not called \fBmain\fR anymore because it
|
||||
is part of the Tcl library and having a function \fBmain\fR
|
||||
in a library (particularly a shared library) causes problems on many
|
||||
systems.
|
||||
Having \fBmain\fR in the Tcl library would also make it hard to use
|
||||
Tcl in C++ programs, since C++ programs must have special C++
|
||||
\fBmain\fR functions.
|
||||
.PP
|
||||
Normally each application contains a small \fBmain\fR function that does
|
||||
nothing but invoke \fBTcl_Main\fR.
|
||||
\fBTcl_Main\fR then does all the work of creating and running a
|
||||
\fBtclsh\fR-like application.
|
||||
.PP
|
||||
When it is has finished its own initialization, but before
|
||||
it processes commands, \fBTcl_Main\fR calls the procedure given by
|
||||
the \fIappInitProc\fR argument. This procedure provides a ``hook''
|
||||
for the application to perform its own initialization, such as defining
|
||||
application-specific commands. The procedure must have an interface
|
||||
that matches the type \fBTcl_AppInitProc\fR:
|
||||
.CS
|
||||
typedef int Tcl_AppInitProc(Tcl_Interp *\fIinterp\fR);
|
||||
.CE
|
||||
\fIAppInitProc\fR is almost always a pointer to \fBTcl_AppInit\fR;
|
||||
for more details on this procedure, see the documentation
|
||||
for \fBTcl_AppInit\fR.
|
||||
|
||||
.SH KEYWORDS
|
||||
application-specific initialization, command-line arguments, main program
|
||||
@@ -1,348 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) TraceVar.3 1.27 97/10/10 15:05:37
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_TraceVar 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_TraceVar, Tcl_TraceVar2, Tcl_UntraceVar, Tcl_UntraceVar2, Tcl_VarTraceInfo, Tcl_VarTraceInfo2 \- monitor accesses to a variable
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_TraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_TraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
|
||||
.sp
|
||||
\fBTcl_UntraceVar(\fIinterp, varName, flags, proc, clientData\fB)\fR
|
||||
.sp
|
||||
\fBTcl_UntraceVar2(\fIinterp, name1, name2, flags, proc, clientData\fB)\fR
|
||||
.sp
|
||||
ClientData
|
||||
\fBTcl_VarTraceInfo(\fIinterp, varName, flags, proc, prevClientData\fB)\fR
|
||||
.sp
|
||||
ClientData
|
||||
\fBTcl_VarTraceInfo2(\fIinterp, name1, name2, flags, proc, prevClientData\fB)\fR
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_VarTraceProc prevClientData
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter containing variable.
|
||||
.AP char *varName in
|
||||
Name of variable. May refer to a scalar variable, to
|
||||
an array variable with no index, or to an array variable
|
||||
with a parenthesized index.
|
||||
If the name references an element of an array, then it
|
||||
must be in writable memory: Tcl will make temporary modifications
|
||||
to it while looking up the name.
|
||||
.AP int flags in
|
||||
OR-ed combination of the values TCL_TRACE_READS, TCL_TRACE_WRITES, and
|
||||
TCL_TRACE_UNSETS, TCL_PARSE_PART1, and TCL_GLOBAL_ONLY.
|
||||
Not all flags are used by all
|
||||
procedures. See below for more information.
|
||||
.AP Tcl_VarTraceProc *proc in
|
||||
Procedure to invoke whenever one of the traced operations occurs.
|
||||
.AP ClientData clientData in
|
||||
Arbitrary one-word value to pass to \fIproc\fR.
|
||||
.AP char *name1 in
|
||||
Name of scalar or array variable (without array index).
|
||||
.AP char *name2 in
|
||||
For a trace on an element of an array, gives the index of the
|
||||
element. For traces on scalar variables or on whole arrays,
|
||||
is NULL.
|
||||
.AP ClientData prevClientData in
|
||||
If non-NULL, gives last value returned by \fBTcl_VarTraceInfo\fR or
|
||||
\fBTcl_VarTraceInfo2\fR, so this call will return information about
|
||||
next trace. If NULL, this call will return information about first
|
||||
trace.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_TraceVar\fR allows a C procedure to monitor and control
|
||||
access to a Tcl variable, so that the C procedure is invoked
|
||||
whenever the variable is read or written or unset.
|
||||
If the trace is created successfully then \fBTcl_TraceVar\fR returns
|
||||
TCL_OK. If an error occurred (e.g. \fIvarName\fR specifies an element
|
||||
of an array, but the actual variable isn't an array) then TCL_ERROR
|
||||
is returned and an error message is left in \fIinterp->result\fR.
|
||||
.PP
|
||||
The \fIflags\fR argument to \fBTcl_TraceVar\fR indicates when the
|
||||
trace procedure is to be invoked and provides information
|
||||
for setting up the trace. It consists of an OR-ed combination
|
||||
of any of the following values:
|
||||
.TP
|
||||
\fBTCL_GLOBAL_ONLY\fR
|
||||
Normally, the variable will be looked up at the current level of
|
||||
procedure call; if this bit is set then the variable will be looked
|
||||
up at global level, ignoring any active procedures.
|
||||
.TP
|
||||
\fBTCL_TRACE_READS\fR
|
||||
Invoke \fIproc\fR whenever an attempt is made to read the variable.
|
||||
.TP
|
||||
\fBTCL_TRACE_WRITES\fR
|
||||
Invoke \fIproc\fR whenever an attempt is made to modify the variable.
|
||||
.TP
|
||||
\fBTCL_TRACE_UNSETS\fR
|
||||
Invoke \fIproc\fR whenever the variable is unset.
|
||||
A variable may be unset either explicitly by an \fBunset\fR command,
|
||||
or implicitly when a procedure returns (its local variables are
|
||||
automatically unset) or when the interpreter is deleted (all
|
||||
variables are automatically unset).
|
||||
.PP
|
||||
Whenever one of the specified operations occurs on the variable,
|
||||
\fIproc\fR will be invoked.
|
||||
It should have arguments and result that match the type
|
||||
\fBTcl_VarTraceProc\fR:
|
||||
.CS
|
||||
typedef char *Tcl_VarTraceProc(
|
||||
ClientData \fIclientData\fR,
|
||||
Tcl_Interp *\fIinterp\fR,
|
||||
char *\fIname1\fR,
|
||||
char *\fIname2\fR,
|
||||
int \fIflags\fR);
|
||||
.CE
|
||||
The \fIclientData\fR and \fIinterp\fR parameters will
|
||||
have the same values as those passed to \fBTcl_TraceVar\fR when the
|
||||
trace was created.
|
||||
\fIClientData\fR typically points to an application-specific
|
||||
data structure that describes what to do when \fIproc\fR
|
||||
is invoked.
|
||||
\fIName1\fR and \fIname2\fR give the name of the traced variable
|
||||
in the normal two-part form (see the description of \fBTcl_TraceVar2\fR
|
||||
below for details).
|
||||
\fIFlags\fR is an OR-ed combination of bits providing several
|
||||
pieces of information.
|
||||
One of the bits TCL_TRACE_READS, TCL_TRACE_WRITES, or TCL_TRACE_UNSETS
|
||||
will be set in \fIflags\fR to indicate which operation is being performed
|
||||
on the variable.
|
||||
The bit TCL_GLOBAL_ONLY will be set whenever the variable being
|
||||
accessed is a global one not accessible from the current level of
|
||||
procedure call: the trace procedure will need to pass this flag
|
||||
back to variable-related procedures like \fBTcl_GetVar\fR if it
|
||||
attempts to access the variable.
|
||||
The bit TCL_TRACE_DESTROYED will be set in \fIflags\fR if the trace is
|
||||
about to be destroyed; this information may be useful to \fIproc\fR
|
||||
so that it can clean up its own internal data structures (see
|
||||
the section TCL_TRACE_DESTROYED below for more details).
|
||||
Lastly, the bit TCL_INTERP_DESTROYED will be set if the entire
|
||||
interpreter is being destroyed.
|
||||
When this bit is set, \fIproc\fR must be especially careful in
|
||||
the things it does (see the section TCL_INTERP_DESTROYED below).
|
||||
The trace procedure's return value should normally be NULL; see
|
||||
ERROR RETURNS below for information on other possibilities.
|
||||
.PP
|
||||
\fBTcl_UntraceVar\fR may be used to remove a trace.
|
||||
If the variable specified by \fIinterp\fR, \fIvarName\fR, and \fIflags\fR
|
||||
has a trace set with \fIflags\fR, \fIproc\fR, and
|
||||
\fIclientData\fR, then the corresponding trace is removed.
|
||||
If no such trace exists, then the call to \fBTcl_UntraceVar\fR
|
||||
has no effect.
|
||||
The same bits are valid for \fIflags\fR as for calls to \fBTcl_TraceVar\fR.
|
||||
.PP
|
||||
\fBTcl_VarTraceInfo\fR may be used to retrieve information about
|
||||
traces set on a given variable.
|
||||
The return value from \fBTcl_VarTraceInfo\fR is the \fIclientData\fR
|
||||
associated with a particular trace.
|
||||
The trace must be on the variable specified by the \fIinterp\fR,
|
||||
\fIvarName\fR, and \fIflags\fR arguments (only the TCL_GLOBAL_ONLY
|
||||
bit from \fIflags\fR is used; other bits are ignored) and its trace procedure
|
||||
must the same as the \fIproc\fR argument.
|
||||
If the \fIprevClientData\fR argument is NULL then the return
|
||||
value corresponds to the first (most recently created) matching
|
||||
trace, or NULL if there are no matching traces.
|
||||
If the \fIprevClientData\fR argument isn't NULL, then it should
|
||||
be the return value from a previous call to \fBTcl_VarTraceInfo\fR.
|
||||
In this case, the new return value will correspond to the next
|
||||
matching trace after the one whose \fIclientData\fR matches
|
||||
\fIprevClientData\fR, or NULL if no trace matches \fIprevClientData\fR
|
||||
or if there are no more matching traces after it.
|
||||
This mechanism makes it possible to step through all of the
|
||||
traces for a given variable that have the same \fIproc\fR.
|
||||
|
||||
.SH "TWO-PART NAMES"
|
||||
.PP
|
||||
The procedures \fBTcl_TraceVar2\fR, \fBTcl_UntraceVar2\fR, and
|
||||
\fBTcl_VarTraceInfo2\fR are identical to \fBTcl_TraceVar\fR,
|
||||
\fBTcl_UntraceVar\fR, and \fBTcl_VarTraceInfo\fR, respectively,
|
||||
except that the name of the variable consists of two parts.
|
||||
\fIName1\fR gives the name of a scalar variable or array,
|
||||
and \fIname2\fR gives the name of an element within an array.
|
||||
If \fIname2\fR is NULL it means that either the variable is
|
||||
a scalar or the trace is to be set on the entire array rather
|
||||
than an individual element (see WHOLE-ARRAY TRACES below for
|
||||
more information).
|
||||
As a special case, if the flag TCL_PARSE_PART1 is specified,
|
||||
\fIname1\fR may contain both an array and an element name:
|
||||
if the name contains an open parenthesis and ends with a
|
||||
close parenthesis, then the value between the parentheses is
|
||||
treated as an element name (which can have any string value) and
|
||||
the characters before the first open
|
||||
parenthesis are treated as the name of an array variable.
|
||||
If the flag TCL_PARSE_PART1 is given,
|
||||
\fIname2\fR should be NULL since the array and element names
|
||||
are taken from \fIname1\fR.
|
||||
|
||||
.SH "ACCESSING VARIABLES DURING TRACES"
|
||||
.PP
|
||||
During read and write traces, the
|
||||
trace procedure can read, write, or unset the traced
|
||||
variable using \fBTcl_GetVar2\fR, \fBTcl_SetVar2\fR, and
|
||||
other procedures.
|
||||
While \fIproc\fR is executing, traces are temporarily disabled
|
||||
for the variable, so that calls to \fBTcl_GetVar2\fR and
|
||||
\fBTcl_SetVar2\fR will not cause \fIproc\fR or other trace procedures
|
||||
to be invoked again.
|
||||
Disabling only occurs for the variable whose trace procedure
|
||||
is active; accesses to other variables will still be traced.
|
||||
However, if a variable is unset during a read or write trace then unset
|
||||
traces will be invoked.
|
||||
.PP
|
||||
During unset traces the variable has already been completely
|
||||
expunged.
|
||||
It is possible for the trace procedure to read or write the
|
||||
variable, but this will be a new version of the variable.
|
||||
Traces are not disabled during unset traces as they are for
|
||||
read and write traces, but existing traces have been removed
|
||||
from the variable before any trace procedures are invoked.
|
||||
If new traces are set by unset trace procedures, these traces
|
||||
will be invoked on accesses to the variable by the trace
|
||||
procedures.
|
||||
|
||||
.SH "CALLBACK TIMING"
|
||||
.PP
|
||||
When read tracing has been specified for a variable, the trace
|
||||
procedure will be invoked whenever the variable's value is
|
||||
read. This includes \fBset\fR Tcl commands, \fB$\fR-notation
|
||||
in Tcl commands, and invocations of the \fBTcl_GetVar\fR
|
||||
and \fBTcl_GetVar2\fR procedures.
|
||||
\fIProc\fR is invoked just before the variable's value is
|
||||
returned.
|
||||
It may modify the value of the variable to affect what
|
||||
is returned by the traced access.
|
||||
If it unsets the variable then the access will return an error
|
||||
just as if the variable never existed.
|
||||
.PP
|
||||
When write tracing has been specified for a variable, the
|
||||
trace procedure will be invoked whenever the variable's value
|
||||
is modified. This includes \fBset\fR commands,
|
||||
commands that modify variables as side effects (such as
|
||||
\fBcatch\fR and \fBscan\fR), and calls to the \fBTcl_SetVar\fR
|
||||
and \fBTcl_SetVar2\fR procedures).
|
||||
\fIProc\fR will be invoked after the variable's value has been
|
||||
modified, but before the new value of the variable has been
|
||||
returned.
|
||||
It may modify the value of the variable to override the change
|
||||
and to determine the value actually returned by the traced
|
||||
access.
|
||||
If it deletes the variable then the traced access will return
|
||||
an empty string.
|
||||
.PP
|
||||
When unset tracing has been specified, the trace procedure
|
||||
will be invoked whenever the variable is destroyed.
|
||||
The traces will be called after the variable has been
|
||||
completely unset.
|
||||
|
||||
.SH "WHOLE-ARRAY TRACES"
|
||||
.PP
|
||||
If a call to \fBTcl_TraceVar\fR or \fBTcl_TraceVar2\fR specifies
|
||||
the name of an array variable without an index into the array,
|
||||
then the trace will be set on the array as a whole.
|
||||
This means that \fIproc\fR will be invoked whenever any
|
||||
element of the array is accessed in the ways specified by
|
||||
\fIflags\fR.
|
||||
When an array is unset, a whole-array trace will be invoked
|
||||
just once, with \fIname1\fR equal to the name of the array
|
||||
and \fIname2\fR NULL; it will not be invoked once for each
|
||||
element.
|
||||
|
||||
.SH "MULTIPLE TRACES"
|
||||
.PP
|
||||
It is possible for multiple traces to exist on the same variable.
|
||||
When this happens, all of the trace procedures will be invoked on each
|
||||
access, in order from most-recently-created to least-recently-created.
|
||||
When there exist whole-array traces for an array as well as
|
||||
traces on individual elements, the whole-array traces are invoked
|
||||
before the individual-element traces.
|
||||
If a read or write trace unsets the variable then all of the unset
|
||||
traces will be invoked but the remainder of the read and write traces
|
||||
will be skipped.
|
||||
|
||||
.SH "ERROR RETURNS"
|
||||
.PP
|
||||
Under normal conditions trace procedures should return NULL, indicating
|
||||
successful completion.
|
||||
If \fIproc\fR returns a non-NULL value it signifies that an
|
||||
error occurred.
|
||||
The return value must be a pointer to a static character string
|
||||
containing an error message.
|
||||
If a trace procedure returns an error, no further traces are
|
||||
invoked for the access and the traced access aborts with the
|
||||
given message.
|
||||
Trace procedures can use this facility to make variables
|
||||
read-only, for example (but note that the value of the variable
|
||||
will already have been modified before the trace procedure is
|
||||
called, so the trace procedure will have to restore the correct
|
||||
value).
|
||||
.PP
|
||||
The return value from \fIproc\fR is only used during read and
|
||||
write tracing.
|
||||
During unset traces, the return value is ignored and all relevant
|
||||
trace procedures will always be invoked.
|
||||
|
||||
.SH "RESTRICTIONS"
|
||||
.PP
|
||||
A trace procedure can be called at any time, even when there
|
||||
is a partially-formed result in the interpreter's result area. If
|
||||
the trace procedure does anything that could damage this result (such
|
||||
as calling \fBTcl_Eval\fR) then it must save the original values of
|
||||
the interpreter's \fBresult\fR and \fBfreeProc\fR fields and restore
|
||||
them before it returns.
|
||||
|
||||
.SH "UNDEFINED VARIABLES"
|
||||
.PP
|
||||
It is legal to set a trace on an undefined variable.
|
||||
The variable will still appear to be undefined until the
|
||||
first time its value is set.
|
||||
If an undefined variable is traced and then unset, the unset will fail
|
||||
with an error (``no such variable''), but the trace
|
||||
procedure will still be invoked.
|
||||
|
||||
.SH "TCL_TRACE_DESTROYED FLAG"
|
||||
.PP
|
||||
In an unset callback to \fIproc\fR, the TCL_TRACE_DESTROYED bit
|
||||
is set in \fIflags\fR if the trace is being removed as part
|
||||
of the deletion.
|
||||
Traces on a variable are always removed whenever the variable
|
||||
is deleted; the only time TCL_TRACE_DESTROYED isn't set is for
|
||||
a whole-array trace invoked when only a single element of an
|
||||
array is unset.
|
||||
|
||||
.SH "TCL_INTERP_DESTROYED"
|
||||
.PP
|
||||
When an interpreter is destroyed, unset traces are called for
|
||||
all of its variables.
|
||||
The TCL_INTERP_DESTROYED bit will be set in the \fIflags\fR
|
||||
argument passed to the trace procedures.
|
||||
Trace procedures must be extremely careful in what they do if
|
||||
the TCL_INTERP_DESTROYED bit is set.
|
||||
It is not safe for the procedures to invoke any Tcl procedures
|
||||
on the interpreter, since its state is partially deleted.
|
||||
All that trace procedures should do under these circumstances is
|
||||
to clean up and free their own internal data structures.
|
||||
|
||||
.SH BUGS
|
||||
.PP
|
||||
Tcl doesn't do any error checking to prevent trace procedures
|
||||
from misusing the interpreter during traces with TCL_INTERP_DESTROYED
|
||||
set.
|
||||
|
||||
.SH KEYWORDS
|
||||
clientData, trace, variable
|
||||
@@ -1,66 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) Translate.3 1.22 96/08/26 12:59:51
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_TranslateFileName 3 7.5 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_TranslateFileName \- convert file name to native form and replace tilde with home directory
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
char *
|
||||
\fBTcl_TranslateFileName\fR(\fIinterp\fR, \fIname\fR, \fIbufferPtr\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_DString *bufferPtr
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter in which to report an error, if any.
|
||||
.AP char *name in
|
||||
File name, which may start with a ``~''.
|
||||
.AP Tcl_DString *bufferPtr in/out
|
||||
If needed, this dynamic string is used to store the new file name.
|
||||
At the time of the call it should be uninitialized or empty. The
|
||||
caller must eventually call \fBTcl_DStringFree\fR to free up
|
||||
anything stored here.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This utility procedure translates a file name to a form suitable for
|
||||
passing to the local operating system. It converts network names into
|
||||
native form and does tilde substitution.
|
||||
.PP
|
||||
If
|
||||
\fBTcl_TranslateFileName\fR has to do tilde substitution or translate
|
||||
the name then it uses
|
||||
the dynamic string at \fI*bufferPtr\fR to hold the new string it
|
||||
generates.
|
||||
After \fBTcl_TranslateFileName\fR returns a non-NULL result, the caller must
|
||||
eventually invoke \fBTcl_DStringFree\fR to free any information
|
||||
placed in \fI*bufferPtr\fR. The caller need not know whether or
|
||||
not \fBTcl_TranslateFileName\fR actually used the string; \fBTcl_TranslateFileName\fR
|
||||
initializes \fI*bufferPtr\fR even if it doesn't use it, so the call to
|
||||
\fBTcl_DStringFree\fR will be safe in either case.
|
||||
.PP
|
||||
If an error occurs (e.g. because there was no user by the given
|
||||
name) then NULL is returned and an error message will be left
|
||||
at \fIinterp->result\fR.
|
||||
When an error occurs, \fBTcl_TranslateFileName\fR
|
||||
frees the dynamic string itself so that the caller need not call
|
||||
\fBTcl_DStringFree\fR.
|
||||
.PP
|
||||
The caller is responsible for making sure that \fIinterp->result\fR
|
||||
has its default empty value when \fBTcl_TranslateFileName\fR is invoked.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
filename
|
||||
|
||||
.SH KEYWORDS
|
||||
file name, home directory, tilde, translate, user
|
||||
@@ -1,76 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) UpVar.3 1.6 96/03/25 20:09:19
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_UpVar 3 7.4 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_UpVar, Tcl_UpVar2 \- link one variable to another
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_UpVar(\fIinterp, frameName, sourceName, destName, flags\fB)\fR
|
||||
.sp
|
||||
int
|
||||
\fBTcl_UpVar2(\fIinterp, frameName, name1, name2, destName, flags\fB)\fR
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_VarTraceProc prevClientData
|
||||
.AP Tcl_Interp *interp in
|
||||
Interpreter containing variables; also used for error reporting.
|
||||
.AP char *frameName in
|
||||
Identifies the stack frame containing source variable.
|
||||
May have any of the forms accepted by
|
||||
the \fBupvar\fR command, such as \fB#0\fR or \fB1\fR.
|
||||
.AP char *sourceName in
|
||||
Name of source variable, in the frame given by \fIframeName\fR.
|
||||
May refer to a scalar variable or to an array variable with a
|
||||
parenthesized index.
|
||||
.AP char *destName in
|
||||
Name of destination variable, which is to be linked to source
|
||||
variable so that references to \fIdestName\fR
|
||||
refer to the other variable. Must not currently exist except as
|
||||
an upvar-ed variable.
|
||||
.AP int flags in
|
||||
Either TCL_GLOBAL_ONLY or 0; if non-zero, then \fIdestName\fR is
|
||||
a global variable; otherwise it is a local to the current procedure
|
||||
(or global if no procedure is active).
|
||||
.AP char *name1 in
|
||||
First part of source variable's name (scalar name, or name of array
|
||||
without array index).
|
||||
.AP char *name2 in
|
||||
If source variable is an element of an array, gives the index of the element.
|
||||
For scalar source variables, is NULL.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_UpVar\fR and \fBTcl_UpVar2\fR provide the same functionality
|
||||
as the \fBupvar\fR command: they make a link from a source variable
|
||||
to a destination variable, so that references to the destination are
|
||||
passed transparently through to the source.
|
||||
The name of the source variable may be specified either as a single
|
||||
string such as \fBxyx\fR or \fBa(24)\fR (by calling \fBTcl_UpVar\fR)
|
||||
or in two parts where the array name has been separated from the
|
||||
element name (by calling \fBTcl_UpVar2\fR).
|
||||
The destination variable name is specified in a single string; it
|
||||
may not be an array element.
|
||||
.PP
|
||||
Both procedures return either TCL_OK or TCL_ERROR, and they
|
||||
leave an error message in \fIinterp->result\fR if an error
|
||||
occurs.
|
||||
.PP
|
||||
As with the \fBupvar\fR command, the source variable need not exist;
|
||||
if it does exist, unsetting it later does not destroy the link. The
|
||||
destination variable may exist at the time of the call, but if so
|
||||
it must exist as a linked variable.
|
||||
|
||||
.SH KEYWORDS
|
||||
linked variable, upvar, variable
|
||||
@@ -1,79 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1994-1997 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) @(#) WrongNumArgs.3 1.5 97/07/30 16:20:07
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH Tcl_WrongNumArgs 3 8.0 Tcl "Tcl Library Procedures"
|
||||
.BS
|
||||
.SH NAME
|
||||
Tcl_WrongNumArgs \- generate standard error message for wrong number of arguments
|
||||
.SH SYNOPSIS
|
||||
.nf
|
||||
\fB#include <tcl.h>\fR
|
||||
.sp
|
||||
\fBTcl_WrongNumArgs\fR(\fIinterp, objc, objv, message\fR)
|
||||
.SH ARGUMENTS
|
||||
.AS Tcl_Interp "*CONST objv[]"
|
||||
.AP Tcl_Interp interp in
|
||||
Interpreter in which error will be reported: error message gets stored
|
||||
in its result object.
|
||||
.AP int objc in
|
||||
Number of leading arguments from \fIobjv\fR to include in error
|
||||
message.
|
||||
.TP
|
||||
Tcl_Obj *CONST \fIobjv\fR[] (in)
|
||||
Arguments to command that had the wrong number of arguments.
|
||||
.AP char *message in
|
||||
Additional error information to print after leading arguments
|
||||
from \fIobjv\fR. This typically gives the acceptable syntax
|
||||
of the command. This argument may be NULL.
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
\fBTcl_WrongNumArgs\fR is a utility procedure that is invoked by
|
||||
command procedures when they discover that they have received the
|
||||
wrong number of arguments. \fBTcl_WrongNumArgs\fR generates a
|
||||
standard error message and stores it in the result object of
|
||||
\fIinterp\fR. The message includes the \fIobjc\fR initial
|
||||
elements of \fIobjv\fR plus \fImessage\fR. For example, if
|
||||
\fIobjv\fR consists of the values \fBfoo\fR and \fBbar\fR,
|
||||
\fIobjc\fR is 1, and \fImessage\fR is ``\fBfileName count\fR''
|
||||
then \fIinterp\fR's result object will be set to the following
|
||||
string:
|
||||
.CS
|
||||
wrong # args: should be "foo fileName count"
|
||||
.CE
|
||||
If \fIobjc\fR is 2, the result will be set to the following string:
|
||||
.CS
|
||||
wrong # args: should be "foo bar fileName count"
|
||||
.CE
|
||||
\fIObjc\fR is usually 1, but may be 2 or more for commands like
|
||||
\fBstring\fR and the Tk widget commands, which use the first argument
|
||||
as a subcommand.
|
||||
.PP
|
||||
Some of the objects in the \fIobjv\fR array may be abbreviations for
|
||||
a subcommand. The command
|
||||
\fBTcl_GetIndexFromObj\fR will convert the abbreviated string object
|
||||
into an \fIindexObject\fR. If an error occurs in the parsing of the
|
||||
subcommand we would like to use the full subcommand name rather than
|
||||
the abbreviation. If the \fBTcl_WrongNumArgs\fR command finds any
|
||||
\fIindexObjects\fR in the \fIobjv\fR array it will use the full subcommand
|
||||
name in the error message instead of the abbreviated name that was
|
||||
origionally passed in. Using the above example, lets assume that
|
||||
\fIbar\fR is actually an abbreviation for \fIbarfly\fR and the object
|
||||
is now an indexObject becasue it was passed to
|
||||
\fBTcl_GetIndexFromObj\fR. In this case the error message would be:
|
||||
.CS
|
||||
wrong # args: should be "foo barfly fileName count"
|
||||
.CE
|
||||
|
||||
.SH "SEE ALSO"
|
||||
Tcl_GetIndexFromObj
|
||||
|
||||
.SH KEYWORDS
|
||||
command, error message, wrong number of arguments
|
||||
@@ -1,109 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1990-1994 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) after.n 1.4 96/03/25 20:09:33
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH after n 7.5 Tcl "Tcl Built-In Commands"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
after \- Execute a command after a time delay
|
||||
.SH SYNOPSIS
|
||||
\fBafter \fIms\fR
|
||||
.sp
|
||||
\fBafter \fIms \fR?\fIscript script script ...\fR?
|
||||
.sp
|
||||
\fBafter cancel \fIid\fR
|
||||
.sp
|
||||
\fBafter cancel \fIscript script script ...\fR
|
||||
.sp
|
||||
\fBafter idle \fR?\fIscript script script ...\fR?
|
||||
.sp
|
||||
\fBafter info \fR?\fIid\fR?
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
This command is used to delay execution of the program or to execute
|
||||
a command in background sometime in the future. It has several forms,
|
||||
depending on the first argument to the command:
|
||||
.TP
|
||||
\fBafter \fIms\fR
|
||||
\fIMs\fR must be an integer giving a time in milliseconds.
|
||||
The command sleeps for \fIms\fR milliseconds and then returns.
|
||||
While the command is sleeping the application does not respond to
|
||||
events.
|
||||
.TP
|
||||
\fBafter \fIms \fR?\fIscript script script ...\fR?
|
||||
In this form the command returns immediately, but it arranges
|
||||
for a Tcl command to be executed \fIms\fR milliseconds later as an
|
||||
event handler.
|
||||
The command will be executed exactly once, at the given time.
|
||||
The delayed command is formed by concatenating all the \fIscript\fR
|
||||
arguments in the same fashion as the \fBconcat\fR command.
|
||||
The command will be executed at global level (outside the context
|
||||
of any Tcl procedure).
|
||||
If an error occurs while executing the delayed command then the
|
||||
\fBbgerror\fR mechanism is used to report the error.
|
||||
The \fBafter\fR command returns an identifier that can be used
|
||||
to cancel the delayed command using \fBafter cancel\fR.
|
||||
.TP
|
||||
\fBafter cancel \fIid\fR
|
||||
Cancels the execution of a delayed command that
|
||||
was previously scheduled.
|
||||
\fIId\fR indicates which command should be canceled; it must have
|
||||
been the return value from a previous \fBafter\fR command.
|
||||
If the command given by \fIid\fR has already been executed then
|
||||
the \fBafter cancel\fR command has no effect.
|
||||
.TP
|
||||
\fBafter cancel \fIscript script ...\fR
|
||||
This command also cancels the execution of a delayed command.
|
||||
The \fIscript\fR arguments are concatenated together with space
|
||||
separators (just as in the \fBconcat\fR command).
|
||||
If there is a pending command that matches the string, it is
|
||||
cancelled and will never be executed; if no such command is
|
||||
currently pending then the \fBafter cancel\fR command has no effect.
|
||||
.TP
|
||||
\fBafter idle \fIscript \fR?\fIscript script ...\fR?
|
||||
Concatenates the \fIscript\fR arguments together with space
|
||||
separators (just as in the \fBconcat\fR command), and arranges
|
||||
for the resulting script to be evaluated later as an idle callback.
|
||||
The script will be run exactly once, the next time the event
|
||||
loop is entered and there are no events to process.
|
||||
The command returns an identifier that can be used
|
||||
to cancel the delayed command using \fBafter cancel\fR.
|
||||
If an error occurs while executing the script then the
|
||||
\fBbgerror\fR mechanism is used to report the error.
|
||||
.TP
|
||||
\fBafter info \fR?\fIid\fR?
|
||||
This command returns information about existing event handlers.
|
||||
If no \fIid\fR argument is supplied, the command returns
|
||||
a list of the identifiers for all existing
|
||||
event handlers created by the \fBafter\fR command for this
|
||||
interpreter.
|
||||
If \fIid\fR is supplied, it specifies an existing handler;
|
||||
\fIid\fR must have been the return value from some previous call
|
||||
to \fBafter\fR and it must not have triggered yet or been cancelled.
|
||||
In this case the command returns a list with two elements.
|
||||
The first element of the list is the script associated
|
||||
with \fIid\fR, and the second element is either
|
||||
\fBidle\fR or \fBtimer\fR to indicate what kind of event
|
||||
handler it is.
|
||||
.LP
|
||||
The \fBafter \fIms\fR and \fBafter idle\fR forms of the command
|
||||
assume that the application is event driven: the delayed commands
|
||||
will not be executed unless the application enters the event loop.
|
||||
In applications that are not normally event-driven, such as
|
||||
\fBtclsh\fR, the event loop can be entered with the \fBvwait\fR
|
||||
and \fBupdate\fR commands.
|
||||
|
||||
.SH "SEE ALSO"
|
||||
bgerror
|
||||
|
||||
.SH KEYWORDS
|
||||
cancel, delay, idle callback, sleep, time
|
||||
@@ -1,32 +0,0 @@
|
||||
'\"
|
||||
'\" Copyright (c) 1993 The Regents of the University of California.
|
||||
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||||
'\"
|
||||
'\" See the file "license.terms" for information on usage and redistribution
|
||||
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||||
'\"
|
||||
'\" SCCS: @(#) append.n 1.6 96/03/25 20:09:44
|
||||
'\"
|
||||
.so man.macros
|
||||
.TH append n "" Tcl "Tcl Built-In Commands"
|
||||
.BS
|
||||
'\" Note: do not modify the .SH NAME line immediately below!
|
||||
.SH NAME
|
||||
append \- Append to variable
|
||||
.SH SYNOPSIS
|
||||
\fBappend \fIvarName \fR?\fIvalue value value ...\fR?
|
||||
.BE
|
||||
|
||||
.SH DESCRIPTION
|
||||
.PP
|
||||
Append all of the \fIvalue\fR arguments to the current value
|
||||
of variable \fIvarName\fR. If \fIvarName\fR doesn't exist,
|
||||
it is given a value equal to the concatenation of all the
|
||||
\fIvalue\fR arguments.
|
||||
This command provides an efficient way to build up long
|
||||
variables incrementally.
|
||||
For example, ``\fBappend a $b\fR'' is much more efficient than
|
||||
``\fBset a $a$b\fR'' if \fB$a\fR is long.
|
||||
|
||||
.SH KEYWORDS
|
||||
append, variable
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user