summaryrefslogtreecommitdiffstats
path: root/doc/Encoding.3
diff options
context:
space:
mode:
Diffstat (limited to 'doc/Encoding.3')
-rw-r--r--doc/Encoding.396
1 files changed, 90 insertions, 6 deletions
diff --git a/doc/Encoding.3 b/doc/Encoding.3
index c365aaf..efdc8ca 100644
--- a/doc/Encoding.3
+++ b/doc/Encoding.3
@@ -4,7 +4,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: Encoding.3,v 1.20 2004/10/07 15:15:37 dkf Exp $
+'\" RCS: @(#) $Id: Encoding.3,v 1.21 2006/02/08 21:41:27 dgp Exp $
'\"
.so man.macros
.TH Tcl_GetEncoding 3 "8.1" Tcl "Tcl Library Procedures"
@@ -21,6 +21,11 @@ Tcl_Encoding
void
\fBTcl_FreeEncoding\fR(\fIencoding\fR)
.sp
+.VS 8.5
+int
+\fBTcl_GetEncodingFromObj\fR(\fIinterp, objPtr, encodingPtr\fR)
+.VE 8.5
+.sp
char *
\fBTcl_ExternalToUtfDString\fR(\fIencoding, src, srcLen, dstPtr\fR)
.sp
@@ -47,12 +52,25 @@ const char *
int
\fBTcl_SetSystemEncoding\fR(\fIinterp, name\fR)
.sp
+.VS 8.5
+const char *
+\fBTcl_GetEncodingNameFromEnvironment\fR(\fIbufPtr\fR)in
+.VE 8.5
+.sp
void
\fBTcl_GetEncodingNames\fR(\fIinterp\fR)
.sp
Tcl_Encoding
\fBTcl_CreateEncoding\fR(\fItypePtr\fR)
.sp
+.VS 8.5
+Tcl_Obj *
+\fBTcl_GetEncodingSearchPath\fR()
+.sp
+int
+\fBTcl_SetEncodingSearchPath\fR(\fIsearchPath\fR)
+.VE 8.5
+.sp
const char *
\fBTcl_GetDefaultEncodingDir\fR(\fIvoid\fR)
.sp
@@ -69,6 +87,14 @@ Name of encoding to load.
.AP Tcl_Encoding encoding in
The encoding to query, free, or use for converting text. If \fIencoding\fR is
NULL, the current system encoding is used.
+.AP Tcl_Obj *objPtr in
+.VS 8.5
+Name of encoding to get token for.
+.VE 8.5
+.AP Tcl_Encoding *encodingPtr out
+.VS 8.5
+Points to storage where encoding token is to be written.
+.VE 8.5
.AP "const char" *src in
For the \fBTcl_ExternalToUtf\fR functions, an array of bytes in the
specified encoding that are to be converted to UTF-8. For the
@@ -121,8 +147,16 @@ buffer as a result of the conversion. May be NULL.
.AP int *dstCharsPtr out
Filled with the number of characters that correspond to the number of bytes
stored in the output buffer. May be NULL.
+.AP Tcl_DString *bufPtr out
+.VS 8.5
+Storage for the prescribed system encoding name.
+.VE 8.5
.AP Tcl_EncodingType *typePtr in
Structure that defines a new type of encoding.
+.AP Tcl_Obj *searchPath in
+.VS 8.5
+List of filesystem directories in which to search for encoding data files.
+.VE 8.5
.AP "const char" *path in
A path to the location of the encoding file.
.BE
@@ -171,6 +205,25 @@ anywhere (i.e., it has been freed as many times as it has been gotten)
\fBTcl_FreeEncoding\fR will release all storage the encoding was using
and delete it from the database.
.PP
+.VS 8.5
+\fBTcl_GetEncodingFromObj\fR treats the string representation of \fIobjPtr\fR
+as an encoding name, and finds an encoding with that name, just as
+\fBTcl_GetEncoding\fR does. When an encoding is found, its \fBTcl_Encoding\fB
+token is written to the storage pointed to by \fIencodingPtr\fR, and the value
+\fBTCL_OK\fR is returned. In addition, a copy of the \fBTcl_Encoding\fR is
+kept as the internal representation of \fIobjPtr\fR. If no such encoding is
+found, the value \fBTCL_ERROR\fR is returned, and no writing to
+\fI*encodingPtr\fR takes place.
+.PP
+The reference count of the \fBTcl_Encoding\fR token may be incremented twice,
+once for the reference written to \fI*encodingPtr\fR and once for the
+reference stored in \fIobjPtr\fR, if a reference is not already in place
+there. The caller should call \fBTcl_FreeEncoding\fR on \fI*encodingPtr\fR
+when the token will no longer be used. The usual mechanisms for freeing the
+internal representation of a \fBTcl_Obj\fR will take care of calling
+\fBTcl_FreeEncoding\fR on that reference at the appropriate time.
+.VE 8.5
+.PP
\fBTcl_ExternalToUtfDString\fR converts a source buffer \fIsrc\fR from the
specified \fIencoding\fR into UTF-8. The converted bytes are stored in
\fIdstPtr\fR, which is then null-terminated. The caller should eventually
@@ -277,6 +330,15 @@ procedure increments the reference count of the new system encoding,
decrements the reference count of the old system encoding, and returns
\fBTCL_OK\fR.
.PP
+.VS 8.5
+\fBTcl_GetEncodingNameFromEnvironment\fR provides a means for the Tcl
+library to report the encoding name it believes to be the correct one
+to use as the system encoding, based on system calls and examination of
+the environment suitable for the platform. It accepts \fIbufPtr\fR,
+a pointer to an uninitialized or freed \fBTcl_DString\fR and writes
+the encoding name to it. The \fBTcl_DStringValue\fR is returned.
+.VE 8.5
+.PP
\fBTcl_GetEncodingNames\fR sets the \fIinterp\fR result to a list
consisting of the names of all the encodings that are currently defined
or can be dynamically loaded, searching the encoding path specified by
@@ -376,12 +438,34 @@ This \fIfreeProc\fR function is called when the encoding is deleted. The
\fIclientData\fR parameter is the same as the \fIclientData\fR field
specified to \fBTcl_CreateEncoding\fR when the encoding was created.
.PP
-
+.VS 8.5
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR
+are called to access and set the list of filesystem directories searched
+for encoding data files.
+.PP
+The value returned by \fBTcl_GetEncodingSearchPath\fR
+is the value stored by the last successful call to
+\fBTcl_SetEncodingSearchPath\fR. If no calls to
+\fBTcl_SetEncodingSearchPath\fR have occurred, Tcl will compute an initial
+value based on the environment. There is one encoding search path for the
+entire process, shared by all threads in the process.
+.PP
+\fBTcl_SetEncodingSearchPath\fR stores \fIsearchPath\fR and returns
+\fBTCL_OK\fR, unless \fIsearchPath\fR is not a valid Tcl list, which
+causes \fBTCL_ERROR\fR to be returned. The elements of \fIsearchPath\fR
+are not verified as existing readable filesystem directories. When
+searching for encoding data files takes place, and non-existent or
+non-readable filesystem directories on the \fIsearchPath\fR are silently
+ignored.
+.PP
\fBTcl_GetDefaultEncodingDir\fR and \fBTcl_SetDefaultEncodingDir\fR
-access and set the directory to use when locating the default encoding
-files. If this value is not NULL, the \fBTclpInitLibraryPath\fR routine
-appends the path to the head of the search path, and uses this path as
-the first place to look into when trying to locate the encoding file.
+are obsolete interfaces best replaced with calls to
+\fBTcl_GetEncodingSearchPath\fR and \fBTcl_SetEncodingSearchPath\fR.
+They are called to access and set the first element of the \fIsearchPath\fR
+list. Since Tcl searches \fIsearchPath\fR for encoding data files in
+list order, these routines establish the ``default'' directory in which
+to find encoding data files.
+.VE 8.5
.SH "ENCODING FILES"
Space would prohibit precompiling into Tcl every possible encoding