typo fix
[p5sagit/p5-mst-13.2.git] / Porting / Glossary
index e29381c..bde26b7 100644 (file)
@@ -37,16 +37,49 @@ aphostname (d_gethname.U):
        host name. The command is fully qualified by its absolute path, to make
        it safe when used by a process with super-user privileges.
 
-apiversion (patchlevel.U):
-       MakeMaker will install add-on modules in a directory with the
-       PERL_APIVERSION version number.  The value is set manually in
-       patchlevel.h.  Normally, for maintenance releases, this is
-       just something like 5.005 or 5.6 or 5.7.  That is, it does not
-       include the subversion number and does not change across
-       maintenance releases.  This is so that add-on extensions can
-       be shared across maintenance versions.  It is unclear how this
-       ought to work for developer versions.  If a release breaks
-       binary compatibility, this number should be increased.
+api_revision (patchlevel.U):
+       The three variables, api_revision, api_version, and
+       api_subversion, specify the version of the oldest perl binary
+       compatible with the present perl.  In a full version string
+       such as '5.6.1', api_revision is the '5'.
+       Prior to 5.5.640, the format was a floating point number,
+       like 5.00563.
+               perl.c:incpush() and lib/lib.pm will automatically search in
+       $sitelib/.. for older directories back to the limit specified
+       by these api_ variables.  This is only useful if you have a
+       perl library directory tree structured like the default one.
+       See INSTALL for how this works.  The versioned site_perl
+       directory was introduced in 5.005, so that is the lowest
+       possible value.  The version list appropriate for the current
+       system is determined in inc_version_list.U.
+               XXX To do:  Since compatibility can depend on compile time
+       options (such as bincompat, longlong, etc.) it should
+       (perhaps) be set by Configure, but currently it isn't.
+       Currently, we read a hard-wired value from patchlevel.h.
+       Perhaps what we ought to do is take the hard-wired value from
+       patchlevel.h but then modify it if the current Configure
+       options warrant.  patchlevel.h then would use an #ifdef guard.
+
+api_subversion (patchlevel.U):
+       The three variables, api_revision, api_version, and
+       api_subversion, specify the version of the oldest perl binary
+       compatible with the present perl.  In a full version string
+       such as '5.6.1', api_subversion is the '1'.  See api_revision for
+       full details.
+
+api_version (patchlevel.U):
+       The three variables, api_revision, api_version, and
+       api_subversion, specify the version of the oldest perl binary
+       compatible with the present perl.  In a full version string
+       such as '5.6.1', api_version is the '6'.  See api_revision for
+       full details.  As a special case, 5.5.0 is rendered in the
+       old-style as 5.005.  (In the 5.005_0x maintenance series,
+       this was the only versioned directory in $sitelib.)
+
+api_versionstring (patchlevel.U):
+       This variable combines api_revision, api_version, and
+       api_subversion in a format such as 5.6.1 (or 5_6_1) suitable
+       for use as a directory name.  This is filesystem dependent.
 
 ar (Loc.U):
        This variable is used internally by Configure to determine the
@@ -176,6 +209,10 @@ cf_time (cf_who.U):
        Holds the output of the "date" command when the configuration file was
        produced. This is used to tag both config.sh and config_h.SH.
 
+charsize (charsize.U):
+       This variable contains the value of the CHARSIZE symbol, which
+       indicates to the C program how many bytes there are in a character.
+
 chgrp (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.
@@ -231,7 +268,7 @@ cpp_stuff (cpp_stuff.U):
        used by the C preprocessor.
 
 cppccsymbols (Cppsym.U):
-       The variable contains the symbols defined by the C compiler when
+       The variable contains the symbols defined by the C compiler
        when it calls cpp.  The symbols defined by the cc alone or cpp
        alone are not in this list, see ccsymbols and cppsymbols.
        The list is a space-separated list of symbol=value tokens.
@@ -752,13 +789,9 @@ d_inetaton (d_inetaton.U):
        indicates to the C program that the inet_aton() function is available
        to parse IP address "dotted-quad" strings.
 
-d_int64t (i_inttypes.U):
+d_int64t (d_int64t.U):
        This symbol will be defined if the C compiler supports int64_t.
 
-d_iovec_s (i_sysuio.U):
-       This variable conditionally defines the HAS_STRUCT_IOVEC symbol,
-       which indicates that the struct iovec is supported.
-
 d_isascii (d_isascii.U):
        This variable conditionally defines the HAS_ISASCII constant,
        which indicates to the C program that isascii() is available.
@@ -782,10 +815,6 @@ d_link (d_link.U):
        This variable conditionally defines HAS_LINK if link() is
        available to create hard links.
 
-d_llseek (io64.U):
-       This variable conditionally defines the HAS_LLSEEK symbol, which
-       indicates to the C program that the llseek() routine is available.
-
 d_locconv (d_locconv.U):
        This variable conditionally defines HAS_LOCALECONV if localeconv() is
        available for numeric and monetary formatting conventions.
@@ -1052,6 +1081,10 @@ d_pwquota (i_pwd.U):
        This variable conditionally defines PWQUOTA, which indicates
        that struct passwd contains pw_quota.
 
+d_quad (quadtype.U):
+       This variable, if defined, tells that there's a 64-bit integer type,
+       quadtype.
+
 d_readdir (d_readdir.U):
        This variable conditionally defines HAS_READDIR if readdir() is
        available to read directory entries.
@@ -1365,15 +1398,27 @@ d_strtol (d_strtol.U):
        indicates to the C program that the strtol() routine is available
        to provide better numeric string conversion than atoi() and friends.
 
+d_strtold (d_strtold.U):
+       This variable conditionally defines the HAS_STRTOLD symbol, which
+       indicates to the C program that the strtold() routine is available.
+
+d_strtoll (d_strtoll.U):
+       This variable conditionally defines the HAS_STRTOLL symbol, which
+       indicates to the C program that the strtoll() routine is available.
+
 d_strtoul (d_strtoul.U):
        This variable conditionally defines the HAS_STRTOUL symbol, which
        indicates to the C program that the strtoul() routine is available
        to provide conversion of strings to unsigned long.
 
-d_strtoull (strtoull.U):
+d_strtoull (d_strtoull.U):
        This variable conditionally defines the HAS_STRTOULL symbol, which
        indicates to the C program that the strtoull() routine is available.
 
+d_strtouq (d_strtouq.U):
+       This variable conditionally defines the HAS_STRTOUQ symbol, which
+       indicates to the C program that the strtouq() routine is available.
+
 d_strxfrm (d_strxfrm.U):
        This variable conditionally defines HAS_STRXFRM if strxfrm() is
        available to transform strings.
@@ -1636,8 +1681,11 @@ flex (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.
 
+fpossize (fpossize.U):
+       This variable contains the size of a fpostype in bytes.
+
 fpostype (fpostype.U):
-       This variable defines Fpos_t to be something like fpost_t, long, 
+       This variable defines Fpos_t to be something like fpos_t, long, 
        uint, or whatever type is used to declare file positions in libc.
 
 freetype (mallocsrc.U):
@@ -1668,6 +1716,9 @@ gccversion (cc.U):
        indicate whether the compiler is version 1 or 2.  This is used in
        setting some of the default cflags.  It is set to '' if not gcc.
 
+gidformat (gidf.U):
+       This variable contains the format string used for printing a Gid_t.
+
 gidsign (gidsign.U):
        This variable contains the signedness of a gidtype.
        1 for unsigned, -1 for signed.
@@ -1694,6 +1745,8 @@ groupcat (nis.U):
        This variable contains a command that produces the text of the
        /etc/group file.  This is normally "cat /etc/group", but can be
        "ypcat group" when NIS is used.
+       On some systems, such as os390, there may be no equivalent
+       command, in which case this variable is unset.
 
 groupstype (groupstype.U):
        This variable defines Groups_t to be something like gid_t, int, 
@@ -1722,6 +1775,8 @@ hostcat (nis.U):
        This variable contains a command that produces the text of the
        /etc/hosts file.  This is normally "cat /etc/hosts", but can be
        "ypcat hosts" when NIS is used.
+       On some systems, such as os390, there may be no equivalent
+       command, in which case this variable is unset.
 
 huge (models.U):
        This variable contains a flag which will tell the C compiler and loader
@@ -1729,6 +1784,30 @@ huge (models.U):
        huge model is not supported, contains the flag to produce large
        model programs.  It is up to the Makefile to use this.
 
+i16size (perlxv.U):
+       This variable is the size of an I16 in bytes.
+
+i16type (perlxv.U):
+       This variable contains the C type used for Perl's I16.
+
+i32size (perlxv.U):
+       This variable is the size of an I32 in bytes.
+
+i32type (perlxv.U):
+       This variable contains the C type used for Perl's I32.
+
+i64size (perlxv.U):
+       This variable is the size of an I64 in bytes.
+
+i64type (perlxv.U):
+       This variable contains the C type used for Perl's I64.
+
+i8size (perlxv.U):
+       This variable is the size of an I8 in bytes.
+
+i8type (perlxv.U):
+       This variable contains the C type used for Perl's I8.
+
 i_arpainet (i_arpainet.U):
        This variable conditionally defines the I_ARPA_INET symbol,
        and indicates whether a C program should include <arpa/inet.h>.
@@ -2039,6 +2118,15 @@ ignore_versioned_solibs (libs.U):
        libraries (libfoo.so.x.y) are to be ignored (because they
        cannot be linked against).
 
+inc_version_list (inc_version_list.U):
+       This variable specifies the list of subdirectories in over
+       which perl.c:incpush() and lib/lib.pm will automatically
+       search when adding directories to @INC.  This is only useful
+       if you have a perl library directory tree structured like the
+       default one.  See INSTALL for how this works.  The versioned
+       site_perl directory was introduced in 5.005, so that is the
+       lowest possible value.
+
 incpath (usrinc.U):
        This variable must preceed the normal include path to get hte
        right one, as in "$incpath/usr/include" or "$incpath/usr/lib".
@@ -2144,6 +2232,16 @@ intsize (intsize.U):
        This variable contains the value of the INTSIZE symbol, which
        indicates to the C program how many bytes there are in an int.
 
+ivdformat (perlxvf.U):
+       This variable contains the format string used for printing
+       a Perl IV as a signed decimal integer. 
+
+ivsize (perlxv.U):
+       This variable is the size of an IV in bytes.
+
+ivtype (perlxv.U):
+       This variable contains the C type used for Perl's IV.
+
 known_extensions (Extensions.U):
        This variable holds a list of all XS extensions included in 
        the package.
@@ -2467,6 +2565,12 @@ nroff (Loc.U):
        full pathname (if any) of the nroff program.  After Configure runs,
        the value is reset to a plain "nroff" and is not useful.
 
+nvsize (perlxv.U):
+       This variable is the size of an NV in bytes.
+
+nvtype (perlxv.U):
+       This variable contains the C type used for Perl's NV.
+
 o_nonblock (nblock_io.U):
        This variable bears the symbol value to be used during open() or fcntl()
        to turn on non-blocking I/O for a file descriptor. If you wish to switch
@@ -2519,22 +2623,23 @@ passcat (nis.U):
        This variable contains a command that produces the text of the
        /etc/passwd file.  This is normally "cat /etc/passwd", but can be
        "ypcat passwd" when NIS is used.
+       On some systems, such as os390, there may be no equivalent
+       command, in which case this variable is unset.
 
 patchlevel (patchlevel.U):
        The patchlevel level of this package.
        The value of patchlevel comes from the patchlevel.h file.
+       In a version number such as 5.6.1, this is the "6".
+       In patchlevel.h, this is referred to as the "PERL_VERSION".
 
 path_sep (Unix.U):
        This is an old synonym for p_ in Head.U, the character
        used to separate elements in the command shell search PATH.
 
 perl (Loc.U):
-       This variable is defined but not used by Configure.
-       The value is a plain '' and is not useful.
-
-PERL_APIVERSION (Oldsyms.U):
-       This value is manually set in patchlevel.h and is used
-       to set the Configure apiversion variable.
+       This variable is used internally by Configure to determine the
+       full pathname (if any) of the perl program.  After Configure runs,
+       the value is reset to a plain "perl" and is not useful.
 
 PERL_REVISION (Oldsyms.U):
        In a Perl version number such as 5.6.2, this is the 5.
@@ -2578,21 +2683,6 @@ plibpth (libpth.U):
        Its value is prepend to libpth. This variable takes care of special
        machines, like the mips.  Usually, it should be empty.
 
-pm_apiversion (xs_apiversion.U):
-       This variable contains the version of the oldest perl
-       compatible with the present perl.  (That is, pure perl modules
-       written for $pm_apiversion will still work for the current
-       version).  perl.c:incpush() and lib/lib.pm will automatically
-       search in $sitelib for older directories across major versions
-       back to pm_apiversion.  This is only useful if you have a perl
-       library directory tree structured like the default one.  The
-       versioned site_perl library was introduced in 5.005, so that's
-       the default setting for this variable.  It's hard to imagine
-       it changing before Perl6.  It is included here for symmetry
-       with xs_apiveprsion -- the searching algorithms will
-       (presumably) be similar.
-       See the INSTALL file for how this works.
-
 pmake (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.
@@ -2630,6 +2720,14 @@ ptrsize (ptrsize.U):
        This variable contains the value of the PTRSIZE symbol, which
        indicates to the C program how many bytes there are in a pointer.
 
+quadkind (quadtype.U):
+       This variable, if defined, encodes the type of a quad:
+       1 = int, 2 = long, 3 = long long, 4 = int64_t.
+
+quadtype (quadtype.U):
+       This variable defines Quad_t to be something like long, int, 
+       long long, int64_t, or whatever type is used for 64-bit integers.
+
 randbits (randfunc.U):
        Indicates how many bits are produced by the function used to
        generate normalized random numbers.
@@ -3012,6 +3110,7 @@ submit (Loc.U):
 subversion (patchlevel.U):
        The subversion level of this package.
        The value of subversion comes from the patchlevel.h file.
+       In a version number such as 5.6.1, this is the "1".
        This is unique to perl.
 
 sysman (sysman.U):
@@ -3069,6 +3168,33 @@ troff (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.
 
+u16size (perlxv.U):
+       This variable is the size of an U16 in bytes.
+
+u16type (perlxv.U):
+       This variable contains the C type used for Perl's U16.
+
+u32size (perlxv.U):
+       This variable is the size of an U32 in bytes.
+
+u32type (perlxv.U):
+       This variable contains the C type used for Perl's U32.
+
+u64size (perlxv.U):
+       This variable is the size of an U64 in bytes.
+
+u64type (perlxv.U):
+       This variable contains the C type used for Perl's U64.
+
+u8size (perlxv.U):
+       This variable is the size of an U8 in bytes.
+
+u8type (perlxv.U):
+       This variable contains the C type used for Perl's U8.
+
+uidformat (uidf.U):
+       This variable contains the format string used for printing a Uid_t.
+
 uidsign (uidsign.U):
        This variable contains the signedness of a uidtype.
        1 for unsigned, -1 for signed.
@@ -3090,15 +3216,30 @@ uniq (Loc.U):
        full pathname (if any) of the uniq program.  After Configure runs,
        the value is reset to a plain "uniq" and is not useful.
 
+uquadtype (quadtype.U):
+       This variable defines Uquad_t to be something like unsigned long,
+       unsigned int, unsigned long long, uint64_t, or whatever type is
+       used for 64-bit integers.
+
+use5005threads (usethreads.U):
+       This variable conditionally defines the USE_5005THREADS symbol,
+       and indicates that Perl should be built to use the 5.005-based
+       threading implementation.
+
 use64bits (use64bits.U):
        This variable conditionally defines the USE_64_BITS symbol,
-       and indicates that explicit 64-bit interfaces should be used
+       and indicates that 64-bit integer types should be used
        when available.
 
 usedl (dlsrc.U):
-       This variable indicates if the the system supports dynamic
+       This variable indicates if the system supports dynamic
        loading of some sort.  See also dlsrc and dlobj.
 
+useithreads (usethreads.U):
+       This variable conditionally defines the USE_ITHREADS symbol,
+       and indicates that Perl should be built to use the interpreter-based
+       threading implementation.
+
 uselargefiles (uselfs.U):
        This variable conditionally defines the USE_LARGE_FILES symbol,
        and indicates that large file interfaces should be used when
@@ -3108,6 +3249,10 @@ uselongdouble (uselongdbl.U):
        This variable conditionally defines the USE_LONG_DOUBLE symbol,
        and indicates that long doubles should be used when available.
 
+uselonglong (uselonglong.U):
+       This variable conditionally defines the USE_LONG_LONG symbol,
+       and indicates that long longs should be used when available.
+
 usemorebits (usemorebits.U):
        This variable conditionally defines the USE_MORE_BITS symbol,
        and indicates that explicit 64-bit interfaces and long doubles
@@ -3183,6 +3328,24 @@ uuname (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.
 
+uvoformat (perlxvf.U):
+       This variable contains the format string used for printing
+       a Perl UV as an unsigned octal integer. 
+
+uvsize (perlxv.U):
+       This variable is the size of a UV in bytes.
+
+uvtype (perlxv.U):
+       This variable contains the C type used for Perl's UV.
+
+uvuformat (perlxvf.U):
+       This variable contains the format string used for printing
+       a Perl UV as an unsigned decimal integer. 
+
+uvxformat (perlxvf.U):
+       This variable contains the format string used for printing
+       a Perl UV as an unsigned hexadecimal integer. 
+
 vendorbin (vendorbin.U):
        This variable contains the eventual value of the VENDORBIN symbol.
        It may have a ~ on the front.
@@ -3219,11 +3382,11 @@ vendorprefixexp (vendorprefix.U):
        which the vendor will install add-on packages.  Derived from vendorprefix.
 
 version (patchlevel.U):
-       The full version number of this package.  This combines
-       baserev, patchlevel, and subversion to get the full
-       version number, including any possible subversions.  Care
-       is taken to use the C locale in order to get something
-       like 5.004 instead of 5,004.  This is unique to perl.
+       The full version number of this package, such as 5.6.1 (or 5_6_1).
+       This combines baserev, patchlevel, and subversion to get the
+       full version number, including any possible subversions.
+       This is suitable for use as a directory name, and hence is
+       filesystem dependent.
 
 vi (Loc.U):
        This variable is defined but not used by Configure.
@@ -3239,23 +3402,6 @@ xlibpth (libpth.U):
        libraries on this platform, for example CPU-specific libraries
        (on multi-CPU platforms) may be listed here.
 
-xs_apiversion (xs_apiversion.U):
-       This variable contains the version of the oldest perl binary
-       compatible with the present perl.  perl.c:incpush() and
-       lib/lib.pm will automatically search in $sitearch for older
-       directories across major versions back to xs_apiversion.
-       This is only useful if you have a perl library directory tree
-       structured like the default one.
-       See INSTALL for how this works.
-       The versioned site_perl directory was introduced in 5.005,
-       so that is the lowest possible value.
-       Since this can depend on compile time options (such as
-       bincompat) it is set by Configure.  Other non-default sources
-       of potential incompatibility, such as multiplicity, threads,
-       debugging, 64bits, sfio, etc., are not checked for currently,
-       though in principle we could go snooping around in old
-       Config.pm files.
-
 zcat (Loc.U):
        This variable is defined but not used by Configure.
        The value is a plain '' and is not useful.