diff --git a/Doc/lib/libplatform.tex b/Doc/lib/libplatform.tex index 3c78eb53614..029c632e48c 100644 --- a/Doc/lib/libplatform.tex +++ b/Doc/lib/libplatform.tex @@ -8,9 +8,9 @@ \versionadded{2.3} -\begin{notice}[note] - Specific platforms listed alphabetically, with Linux included in the \UNIX - section. +\begin{notice} + Specific platforms listed alphabetically, with Linux included in the + \UNIX{} section. \end{notice} \subsection{Cross Platform} @@ -38,52 +38,46 @@ \begin{funcdesc}{machine}{} Returns the machine type, e.g. \code{'i386'}. - An empty string is returned if the value cannot be determined. \end{funcdesc} \begin{funcdesc}{node}{} - Returns the computer's network name (may not be fully qualified!) - + Returns the computer's network name (may not be fully qualified!). An empty string is returned if the value cannot be determined. \end{funcdesc} \begin{funcdesc}{platform}{aliased=0, terse=0} - Returns a single string identifying the underlying platform - with as much useful information as possible. - - The output is intended to be \emph{human readable} rather than - machine parseable. It may look different on different - platforms and this is intended. - - If \code{aliased} is true, the function will use aliases for - various platforms that report system names which differ from - their common names, e.g. SunOS will be reported as - Solaris. The \function{system_alias()} function is used to implement - this. - - Setting terse to true causes the function to return only the - absolute minimum information needed to identify the platform. + Returns a single string identifying the underlying platform + with as much useful information as possible. + + The output is intended to be \emph{human readable} rather than + machine parseable. It may look different on different platforms and + this is intended. + + If \var{aliased} is true, the function will use aliases for various + platforms that report system names which differ from their common + names, for example SunOS will be reported as Solaris. The + \function{system_alias()} function is used to implement this. + + Setting \var{terse} to true causes the function to return only the + absolute minimum information needed to identify the platform. \end{funcdesc} - \begin{funcdesc}{processor}{} - Returns the (real) processor name, e.g. 'amdk6' + Returns the (real) processor name, e.g. \code{'amdk6'}. - An empty string is returned if the value cannot be - determined. Note that many platforms do not provide this - information or simply return the same value as for \function{machine()}, - e.g. NetBSD does this. + An empty string is returned if the value cannot be determined. Note + that many platforms do not provide this information or simply return + the same value as for \function{machine()}. NetBSD does this. \end{funcdesc} \begin{funcdesc}{python_build}{} - Returns a tuple \code{(buildno, builddate)} stating the Python - build number and date as strings. + Returns a tuple \code{(\var{buildno}, \var{builddate})} stating the + Python build number and date as strings. \end{funcdesc} \begin{funcdesc}{python_compiler}{} - Returns a string identifying the compiler used for compiling - Python. + Returns a string identifying the compiler used for compiling Python. \end{funcdesc} \begin{funcdesc}{python_version}{} @@ -94,43 +88,41 @@ \end{funcdesc} \begin{funcdesc}{python_version_tuple}{} - Returns the Python version as tuple \code{(major, minor, patchlevel)} - of strings. + Returns the Python version as tuple \code{(\var{major}, \var{minor}, + \var{patchlevel})} of strings. Note that unlike the Python \code{sys.version}, the returned value - will always include the patchlevel (it defaults to 0). + will always include the patchlevel (it defaults to \code{'0'}). \end{funcdesc} \begin{funcdesc}{release}{} Returns the system's release, e.g. \code{'2.2.0'} or \code{'NT'} - An empty string is returned if the value cannot be determined. \end{funcdesc} \begin{funcdesc}{system}{} - Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, or \code{'Java'}. - + Returns the system/OS name, e.g. \code{'Linux'}, \code{'Windows'}, + or \code{'Java'}. An empty string is returned if the value cannot be determined. \end{funcdesc} \begin{funcdesc}{system_alias}{system, release, version} - Returns \code{(system, release, version)} aliased to common - marketing names used for some systems. - - It also does some reordering of the information in some cases - where it would otherwise cause confusion. + Returns \code{(\var{system}, \var{release}, \var{version})} aliased + to common marketing names used for some systems. It also does some + reordering of the information in some cases where it would otherwise + cause confusion. \end{funcdesc} \begin{funcdesc}{version}{} - Returns the system's release version, e.g. \code{'#3 on degas'}. - + Returns the system's release version, e.g. \code{'\#3 on degas'}. An empty string is returned if the value cannot be determined. \end{funcdesc} \begin{funcdesc}{uname}{} - Fairly portable uname interface. Returns a tuple - of strings \code{(system, node, release, version, machine, processor)} - identifying the underlying platform. + Fairly portable uname interface. Returns a tuple of strings + \code{(\var{system}, \var{node}, \var{release}, \var{version}, + \var{machine}, \var{processor})} identifying the underlying + platform. Note that unlike the \function{os.uname()} function this also returns possible processor information as additional tuple entry. @@ -138,86 +130,92 @@ Entries which cannot be determined are set to \code{''}. \end{funcdesc} + \subsection{Java Platform} -\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''), osinfo=('','','')} - Version interface for JPython. - - Returns a tuple \code{(release, vendor, vminfo, osinfo)} with vminfo being - a tuple \code{(vm_name, vm_release, vm_vendor)} and osinfo being a - tuple \code{(os_name, os_version, os_arch)}. - - Values which cannot be determined are set to the defaults - given as parameters (which all default to \code{''}). +\begin{funcdesc}{java_ver}{release='', vendor='', vminfo=('','',''), + osinfo=('','','')} + Version interface for JPython. + + Returns a tuple \code{(\var{release}, \var{vendor}, \var{vminfo}, + \var{osinfo})} with \var{vminfo} being a tuple \code{(\var{vm_name}, + \var{vm_release}, \var{vm_vendor})} and \var{osinfo} being a tuple + \code{(\var{os_name}, \var{os_version}, \var{os_arch})}. + Values which cannot be determined are set to the defaults + given as parameters (which all default to \code{''}). \end{funcdesc} + \subsection{Windows Platform} \begin{funcdesc}{win32_ver}{release='', version='', csd='', ptype=''} - Get additional version information from the Windows Registry - and return a tuple \code{(version, csd, ptype)} referring to version - number, CSD level and OS type (multi/single processor). - - As a hint: ptype returns \code{'Uniprocessor Free'} on single - processor NT machines and \code{'Multiprocessor Free'} on multi - processor machines. The \emph{'Free'} refers to the OS version being - free of debugging code. It could also state \emph{'Checked'} which - means the OS version uses debugging code, i.e. code that - checks arguments, ranges, etc. + Get additional version information from the Windows Registry + and return a tuple \code{(\var{version}, \var{csd}, \var{ptype})} + referring to version number, CSD level and OS type (multi/single + processor). -\begin{notice}[note] - This function only works if Mark Hammond's \module{win32all} - package is installed and (obviously) only runs on Win32 - compatible platforms. -\end{notice} + As a hint: \var{ptype} is \code{'Uniprocessor Free'} on single + processor NT machines and \code{'Multiprocessor Free'} on multi + processor machines. The \emph{'Free'} refers to the OS version being + free of debugging code. It could also state \emph{'Checked'} which + means the OS version uses debugging code, i.e. code that + checks arguments, ranges, etc. + \begin{notice}[note] + This function only works if Mark Hammond's \module{win32all} + package is installed and (obviously) only runs on Win32 + compatible platforms. + \end{notice} \end{funcdesc} \subsubsection{Win95/98 specific} \begin{funcdesc}{popen}{cmd, mode='r', bufsize=None} - Portable \function{popen()} interface. - Find a working popen implementation preferring \function{win32pipe.popen}. - On NT \function{win32pipe} should work; on Win9x - it hangs due to bugs in the MS C lib. - \seetext{MS KnowledgeBase article Q150956.} + Portable \function{popen()} interface. Find a working popen + implementation preferring \function{win32pipe.popen()}. On Windows + NT, \function{win32pipe.popen()} should work; on Windows 9x it hangs + due to bugs in the MS C library. + % This KnowledgeBase article appears to be missing... + %See also \ulink{MS KnowledgeBase article Q150956}{}. \end{funcdesc} -\subsection{Mac Platform} +\subsection{Mac OS Platform} \begin{funcdesc}{mac_ver}{release='', versioninfo=('','',''), machine=''} - Get MacOS version information and return it as tuple \code{(release, - versioninfo, machine)} with versioninfo being a tuple \code{(version, - dev_stage, non_release_version)}. - - Entries which cannot be determined are set to \code{''}. All tuple - entries are strings. + Get Mac OS version information and return it as tuple + \code{(\var{release}, \var{versioninfo}, \var{machine})} with + \var{versioninfo} being a tuple \code{(\var{version}, + \var{dev_stage}, \var{non_release_version})}. - Documentation for the underlying gestalt() API is available online - at \url{http://www.rgaros.nl/gestalt/} + Entries which cannot be determined are set to \code{''}. All tuple + entries are strings. + + Documentation for the underlying \cfunction{gestalt()} API is + available online at \url{http://www.rgaros.nl/gestalt/}. \end{funcdesc} + \subsection{\UNIX{} Platforms} -\begin{funcdesc}{dist}{distname='',version='',id='',supported_dists=('SuSE','debian','redhat','mandrake')} - Tries to determine the name of the OS distribution name - - Returns a tuple \code{(distname, version, id)} which defaults to the - args given as parameters. +\begin{funcdesc}{dist}{distname='', version='', id='', + supported_dists=('SuSE','debian','redhat','mandrake')} + Tries to determine the name of the OS distribution name + Returns a tuple \code{(\var{distname}, \var{version}, \var{id})} + which defaults to the args given as parameters. \end{funcdesc} -\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='', version='', chunksize=2048} - Tries to determine the libc version against which the - file executable (defaults to the Python interpreter) is linked. +\begin{funcdesc}{libc_ver}{executable=sys.executable, lib='', + version='', chunksize=2048} + Tries to determine the libc version against which the file + executable (defaults to the Python interpreter) is linked. Returns + a tuple of strings \code{(\var{lib}, \var{version})} which default + to the given parameters in case the lookup fails. - Returns a tuple of strings \code{(lib, version)} which default to the - given parameters in case the lookup fails. - - Note that the function has intimate knowledge of how different + Note that this function has intimate knowledge of how different libc versions add symbols to the executable is probably only - useable for executables compiled using \emph{gcc}. + useable for executables compiled using \program{gcc}. - The file is read and scanned in chunks of chunksize bytes. + The file is read and scanned in chunks of \var{chunksize} bytes. \end{funcdesc}