util/src/TclTk/tcl8.6.12/doc/PkgRequire.3

   1 '\"
   2 '\" Copyright (c) 1996 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_PkgRequire 3 7.5 Tcl "Tcl Library Procedures"
   8 .so man.macros
   9 .BS
  10 .SH NAME
  11 Tcl_PkgRequire, Tcl_PkgRequireEx, Tcl_PkgRequireProc, Tcl_PkgPresent, Tcl_PkgPresentEx, Tcl_PkgProvide, Tcl_PkgProvideEx \- package version control
  12 .SH SYNOPSIS
  13 .nf
  14 \fB#include <tcl.h>\fR
  15 .sp
  16 const char *
  17 \fBTcl_PkgRequire\fR(\fIinterp, name, version, exact\fR)
  18 .sp
  19 const char *
  20 \fBTcl_PkgRequireEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
  21 .sp
  22 int
  23 \fBTcl_PkgRequireProc\fR(\fIinterp, name, objc, objv, clientDataPtr\fR)
  24 .sp
  25 const char *
  26 \fBTcl_PkgPresent\fR(\fIinterp, name, version, exact\fR)
  27 .sp
  28 const char *
  29 \fBTcl_PkgPresentEx\fR(\fIinterp, name, version, exact, clientDataPtr\fR)
  30 .sp
  31 int
  32 \fBTcl_PkgProvide\fR(\fIinterp, name, version\fR)
  33 .sp
  34 int
  35 \fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
  36 .SH ARGUMENTS
  37 .AS void *clientDataPtr out
  38 .AP Tcl_Interp *interp in
  39 Interpreter where package is needed or available.
  40 .AP "const char" *name in
  41 Name of package.
  42 .AP "const char" *version in
  43 A version string consisting of one or more decimal numbers
  44 separated by dots.
  45 .AP int exact in
  46 Non-zero means that only the particular version specified by
  47 \fIversion\fR is acceptable.
  48 Zero means that newer versions than \fIversion\fR are also
  49 acceptable as long as they have the same major version number
  50 as \fIversion\fR.
  51 .AP "const void" *clientData in
  52 Arbitrary value to be associated with the package.
  53 .AP void *clientDataPtr out
  54 Pointer to place to store the value associated with the matching
  55 package. It is only changed if the pointer is not NULL and the
  56 function completed successfully. The storage can be any pointer
  57 type with the same size as a void pointer.
  58 .AP int objc in
  59 Number of requirements.
  60 .AP Tcl_Obj* objv[] in
  61 Array of requirements.
  62 .BE
  63 .SH DESCRIPTION
  64 .PP
  65 These procedures provide C-level interfaces to Tcl's package and
  66 version management facilities.
  67 .PP
  68 \fBTcl_PkgRequire\fR is equivalent to the \fBpackage require\fR
  69 command, \fBTcl_PkgPresent\fR is equivalent to the \fBpackage present\fR
  70 command, and \fBTcl_PkgProvide\fR is equivalent to the
  71 \fBpackage provide\fR command.
  72 .PP
  73 See the documentation for the Tcl commands for details on what these
  74 procedures do.
  75 .PP
  76 If \fBTcl_PkgPresent\fR or \fBTcl_PkgRequire\fR complete successfully
  77 they return a pointer to the version string for the version of the package
  78 that is provided in the interpreter (which may be different than
  79 \fIversion\fR); if an error occurs they return NULL and leave an error
  80 message in the interpreter's result.
  81 .PP
  82 \fBTcl_PkgProvide\fR returns \fBTCL_OK\fR if it completes successfully;
  83 if an error occurs it returns \fBTCL_ERROR\fR and leaves an error message
  84 in the interpreter's result.
  85 .PP
  86 \fBTcl_PkgProvideEx\fR, \fBTcl_PkgPresentEx\fR and \fBTcl_PkgRequireEx\fR
  87 allow the setting and retrieving of the client data associated with
  88 the package. In all other respects they are equivalent to the matching
  89 functions.
  90 .PP
  91 \fBTcl_PkgRequireProc\fR is the form of \fBpackage require\fR handling
  92 multiple requirements. The other forms are present for backward
  93 compatibility and translate their invocations to this form.
  94 .SH KEYWORDS
  95 package, present, provide, require, version
  96 .SH "SEE ALSO"
  97 package(n), Tcl_StaticPackage(3)