util/X86LINUX64/man/man3/Tcl_AppendAllObjTypes.3

   1 '\"
   2 '\" Copyright (c) 1996-1997 Sun Microsystems, Inc.
   3 '\"
   4 '\" See the file "license.terms" for information on usage and redistribution
   5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   6 '\"
   7 .TH Tcl_ObjType 3 8.0 Tcl "Tcl Library Procedures"
   8 .\" The -*- nroff -*- definitions below are for supplemental macros used
   9 .\" in Tcl/Tk manual entries.
  10 .\"
  11 .\" .AP type name in/out ?indent?
  12 .\"     Start paragraph describing an argument to a library procedure.
  13 .\"     type is type of argument (int, etc.), in/out is either "in", "out",
  14 .\"     or "in/out" to describe whether procedure reads or modifies arg,
  15 .\"     and indent is equivalent to second arg of .IP (shouldn't ever be
  16 .\"     needed;  use .AS below instead)
  17 .\"
  18 .\" .AS ?type? ?name?
  19 .\"     Give maximum sizes of arguments for setting tab stops.  Type and
  20 .\"     name are examples of largest possible arguments that will be passed
  21 .\"     to .AP later.  If args are omitted, default tab stops are used.
  22 .\"
  23 .\" .BS
  24 .\"     Start box enclosure.  From here until next .BE, everything will be
  25 .\"     enclosed in one large box.
  26 .\"
  27 .\" .BE
  28 .\"     End of box enclosure.
  29 .\"
  30 .\" .CS
  31 .\"     Begin code excerpt.
  32 .\"
  33 .\" .CE
  34 .\"     End code excerpt.
  35 .\"
  36 .\" .VS ?version? ?br?
  37 .\"     Begin vertical sidebar, for use in marking newly-changed parts
  38 .\"     of man pages.  The first argument is ignored and used for recording
  39 .\"     the version when the .VS was added, so that the sidebars can be
  40 .\"     found and removed when they reach a certain age.  If another argument
  41 .\"     is present, then a line break is forced before starting the sidebar.
  42 .\"
  43 .\" .VE
  44 .\"     End of vertical sidebar.
  45 .\"
  46 .\" .DS
  47 .\"     Begin an indented unfilled display.
  48 .\"
  49 .\" .DE
  50 .\"     End of indented unfilled display.
  51 .\"
  52 .\" .SO ?manpage?
  53 .\"     Start of list of standard options for a Tk widget. The manpage
  54 .\"     argument defines where to look up the standard options; if
  55 .\"     omitted, defaults to "options". The options follow on successive
  56 .\"     lines, in three columns separated by tabs.
  57 .\"
  58 .\" .SE
  59 .\"     End of list of standard options for a Tk widget.
  60 .\"
  61 .\" .OP cmdName dbName dbClass
  62 .\"     Start of description of a specific option.  cmdName gives the
  63 .\"     option's name as specified in the class command, dbName gives
  64 .\"     the option's name in the option database, and dbClass gives
  65 .\"     the option's class in the option database.
  66 .\"
  67 .\" .UL arg1 arg2
  68 .\"     Print arg1 underlined, then print arg2 normally.
  69 .\"
  70 .\" .QW arg1 ?arg2?
  71 .\"     Print arg1 in quotes, then arg2 normally (for trailing punctuation).
  72 .\"
  73 .\" .PQ arg1 ?arg2?
  74 .\"     Print an open parenthesis, arg1 in quotes, then arg2 normally
  75 .\"     (for trailing punctuation) and then a closing parenthesis.
  76 .\"
  77 .\"     # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
  78 .if t .wh -1.3i ^B
  79 .nr ^l \n(.l
  80 .ad b
  81 .\"     # Start an argument description
  82 .de AP
  83 .ie !"\\$4"" .TP \\$4
  84 .el \{\
  85 .   ie !"\\$2"" .TP \\n()Cu
  86 .   el          .TP 15
  87 .\}
  88 .ta \\n()Au \\n()Bu
  89 .ie !"\\$3"" \{\
  90 \&\\$1 \\fI\\$2\\fP (\\$3)
  91 .\".b
  92 .\}
  93 .el \{\
  94 .br
  95 .ie !"\\$2"" \{\
  96 \&\\$1  \\fI\\$2\\fP
  97 .\}
  98 .el \{\
  99 \&\\fI\\$1\\fP
 100 .\}
 101 .\}
 102 ..
 103 .\"     # define tabbing values for .AP
 104 .de AS
 105 .nr )A 10n
 106 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
 107 .nr )B \\n()Au+15n
 108 .\"
 109 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
 110 .nr )C \\n()Bu+\\w'(in/out)'u+2n
 111 ..
 112 .AS Tcl_Interp Tcl_CreateInterp in/out
 113 .\"     # BS - start boxed text
 114 .\"     # ^y = starting y location
 115 .\"     # ^b = 1
 116 .de BS
 117 .br
 118 .mk ^y
 119 .nr ^b 1u
 120 .if n .nf
 121 .if n .ti 0
 122 .if n \l'\\n(.lu\(ul'
 123 .if n .fi
 124 ..
 125 .\"     # BE - end boxed text (draw box now)
 126 .de BE
 127 .nf
 128 .ti 0
 129 .mk ^t
 130 .ie n \l'\\n(^lu\(ul'
 131 .el \{\
 132 .\"     Draw four-sided box normally, but don't draw top of
 133 .\"     box if the box started on an earlier page.
 134 .ie !\\n(^b-1 \{\
 135 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 136 .\}
 137 .el \}\
 138 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
 139 .\}
 140 .\}
 141 .fi
 142 .br
 143 .nr ^b 0
 144 ..
 145 .\"     # VS - start vertical sidebar
 146 .\"     # ^Y = starting y location
 147 .\"     # ^v = 1 (for troff;  for nroff this doesn't matter)
 148 .de VS
 149 .if !"\\$2"" .br
 150 .mk ^Y
 151 .ie n 'mc \s12\(br\s0
 152 .el .nr ^v 1u
 153 ..
 154 .\"     # VE - end of vertical sidebar
 155 .de VE
 156 .ie n 'mc
 157 .el \{\
 158 .ev 2
 159 .nf
 160 .ti 0
 161 .mk ^t
 162 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
 163 .sp -1
 164 .fi
 165 .ev
 166 .\}
 167 .nr ^v 0
 168 ..
 169 .\"     # Special macro to handle page bottom:  finish off current
 170 .\"     # box/sidebar if in box/sidebar mode, then invoked standard
 171 .\"     # page bottom macro.
 172 .de ^B
 173 .ev 2
 174 'ti 0
 175 'nf
 176 .mk ^t
 177 .if \\n(^b \{\
 178 .\"     Draw three-sided box if this is the box's first page,
 179 .\"     draw two sides but no top otherwise.
 180 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 181 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
 182 .\}
 183 .if \\n(^v \{\
 184 .nr ^x \\n(^tu+1v-\\n(^Yu
 185 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
 186 .\}
 187 .bp
 188 'fi
 189 .ev
 190 .if \\n(^b \{\
 191 .mk ^y
 192 .nr ^b 2
 193 .\}
 194 .if \\n(^v \{\
 195 .mk ^Y
 196 .\}
 197 ..
 198 .\"     # DS - begin display
 199 .de DS
 200 .RS
 201 .nf
 202 .sp
 203 ..
 204 .\"     # DE - end display
 205 .de DE
 206 .fi
 207 .RE
 208 .sp
 209 ..
 210 .\"     # SO - start of list of standard options
 211 .de SO
 212 'ie '\\$1'' .ds So \\fBoptions\\fR
 213 'el .ds So \\fB\\$1\\fR
 214 .SH "STANDARD OPTIONS"
 215 .LP
 216 .nf
 217 .ta 5.5c 11c
 218 .ft B
 219 ..
 220 .\"     # SE - end of list of standard options
 221 .de SE
 222 .fi
 223 .ft R
 224 .LP
 225 See the \\*(So manual entry for details on the standard options.
 226 ..
 227 .\"     # OP - start of full description for a single option
 228 .de OP
 229 .LP
 230 .nf
 231 .ta 4c
 232 Command-Line Name:      \\fB\\$1\\fR
 233 Database Name:  \\fB\\$2\\fR
 234 Database Class: \\fB\\$3\\fR
 235 .fi
 236 .IP
 237 ..
 238 .\"     # CS - begin code excerpt
 239 .de CS
 240 .RS
 241 .nf
 242 .ta .25i .5i .75i 1i
 243 ..
 244 .\"     # CE - end code excerpt
 245 .de CE
 246 .fi
 247 .RE
 248 ..
 249 .\"     # UL - underline word
 250 .de UL
 251 \\$1\l'|0\(ul'\\$2
 252 ..
 253 .\"     # QW - apply quotation marks to word
 254 .de QW
 255 .ie '\\*(lq'"' ``\\$1''\\$2
 256 .\"" fix emacs highlighting
 257 .el \\*(lq\\$1\\*(rq\\$2
 258 ..
 259 .\"     # PQ - apply parens and quotation marks to word
 260 .de PQ
 261 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
 262 .\"" fix emacs highlighting
 263 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
 264 ..
 265 .\"     # QR - quoted range
 266 .de QR
 267 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
 268 .\"" fix emacs highlighting
 269 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
 270 ..
 271 .\"     # MT - "empty" string
 272 .de MT
 273 .QW ""
 274 ..
 275 .BS
 276 .SH NAME
 277 Tcl_RegisterObjType, Tcl_GetObjType, Tcl_AppendAllObjTypes, Tcl_ConvertToType  \- manipulate Tcl value types
 278 .SH SYNOPSIS
 279 .nf
 280 \fB#include <tcl.h>\fR
 281 .sp
 282 \fBTcl_RegisterObjType\fR(\fItypePtr\fR)
 283 .sp
 284 const Tcl_ObjType *
 285 \fBTcl_GetObjType\fR(\fItypeName\fR)
 286 .sp
 287 int
 288 \fBTcl_AppendAllObjTypes\fR(\fIinterp, objPtr\fR)
 289 .sp
 290 int
 291 \fBTcl_ConvertToType\fR(\fIinterp, objPtr, typePtr\fR)
 292 .SH ARGUMENTS
 293 .AS "const char" *typeName
 294 .AP "const Tcl_ObjType" *typePtr in
 295 Points to the structure containing information about the Tcl value type.
 296 This storage must live forever,
 297 typically by being statically allocated.
 298 .AP "const char" *typeName in
 299 The name of a Tcl value type that \fBTcl_GetObjType\fR should look up.
 300 .AP Tcl_Interp *interp in
 301 Interpreter to use for error reporting.
 302 .AP Tcl_Obj *objPtr in
 303 For \fBTcl_AppendAllObjTypes\fR, this points to the value onto which
 304 it appends the name of each value type as a list element.
 305 For \fBTcl_ConvertToType\fR, this points to a value that
 306 must have been the result of a previous call to \fBTcl_NewObj\fR.
 307 .BE
 308
 309 .SH DESCRIPTION
 310 .PP
 311 The procedures in this man page manage Tcl value types (sometimes
 312 referred to as object types or \fBTcl_ObjType\fRs for historical reasons).
 313 They are used to register new value types, look up types,
 314 and force conversions from one type to another.
 315 .PP
 316 \fBTcl_RegisterObjType\fR registers a new Tcl value type
 317 in the table of all value types that \fBTcl_GetObjType\fR
 318 can look up by name.  There are other value types supported by Tcl
 319 as well, which Tcl chooses not to register.  Extensions can likewise
 320 choose to register the value types they create or not.
 321 The argument \fItypePtr\fR points to a Tcl_ObjType structure that
 322 describes the new type by giving its name
 323 and by supplying pointers to four procedures
 324 that implement the type.
 325 If the type table already contains a type
 326 with the same name as in \fItypePtr\fR,
 327 it is replaced with the new type.
 328 The Tcl_ObjType structure is described
 329 in the section \fBTHE TCL_OBJTYPE STRUCTURE\fR below.
 330 .PP
 331 \fBTcl_GetObjType\fR returns a pointer to the registered Tcl_ObjType
 332 with name \fItypeName\fR.
 333 It returns NULL if no type with that name is registered.
 334 .PP
 335 \fBTcl_AppendAllObjTypes\fR appends the name of each registered value type
 336 as a list element onto the Tcl value referenced by \fIobjPtr\fR.
 337 The return value is \fBTCL_OK\fR unless there was an error
 338 converting \fIobjPtr\fR to a list value;
 339 in that case \fBTCL_ERROR\fR is returned.
 340 .PP
 341 \fBTcl_ConvertToType\fR converts a value from one type to another
 342 if possible.
 343 It creates a new internal representation for \fIobjPtr\fR
 344 appropriate for the target type \fItypePtr\fR
 345 and sets its \fItypePtr\fR member as determined by calling the
 346 \fItypePtr->setFromAnyProc\fR routine.
 347 Any internal representation for \fIobjPtr\fR's old type is freed.
 348 If an error occurs during conversion, it returns \fBTCL_ERROR\fR
 349 and leaves an error message in the result value for \fIinterp\fR
 350 unless \fIinterp\fR is NULL.
 351 Otherwise, it returns \fBTCL_OK\fR.
 352 Passing a NULL \fIinterp\fR allows this procedure to be used
 353 as a test whether the conversion can be done (and in fact was done).
 354 .VS 8.5
 355 .PP
 356 In many cases, the \fItypePtr->setFromAnyProc\fR routine will
 357 set \fIobjPtr->typePtr\fR to the argument value \fItypePtr\fR,
 358 but that is no longer guaranteed.  The \fIsetFromAnyProc\fR is
 359 free to set the internal representation for \fIobjPtr\fR to make
 360 use of another related Tcl_ObjType, if it sees fit.
 361 .VE 8.5
 362 .SH "THE TCL_OBJTYPE STRUCTURE"
 363 .PP
 364 Extension writers can define new value types by defining four
 365 procedures and
 366 initializing a Tcl_ObjType structure to describe the type.
 367 Extension writers may also pass a pointer to their Tcl_ObjType
 368 structure to \fBTcl_RegisterObjType\fR if they wish to permit
 369 other extensions to look up their Tcl_ObjType by name with
 370 the \fBTcl_GetObjType\fR routine.
 371 The \fBTcl_ObjType\fR structure is defined as follows:
 372 .PP
 373 .CS
 374 typedef struct Tcl_ObjType {
 375     const char *\fIname\fR;
 376     Tcl_FreeInternalRepProc *\fIfreeIntRepProc\fR;
 377     Tcl_DupInternalRepProc *\fIdupIntRepProc\fR;
 378     Tcl_UpdateStringProc *\fIupdateStringProc\fR;
 379     Tcl_SetFromAnyProc *\fIsetFromAnyProc\fR;
 380 } \fBTcl_ObjType\fR;
 381 .CE
 382 .SS "THE NAME FIELD"
 383 .PP
 384 The \fIname\fR member describes the name of the type, e.g. \fBint\fR.
 385 When a type is registered, this is the name used by callers
 386 of \fBTcl_GetObjType\fR to lookup the type.  For unregistered
 387 types, the \fIname\fR field is primarily of value for debugging.
 388 The remaining four members are pointers to procedures
 389 called by the generic Tcl value code:
 390 .SS "THE SETFROMANYPROC FIELD"
 391 .PP
 392 The \fIsetFromAnyProc\fR member contains the address of a function
 393 called to create a valid internal representation
 394 from a value's string representation.
 395 .PP
 396 .CS
 397 typedef int \fBTcl_SetFromAnyProc\fR(
 398         Tcl_Interp *\fIinterp\fR,
 399         Tcl_Obj *\fIobjPtr\fR);
 400 .CE
 401 .PP
 402 If an internal representation cannot be created from the string,
 403 it returns \fBTCL_ERROR\fR and puts a message
 404 describing the error in the result value for \fIinterp\fR
 405 unless \fIinterp\fR is NULL.
 406 If \fIsetFromAnyProc\fR is successful,
 407 it stores the new internal representation,
 408 sets \fIobjPtr\fR's \fItypePtr\fR member to point to
 409 the \fBTcl_ObjType\fR struct corresponding to the new
 410 internal representation, and returns \fBTCL_OK\fR.
 411 Before setting the new internal representation,
 412 the \fIsetFromAnyProc\fR must free any internal representation
 413 of \fIobjPtr\fR's old type;
 414 it does this by calling the old type's \fIfreeIntRepProc\fR
 415 if it is not NULL.
 416 .PP
 417 As an example, the \fIsetFromAnyProc\fR for the built-in Tcl list type
 418 gets an up-to-date string representation for \fIobjPtr\fR
 419 by calling \fBTcl_GetStringFromObj\fR.
 420 It parses the string to verify it is in a valid list format and
 421 to obtain each element value in the list, and, if this succeeds,
 422 stores the list elements in \fIobjPtr\fR's internal representation
 423 and sets \fIobjPtr\fR's \fItypePtr\fR member to point to the list type's
 424 Tcl_ObjType structure.
 425 .PP
 426 Do not release \fIobjPtr\fR's old internal representation unless you
 427 replace it with a new one or reset the \fItypePtr\fR member to NULL.
 428 .PP
 429 The \fIsetFromAnyProc\fR member may be set to NULL, if the routines
 430 making use of the internal representation have no need to derive that
 431 internal representation from an arbitrary string value.  However, in
 432 this case, passing a pointer to the type to \fBTcl_ConvertToType\fR will
 433 lead to a panic, so to avoid this possibility, the type
 434 should \fInot\fR be registered.
 435 .SS "THE UPDATESTRINGPROC FIELD"
 436 .PP
 437 The \fIupdateStringProc\fR member contains the address of a function
 438 called to create a valid string representation
 439 from a value's internal representation.
 440 .PP
 441 .CS
 442 typedef void \fBTcl_UpdateStringProc\fR(
 443         Tcl_Obj *\fIobjPtr\fR);
 444 .CE
 445 .PP
 446 \fIobjPtr\fR's \fIbytes\fR member is always NULL when it is called.
 447 It must always set \fIbytes\fR non-NULL before returning.
 448 We require the string representation's byte array
 449 to have a null after the last byte, at offset \fIlength\fR,
 450 and to have no null bytes before that; this allows string representations
 451 to be treated as conventional null character-terminated C strings.
 452 These restrictions are easily met by using Tcl's internal UTF encoding
 453 for the string representation, same as one would do for other
 454 Tcl routines accepting string values as arguments.
 455 Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
 456 or \fBckalloc\fR.  Note that \fIupdateStringProc\fRs must allocate
 457 enough storage for the string's bytes and the terminating null byte.
 458 .PP
 459 The \fIupdateStringProc\fR for Tcl's built-in double type, for example,
 460 calls Tcl_PrintDouble to write to a buffer of size TCL_DOUBLE_SPACE,
 461 then allocates and copies the string representation to just enough
 462 space to hold it.  A pointer to the allocated space is stored in
 463 the \fIbytes\fR member.
 464 .PP
 465 The \fIupdateStringProc\fR member may be set to NULL, if the routines
 466 making use of the internal representation are written so that the
 467 string representation is never invalidated.  Failure to meet this
 468 obligation will lead to panics or crashes when \fBTcl_GetStringFromObj\fR
 469 or other similar routines ask for the string representation.
 470 .SS "THE DUPINTREPPROC FIELD"
 471 .PP
 472 The \fIdupIntRepProc\fR member contains the address of a function
 473 called to copy an internal representation from one value to another.
 474 .PP
 475 .CS
 476 typedef void \fBTcl_DupInternalRepProc\fR(
 477         Tcl_Obj *\fIsrcPtr\fR,
 478         Tcl_Obj *\fIdupPtr\fR);
 479 .CE
 480 .PP
 481 \fIdupPtr\fR's internal representation is made a copy of \fIsrcPtr\fR's
 482 internal representation.
 483 Before the call,
 484 \fIsrcPtr\fR's internal representation is valid and \fIdupPtr\fR's is not.
 485 \fIsrcPtr\fR's value type determines what
 486 copying its internal representation means.
 487 .PP
 488 For example, the \fIdupIntRepProc\fR for the Tcl integer type
 489 simply copies an integer.
 490 The built-in list type's \fIdupIntRepProc\fR uses a far more
 491 sophisticated scheme to continue sharing storage as much as it
 492 reasonably can.
 493 .SS "THE FREEINTREPPROC FIELD"
 494 .PP
 495 The \fIfreeIntRepProc\fR member contains the address of a function
 496 that is called when a value is freed.
 497 .PP
 498 .CS
 499 typedef void \fBTcl_FreeInternalRepProc\fR(
 500         Tcl_Obj *\fIobjPtr\fR);
 501 .CE
 502 .PP
 503 The \fIfreeIntRepProc\fR function can deallocate the storage
 504 for the value's internal representation
 505 and do other type-specific processing necessary when a value is freed.
 506 .PP
 507 For example, the list type's \fIfreeIntRepProc\fR respects
 508 the storage sharing scheme established by the \fIdupIntRepProc\fR
 509 so that it only frees storage when the last value sharing it
 510 is being freed.
 511 .PP
 512 The \fIfreeIntRepProc\fR member can be set to NULL
 513 to indicate that the internal representation does not require freeing.
 514 The \fIfreeIntRepProc\fR implementation must not access the
 515 \fIbytes\fR member of the value, since Tcl makes its own internal
 516 uses of that field during value deletion.  The defined tasks for
 517 the \fIfreeIntRepProc\fR have no need to consult the \fIbytes\fR
 518 member.
 519 .SH "SEE ALSO"
 520 Tcl_NewObj(3), Tcl_DecrRefCount(3), Tcl_IncrRefCount(3)
 521 .SH KEYWORDS
 522 internal representation, value, value type, string representation, type conversion