home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / !ibrowse / files / pylibi-4 < prev    next >
Encoding:
GNU Info File  |  1996-11-14  |  49.7 KB  |  1,339 lines
  1. This is Info file pylibi, produced by Makeinfo-1.55 from the input file
  2. lib.texi.
  3.  
  4. This file describes the built-in types, exceptions and functions and the
  5. standard modules that come with the Python system.  It assumes basic
  6. knowledge about the Python language.  For an informal introduction to
  7. the language, see the Python Tutorial.  The Python Reference Manual
  8. gives a more formal definition of the language.  (These manuals are not
  9. yet available in INFO or Texinfo format.)
  10.  
  11. Copyright 1991-1995 by Stichting Mathematisch Centrum, Amsterdam, The
  12. Netherlands.
  13.  
  14. All Rights Reserved
  15.  
  16. Permission to use, copy, modify, and distribute this software and its
  17. documentation for any purpose and without fee is hereby granted,
  18. provided that the above copyright notice appear in all copies and that
  19. both that copyright notice and this permission notice appear in
  20. supporting documentation, and that the names of Stichting Mathematisch
  21. Centrum or CWI or Corporation for National Research Initiatives or CNRI
  22. not be used in advertising or publicity pertaining to distribution of
  23. the software without specific, written prior permission.
  24.  
  25. While CWI is the initial source for this software, a modified version
  26. is made available by the Corporation for National Research Initiatives
  27. (CNRI) at the Internet address ftp://ftp.python.org.
  28.  
  29. STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
  30. REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
  31. MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
  32. CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
  33. DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
  34. PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS
  35. ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
  36. THIS SOFTWARE.
  37.  
  38. 
  39. File: pylibi,  Node: os,  Next: time,  Prev: Generic Operating System Services,  Up: Generic Operating System Services
  40.  
  41. Standard Module `os'
  42. ====================
  43.  
  44. This module provides a more portable way of using operating system (OS)
  45. dependent functionality than importing an OS dependent built-in module
  46. like `posix'.
  47.  
  48. When the optional built-in module `posix' is available, this module
  49. exports the same functions and data as `posix'; otherwise, it searches
  50. for an OS dependent built-in module like `mac' and exports the same
  51. functions and data as found there.  The design of all Python's built-in
  52. OS dependent modules is such that as long as the same functionality is
  53. available, it uses the same interface; e.g., the function
  54. `os.stat(FILE)' returns stat info about a FILE in a format compatible
  55. with the POSIX interface.
  56.  
  57. Extensions peculiar to a particular OS are also available through the
  58. `os' module, but using them is of course a threat to portability!
  59.  
  60. Note that after the first time `os' is imported, there is *no*
  61. performance penalty in using functions from `os' instead of directly
  62. from the OS dependent built-in module, so there should be *no* reason
  63. not to use `os'!
  64.  
  65. In addition to whatever the correct OS dependent module exports, the
  66. following variables and functions are always exported by `os':
  67.  
  68.  - data of module os: name
  69.      The name of the OS dependent module imported.  The following names
  70.      have currently been registered: `'posix'', `'nt'', `'dos'',
  71.      `'mac''.
  72.  
  73.  - data of module os: path
  74.      The corresponding OS dependent standard module for pathname
  75.      operations, e.g., `posixpath' or `macpath'.  Thus, (given the
  76.      proper imports), `os.path.split(FILE)' is equivalent to but more
  77.      portable than `posixpath.split(FILE)'.
  78.  
  79.  - data of module os: curdir
  80.      The constant string used by the OS to refer to the current
  81.      directory, e.g. `'.'' for POSIX or `':'' for the Mac.
  82.  
  83.  - data of module os: pardir
  84.      The constant string used by the OS to refer to the parent
  85.      directory, e.g. `'..'' for POSIX or `'::'' for the Mac.
  86.  
  87.  - data of module os: sep
  88.      The character used by the OS to separate pathname components, e.g.
  89.      `'/'' for POSIX or `':'' for the Mac.  Note that knowing this is
  90.      not sufficient to be able to parse or concatenate pathnames--better
  91.      use `os.path.split()' and `os.path.join()'--but it is occasionally
  92.      useful.
  93.  
  94.  - data of module os: pathsep
  95.      The character conventionally used by the OS to separate search
  96.      patch components (as in `$PATH'), e.g. `':'' for POSIX or `';''
  97.      for MS-DOS.
  98.  
  99.  - data of module os: defpath
  100.      The default search path used by `os.exec*p*()' if the environment
  101.      doesn't have a `'PATH'' key.
  102.  
  103.  - function of module os: execl (PATH, ARG0, ARG1, ...)
  104.      This is equivalent to `os.execv(PATH, (ARG0, ARG1, ...))'.
  105.  
  106.  - function of module os: execle (PATH, ARG0, ARG1, ..., ENV)
  107.      This is equivalent to `os.execve(PATH, (ARG0, ARG1, ...), ENV)'.
  108.  
  109.  - function of module os: execlp (PATH, ARG0, ARG1, ...)
  110.      This is equivalent to `os.execvp(PATH, (ARG0, ARG1, ...))'.
  111.  
  112.  - function of module os: execvp (PATH, ARGS)
  113.      This is like `os.execv(PATH, ARGS)' but duplicates the shell's
  114.      actions in searching for an executable file in a list of
  115.      directories.  The directory list is obtained from
  116.      `os.environ['PATH']'.
  117.  
  118.  - function of module os: execvpe (PATH, ARGS, ENV)
  119.      This is a cross between `os.execve()' and `os.execvp()'.  The
  120.      directory list is obtained from `ENV['PATH']'.
  121.  
  122. (The functions `os.execv()' and `execve()' are not documented here,
  123. since they are implemented by the OS dependent module.  If the OS
  124. dependent module doesn't define either of these, the functions that
  125. rely on it will raise an exception.  They are documented in the section
  126. on module `posix', together with all other functions that `os' imports
  127. from the OS dependent module.)
  128.  
  129. 
  130. File: pylibi,  Node: time,  Next: getopt,  Prev: os,  Up: Generic Operating System Services
  131.  
  132. Built-in Module `time'
  133. ======================
  134.  
  135. This module provides various time-related functions.  It is always
  136. available.
  137.  
  138. An explanation of some terminology and conventions is in order.
  139.  
  140.    * The "epoch" is the point where the time starts.  On January 1st of
  141.      that year, at 0 hours, the "time since the epoch" is zero.  For
  142.      UNIX, the epoch is 1970.  To find out what the epoch is, look at
  143.      `gmtime(0)'.
  144.  
  145.    * UTC is Coordinated Universal Time (formerly known as Greenwich Mean
  146.      Time).  The acronym UTC is not a mistake but a compromise between
  147.      English and French.
  148.  
  149.    * DST is Daylight Saving Time, an adjustment of the timezone by
  150.      (usually) one hour during part of the year.  DST rules are magic
  151.      (determined by local law) and can change from year to year.  The C
  152.      library has a table containing the local rules (often it is read
  153.      from a system file for flexibility) and is the only source of True
  154.      Wisdom in this respect.
  155.  
  156.    * The precision of the various real-time functions may be less than
  157.      suggested by the units in which their value or argument is
  158.      expressed.  E.g. on most UNIX systems, the clock "ticks" only 50
  159.      or 100 times a second, and on the Mac, times are only accurate to
  160.      whole seconds.
  161.  
  162.    * The time tuple as returned by `gmtime()' and `localtime()', or as
  163.      accpted by `mktime()' is a tuple of 9 integers: year (e.g. 1993),
  164.      month (1-12), day (1-31), hour (0-23), minute (0-59), second
  165.      (0-59), weekday (0-6, monday is 0), Julian day (1-366) and
  166.      daylight savings flag (-1, 0  or 1).  Note that unlike the C
  167.      structure, the month value is a range of 1-12, not 0-11.  A year
  168.      value of  100 will typically be silently converted to 1900  year
  169.      value.  A -1 argument as daylight savings flag, passed to
  170.      `mktime()' will usually result in the correct daylight savings
  171.      state to be filled in.
  172.  
  173. The module defines the following functions and data items:
  174.  
  175.  - data of module time: altzone
  176.      The offset of the local DST timezone, in seconds west of the 0th
  177.      meridian, if one is defined.  Negative if the local DST timezone is
  178.      east of the 0th meridian (as in Western Europe, including the UK).
  179.      Only use this if `daylight' is nonzero.
  180.  
  181.  - function of module time: asctime (TUPLE)
  182.      Convert a tuple representing a time as returned by `gmtime()' or
  183.      `localtime()' to a 24-character string of the following form:
  184.      `'Sun Jun 20 23:21:05 1993''.  Note: unlike the C function of the
  185.      same name, there is no trailing newline.
  186.  
  187.  - function of module time: clock ()
  188.      Return the current CPU time as a floating point number expressed in
  189.      seconds.  The precision, and in fact the very definiton of the
  190.      meaning of "CPU time", depends on that of the C function of the
  191.      same name.
  192.  
  193.  - function of module time: ctime (SECS)
  194.      Convert a time expressed in seconds since the epoch to a string
  195.      representing local time.  `ctime(t)' is equivalent to
  196.      `asctime(localtime(t))'.
  197.  
  198.  - data of module time: daylight
  199.      Nonzero if a DST timezone is defined.
  200.  
  201.  - function of module time: gmtime (SECS)
  202.      Convert a time expressed in seconds since the epoch to a time tuple
  203.      in UTC in which the dst flag is always zero.  Fractions of a
  204.      second are ignored.
  205.  
  206.  - function of module time: localtime (SECS)
  207.      Like `gmtime' but converts to local time.  The dst flag is set to
  208.      1 when DST applies to the given time.
  209.  
  210.  - function of module time: mktime (TUPLE)
  211.      This is the inverse function of `localtime'.  Its argument is the
  212.      full 9-tuple (since the dst flag is needed -- pass -1 as the dst
  213.      flag if it is unknown) which expresses the time in local time, not
  214.      UTC.  It returns a floating point number, for compatibility with
  215.      `time.time()'.  If the input value can't be represented as a valid
  216.      time, OverflowError is raised.
  217.  
  218.  - function of module time: sleep (SECS)
  219.      Suspend execution for the given number of seconds.  The argument
  220.      may be a floating point number to indicate a more precise sleep
  221.      time.
  222.  
  223.  - function of module time: strftime (FORMAT, TUPLE)
  224.      Convert a tuple representing a time as returned by `gmtime()' or
  225.      `localtime()' to a string as specified by the format argument.
  226.  
  227.      The following directives, shown without the optional field width
  228.      and precision specification, are replaced by the indicated
  229.      characters:
  230.  
  231.      lp25em %a  &      Locale's abbreviated weekday name.
  232.      %A  &      Locale's full weekday name.
  233.      %b  &      Locale's abbreviated month name.
  234.      %B  &      Locale's full month name.
  235.      %c  &      Locale's appropriate date and time representation.
  236.      %d  &      Day of the month as a decimal number [01,31].
  237.      %E  &      Locale's combined Emperor/Era name and year.
  238.      %H  &      Hour (24-hour clock) as a decimal number [00,23].
  239.      %I  &      Hour (12-hour clock) as a decimal number [01,12].
  240.      %j  &      Day of the year as a decimal number [001,366].
  241.      %m  &      Month as a decimal number [01,12].
  242.      %M  &      Minute as a decimal number [00,59].
  243.      %n  &      New-line character.
  244.      %N  &      Locale's Emperor/Era name.
  245.      %o  &      Locale's Emperor/Era year.
  246.      %p  &      Locale's equivalent of either AM or PM.
  247.      %S  &      Second as a decimal number [00,61].
  248.      %t  &      Tab character.
  249.      %U  &      Week number of the year (Sunday as the first day of the
  250.      week) as a decimal number [00,53].  All days in a new year
  251.      preceding the first Sunday are considered to be in week 0.
  252.      %w  &      Weekday as a decimal number [0(Sunday),6].
  253.      %W  &      Week number of the year (Monday as the first day of the
  254.      week) as a decimal number [00,53].  All days in a new year
  255.      preceding the first Sunday are considered to be in week 0.
  256.      %x  &      Locale's appropriate date representation.
  257.      %X  &      Locale's appropriate time representation.
  258.      %y  &      Year without century as a decimal number [00,99].
  259.      %Y  &      Year with century as a decimal number.
  260.      %Z  &      Time zone name (or by no characters if no time zone
  261.      exists).
  262.      %%  &     %
  263.      An optional field width and precision specification can immediately
  264.      follow the initial % of a directive in the following order:
  265.      lp25em [-|0]w  &       the decimal digit string w specifies a
  266.      minimum field width in which the result of the conversion is right-
  267.      or left-justified.  It is right-justified (with space padding) by
  268.      default.  If the optional flag `-' is specified, it is
  269.      left-justified with space padding on the right.  If the optional
  270.      flag `0' is specified, it is right-justified and padded with zeros
  271.      on the left.
  272.      .p      &       the decimal digit string p specifies the minimum
  273.      number of digits to appear for the d, H, I, j, m, M, o, S, U, w,
  274.      W, y and Y directives, and the maximum number of characters to be
  275.      used from the a, A, b, B, c, D, E, F, h, n, N, p, r, t, T, x, X,
  276.      z, Z, and the first case, if a directive supplies fewer digits
  277.      than specified by the precision, it will be expanded with leading
  278.      zeros.  In the second case, if a directive supplies more
  279.      characters than specified by the precision, excess characters will
  280.      truncated on the right.
  281.  
  282.      If no field width or precision is specified for a d, H, I, m, M,
  283.      S, U, W, y, or j directive, a default of .2 is used for all but j
  284.      for which .3 is used.
  285.  
  286.  
  287.  - function of module time: time ()
  288.      Return the time as a floating point number expressed in seconds
  289.      since the epoch, in UTC.  Note that even though the time is always
  290.      returned as a floating point number, not all systems provide time
  291.      with a better precision than 1 second.
  292.  
  293.  - data of module time: timezone
  294.      The offset of the local (non-DST) timezone, in seconds west of the
  295.      0th meridian (i.e. negative in most of Western Europe, positive in
  296.      the US, zero in the UK).
  297.  
  298.  - data of module time: tzname
  299.      A tuple of two strings: the first is the name of the local non-DST
  300.      timezone, the second is the name of the local DST timezone.  If no
  301.      DST timezone is defined, the second string should not be used.
  302.  
  303. 
  304. File: pylibi,  Node: getopt,  Next: tempfile,  Prev: time,  Up: Generic Operating System Services
  305.  
  306. Standard Module `getopt'
  307. ========================
  308.  
  309. This module helps scripts to parse the command line arguments in
  310. `sys.argv'.  It supports the same conventions as the UNIX `getopt()'
  311. function (including the special meanings of arguments of the form `-'
  312. and `--').  Long options similar to those supported by GNU software may
  313. be used as well via an optional third argument.  It defines the function
  314. `getopt.getopt(args, options [, long_options])' and the exception
  315. `getopt.error'.
  316.  
  317. The first argument to `getopt()' is the argument list passed to the
  318. script with its first element chopped off (i.e., `sys.argv[1:]').  The
  319. second argument is the string of option letters that the script wants
  320. to recognize, with options that require an argument followed by a colon
  321. (i.e., the same format that UNIX `getopt()' uses).  The third option,
  322. if specified, is a list of strings with the names of the long options
  323. which should be supported.  The leading `'--'' characters should not be
  324. included in the option name.  Options which require an argument should
  325. be followed by an equal sign (`'='').  The return value consists of two
  326. elements: the first is a list of option-and-value pairs; the second is
  327. the list of program arguments left after the option list was stripped
  328. (this is a trailing slice of the first argument).  Each
  329. option-and-value pair returned has the option as its first element,
  330. prefixed with a hyphen (e.g., `'-x''), and the option argument as its
  331. second element, or an empty string if the option has no argument.  The
  332. options occur in the list in the same order in which they were found,
  333. thus allowing multiple occurrences.  Long and short options may be
  334. mixed.
  335.  
  336. An example using only UNIX style options:
  337.  
  338.      >>> import getopt, string
  339.      >>> args = string.split('-a -b -cfoo -d bar a1 a2')
  340.      >>> args
  341.      ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
  342.      >>> optlist, args = getopt.getopt(args, 'abc:d:')
  343.      >>> optlist
  344.      [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
  345.      >>> args
  346.      ['a1', 'a2']
  347.      >>>
  348. Using long option names is equally easy:
  349.  
  350.      >>> s = '--condition=foo --testing --output-file abc.def -x a1 a2'
  351.      >>> args = string.split(s)
  352.      >>> args
  353.      ['--condition=foo', '--testing', '--output-file', 'abc.def', '-x', 'a1', 'a2']
  354.      >>> optlist, args = getopt.getopt(args, 'x', [
  355.      ...     'condition=', 'output-file=', 'testing'])
  356.      >>> optlist
  357.      [('--condition', 'foo'), ('--testing', ''), ('--output-file', 'abc.def'), ('-x', '')]
  358.      >>> args
  359.      ['a1', 'a2']
  360.      >>>
  361. The exception `getopt.error = 'getopt.error'' is raised when an
  362. unrecognized option is found in the argument list or when an option
  363. requiring an argument is given none.  The argument to the exception is
  364. a string indicating the cause of the error.  For long options, an
  365. argument given to an option which does not require one will also cause
  366. this exception to be raised.
  367.  
  368. 
  369. File: pylibi,  Node: tempfile,  Next: errno,  Prev: getopt,  Up: Generic Operating System Services
  370.  
  371. Standard Module `tempfile'
  372. ==========================
  373.  
  374. This module generates temporary file names.  It is not UNIX specific,
  375. but it may require some help on non-UNIX systems.
  376.  
  377. Note: the modules does not create temporary files, nor does it
  378. automatically remove them when the current process exits or dies.
  379.  
  380. The module defines a single user-callable function:
  381.  
  382.  - function of module tempfile: mktemp ()
  383.      Return a unique temporary filename.  This is an absolute pathname
  384.      of a file that does not exist at the time the call is made.  No
  385.      two calls will return the same filename.
  386.  
  387. The module uses two global variables that tell it how to construct a
  388. temporary name.  The caller may assign values to them; by default they
  389. are initialized at the first call to `mktemp()'.
  390.  
  391.  - data of module tempfile: tempdir
  392.      When set to a value other than `None', this variable defines the
  393.      directory in which filenames returned by `mktemp()' reside.  The
  394.      default is taken from the environment variable `TMPDIR'; if this
  395.      is not set, either `/usr/tmp' is used (on UNIX), or the current
  396.      working directory (all other systems).  No check is made to see
  397.      whether its value is valid.
  398.  
  399.  - data of module tempfile: template
  400.      When set to a value other than `None', this variable defines the
  401.      prefix of the final component of the filenames returned by
  402.      `mktemp()'.  A string of decimal digits is added to generate
  403.      unique filenames.  The default is either "`@PID.'" where PID is
  404.      the current process ID (on UNIX), or "`tmp'" (all other systems).
  405.  
  406. Warning: if a UNIX process uses `mktemp()', then calls `fork()' and
  407. both parent and child continue to use `mktemp()', the processes will
  408. generate conflicting temporary names.  To resolve this, the child
  409. process should assign `None' to `template', to force recomputing the
  410. default on the next call to `mktemp()'.
  411.  
  412. 
  413. File: pylibi,  Node: errno,  Prev: tempfile,  Up: Generic Operating System Services
  414.  
  415. Standard Module `errno'
  416. =======================
  417.  
  418. This module makes available standard errno system symbols.  The value
  419. of each symbol is the corresponding integer value.  The names and
  420. descriptions are borrowed from linux/include/errno.h, which should be
  421. pretty all-inclusive.  Of the following list, symbols that are not used
  422. on the current platform are not defined by the module.
  423.  
  424. Symbols available can include:
  425.  
  426.  - data of module errno: EPERM
  427.      Operation not permitted
  428.  
  429.  - data of module errno: ENOENT
  430.      No such file or directory
  431.  
  432.  - data of module errno: ESRCH
  433.      No such process
  434.  
  435.  - data of module errno: EINTR
  436.      Interrupted system call
  437.  
  438.  - data of module errno: EIO
  439.      I/O error
  440.  
  441.  - data of module errno: ENXIO
  442.      No such device or address
  443.  
  444.  - data of module errno: E2BIG
  445.      Arg list too long
  446.  
  447.  - data of module errno: ENOEXEC
  448.      Exec format error
  449.  
  450.  - data of module errno: EBADF
  451.      Bad file number
  452.  
  453.  - data of module errno: ECHILD
  454.      No child processes
  455.  
  456.  - data of module errno: EAGAIN
  457.      Try again
  458.  
  459.  - data of module errno: ENOMEM
  460.      Out of memory
  461.  
  462.  - data of module errno: EACCES
  463.      Permission denied
  464.  
  465.  - data of module errno: EFAULT
  466.      Bad address
  467.  
  468.  - data of module errno: ENOTBLK
  469.      Block device required
  470.  
  471.  - data of module errno: EBUSY
  472.      Device or resource busy
  473.  
  474.  - data of module errno: EEXIST
  475.      File exists
  476.  
  477.  - data of module errno: EXDEV
  478.      Cross-device link
  479.  
  480.  - data of module errno: ENODEV
  481.      No such device
  482.  
  483.  - data of module errno: ENOTDIR
  484.      Not a directory
  485.  
  486.  - data of module errno: EISDIR
  487.      Is a directory
  488.  
  489.  - data of module errno: EINVAL
  490.      Invalid argument
  491.  
  492.  - data of module errno: ENFILE
  493.      File table overflow
  494.  
  495.  - data of module errno: EMFILE
  496.      Too many open files
  497.  
  498.  - data of module errno: ENOTTY
  499.      Not a typewriter
  500.  
  501.  - data of module errno: ETXTBSY
  502.      Text file busy
  503.  
  504.  - data of module errno: EFBIG
  505.      File too large
  506.  
  507.  - data of module errno: ENOSPC
  508.      No space left on device
  509.  
  510.  - data of module errno: ESPIPE
  511.      Illegal seek
  512.  
  513.  - data of module errno: EROFS
  514.      Read-only file system
  515.  
  516.  - data of module errno: EMLINK
  517.      Too many links
  518.  
  519.  - data of module errno: EPIPE
  520.      Broken pipe
  521.  
  522.  - data of module errno: EDOM
  523.      Math argument out of domain of func
  524.  
  525.  - data of module errno: ERANGE
  526.      Math result not representable
  527.  
  528.  - data of module errno: EDEADLK
  529.      Resource deadlock would occur
  530.  
  531.  - data of module errno: ENAMETOOLONG
  532.      File name too long
  533.  
  534.  - data of module errno: ENOLCK
  535.      No record locks available
  536.  
  537.  - data of module errno: ENOSYS
  538.      Function not implemented
  539.  
  540.  - data of module errno: ENOTEMPTY
  541.      Directory not empty
  542.  
  543.  - data of module errno: ELOOP
  544.      Too many symbolic links encountered
  545.  
  546.  - data of module errno: EWOULDBLOCK
  547.      Operation would block
  548.  
  549.  - data of module errno: ENOMSG
  550.      No message of desired type
  551.  
  552.  - data of module errno: EIDRM
  553.      Identifier removed
  554.  
  555.  - data of module errno: ECHRNG
  556.      Channel number out of range
  557.  
  558.  - data of module errno: EL2NSYNC
  559.      Level 2 not synchronized
  560.  
  561.  - data of module errno: EL3HLT
  562.      Level 3 halted
  563.  
  564.  - data of module errno: EL3RST
  565.      Level 3 reset
  566.  
  567.  - data of module errno: ELNRNG
  568.      Link number out of range
  569.  
  570.  - data of module errno: EUNATCH
  571.      Protocol driver not attached
  572.  
  573.  - data of module errno: ENOCSI
  574.      No CSI structure available
  575.  
  576.  - data of module errno: EL2HLT
  577.      Level 2 halted
  578.  
  579.  - data of module errno: EBADE
  580.      Invalid exchange
  581.  
  582.  - data of module errno: EBADR
  583.      Invalid request descriptor
  584.  
  585.  - data of module errno: EXFULL
  586.      Exchange full
  587.  
  588.  - data of module errno: ENOANO
  589.      No anode
  590.  
  591.  - data of module errno: EBADRQC
  592.      Invalid request code
  593.  
  594.  - data of module errno: EBADSLT
  595.      Invalid slot
  596.  
  597.  - data of module errno: EDEADLOCK
  598.      File locking deadlock error
  599.  
  600.  - data of module errno: EBFONT
  601.      Bad font file format
  602.  
  603.  - data of module errno: ENOSTR
  604.      Device not a stream
  605.  
  606.  - data of module errno: ENODATA
  607.      No data available
  608.  
  609.  - data of module errno: ETIME
  610.      Timer expired
  611.  
  612.  - data of module errno: ENOSR
  613.      Out of streams resources
  614.  
  615.  - data of module errno: ENONET
  616.      Machine is not on the network
  617.  
  618.  - data of module errno: ENOPKG
  619.      Package not installed
  620.  
  621.  - data of module errno: EREMOTE
  622.      Object is remote
  623.  
  624.  - data of module errno: ENOLINK
  625.      Link has been severed
  626.  
  627.  - data of module errno: EADV
  628.      Advertise error
  629.  
  630.  - data of module errno: ESRMNT
  631.      Srmount error
  632.  
  633.  - data of module errno: ECOMM
  634.      Communication error on send
  635.  
  636.  - data of module errno: EPROTO
  637.      Protocol error
  638.  
  639.  - data of module errno: EMULTIHOP
  640.      Multihop attempted
  641.  
  642.  - data of module errno: EDOTDOT
  643.      RFS specific error
  644.  
  645.  - data of module errno: EBADMSG
  646.      Not a data message
  647.  
  648.  - data of module errno: EOVERFLOW
  649.      Value too large for defined data type
  650.  
  651.  - data of module errno: ENOTUNIQ
  652.      Name not unique on network
  653.  
  654.  - data of module errno: EBADFD
  655.      File descriptor in bad state
  656.  
  657.  - data of module errno: EREMCHG
  658.      Remote address changed
  659.  
  660.  - data of module errno: ELIBACC
  661.      Can not access a needed shared library
  662.  
  663.  - data of module errno: ELIBBAD
  664.      Accessing a corrupted shared library
  665.  
  666.  - data of module errno: ELIBSCN
  667.      .lib section in a.out corrupted
  668.  
  669.  - data of module errno: ELIBMAX
  670.      Attempting to link in too many shared libraries
  671.  
  672.  - data of module errno: ELIBEXEC
  673.      Cannot exec a shared library directly
  674.  
  675.  - data of module errno: EILSEQ
  676.      Illegal byte sequence
  677.  
  678.  - data of module errno: ERESTART
  679.      Interrupted system call should be restarted
  680.  
  681.  - data of module errno: ESTRPIPE
  682.      Streams pipe error
  683.  
  684.  - data of module errno: EUSERS
  685.      Too many users
  686.  
  687.  - data of module errno: ENOTSOCK
  688.      Socket operation on non-socket
  689.  
  690.  - data of module errno: EDESTADDRREQ
  691.      Destination address required
  692.  
  693.  - data of module errno: EMSGSIZE
  694.      Message too long
  695.  
  696.  - data of module errno: EPROTOTYPE
  697.      Protocol wrong type for socket
  698.  
  699.  - data of module errno: ENOPROTOOPT
  700.      Protocol not available
  701.  
  702.  - data of module errno: EPROTONOSUPPORT
  703.      Protocol not supported
  704.  
  705.  - data of module errno: ESOCKTNOSUPPORT
  706.      Socket type not supported
  707.  
  708.  - data of module errno: EOPNOTSUPP
  709.      Operation not supported on transport endpoint
  710.  
  711.  - data of module errno: EPFNOSUPPORT
  712.      Protocol family not supported
  713.  
  714.  - data of module errno: EAFNOSUPPORT
  715.      Address family not supported by protocol
  716.  
  717.  - data of module errno: EADDRINUSE
  718.      Address already in use
  719.  
  720.  - data of module errno: EADDRNOTAVAIL
  721.      Cannot assign requested address
  722.  
  723.  - data of module errno: ENETDOWN
  724.      Network is down
  725.  
  726.  - data of module errno: ENETUNREACH
  727.      Network is unreachable
  728.  
  729.  - data of module errno: ENETRESET
  730.      Network dropped connection because of reset
  731.  
  732.  - data of module errno: ECONNABORTED
  733.      Software caused connection abort
  734.  
  735.  - data of module errno: ECONNRESET
  736.      Connection reset by peer
  737.  
  738.  - data of module errno: ENOBUFS
  739.      No buffer space available
  740.  
  741.  - data of module errno: EISCONN
  742.      Transport endpoint is already connected
  743.  
  744.  - data of module errno: ENOTCONN
  745.      Transport endpoint is not connected
  746.  
  747.  - data of module errno: ESHUTDOWN
  748.      Cannot send after transport endpoint shutdown
  749.  
  750.  - data of module errno: ETOOMANYREFS
  751.      Too many references: cannot splice
  752.  
  753.  - data of module errno: ETIMEDOUT
  754.      Connection timed out
  755.  
  756.  - data of module errno: ECONNREFUSED
  757.      Connection refused
  758.  
  759.  - data of module errno: EHOSTDOWN
  760.      Host is down
  761.  
  762.  - data of module errno: EHOSTUNREACH
  763.      No route to host
  764.  
  765.  - data of module errno: EALREADY
  766.      Operation already in progress
  767.  
  768.  - data of module errno: EINPROGRESS
  769.      Operation now in progress
  770.  
  771.  - data of module errno: ESTALE
  772.      Stale NFS file handle
  773.  
  774.  - data of module errno: EUCLEAN
  775.      Structure needs cleaning
  776.  
  777.  - data of module errno: ENOTNAM
  778.      Not a XENIX named type file
  779.  
  780.  - data of module errno: ENAVAIL
  781.      No XENIX semaphores available
  782.  
  783.  - data of module errno: EISNAM
  784.      Is a named type file
  785.  
  786.  - data of module errno: EREMOTEIO
  787.      Remote I/O error
  788.  
  789.  - data of module errno: EDQUOT
  790.      Quota exceeded
  791.  
  792. 
  793. File: pylibi,  Node: Optional Operating System Services,  Next: The Python Debugger,  Prev: Generic Operating System Services,  Up: Top
  794.  
  795. Optional Operating System Services
  796. **********************************
  797.  
  798. The modules described in this chapter provide interfaces to operating
  799. system features that are available on selected operating systems only.
  800. The interfaces are generally modelled after the UNIX or C interfaces
  801. but they are available on some other systems as well (e.g. Windows or
  802. NT).  Here's an overview:
  803.  
  804. signal
  805.      -- Set handlers for asynchronous events.
  806.  
  807. socket
  808.      -- Low-level networking interface.
  809.  
  810. select
  811.      -- Wait for I/O completion on multiple streams.
  812.  
  813. thread
  814.      -- Create multiple threads of control within one namespace.
  815.  
  816. * Menu:
  817.  
  818. * signal::
  819. * socket::
  820.  
  821. 
  822. File: pylibi,  Node: signal,  Next: socket,  Prev: Optional Operating System Services,  Up: Optional Operating System Services
  823.  
  824. Built-in Module `signal'
  825. ========================
  826.  
  827. This module provides mechanisms to use signal handlers in Python.  Some
  828. general rules for working with signals handlers:
  829.  
  830.    * A handler for a particular signal, once set, remains installed
  831.      until it is explicitly reset (i.e. Python emulates the BSD style
  832.      interface regardless of the underlying implementation), with the
  833.      exception of the handler for `SIGCHLD', which follows the
  834.      underlying implementation.
  835.  
  836.    * There is no way to "block" signals temporarily from critical
  837.      sections (since this is not supported by all UNIX flavors).
  838.  
  839.    * Although Python signal handlers are called asynchronously as far as
  840.      the Python user is concerned, they can only occur between the
  841.      "atomic" instructions of the Python interpreter.  This means that
  842.      signals arriving during long calculations implemented purely in C
  843.      (e.g. regular expression matches on large bodies of text) may be
  844.      delayed for an arbitrary amount of time.
  845.  
  846.    * When a signal arrives during an I/O operation, it is possible that
  847.      the I/O operation raises an exception after the signal handler
  848.      returns.  This is dependent on the underlying UNIX system's
  849.      semantics regarding interrupted system calls.
  850.  
  851.    * Because the C signal handler always returns, it makes little sense
  852.      to catch synchronous errors like `SIGFPE' or `SIGSEGV'.
  853.  
  854.    * Python installs a small number of signal handlers by default:
  855.      `SIGPIPE' is ignored (so write errors on pipes and sockets can be
  856.      reported as ordinary Python exceptions), `SIGINT' is translated
  857.      into a `KeyboardInterrupt' exception, and `SIGTERM' is caught so
  858.      that necessary cleanup (especially `sys.exitfunc') can be
  859.      performed before actually terminating.  All of these can be
  860.      overridden.
  861.  
  862.    * Some care must be taken if both signals and threads are used in the
  863.      same program.  The fundamental thing to remember in using signals
  864.      and threads simultaneously is: always perform `signal()' operations
  865.      in the main thread of execution.  Any thread can perform an
  866.      `alarm()', `getsignal()', or `pause()'; only the main thread can
  867.      set a new signal handler, and the main thread will be the only one
  868.      to receive signals (this is enforced by the Python signal module,
  869.      even if the underlying thread implementation supports sending
  870.      signals to individual threads).  This means that signals can't be
  871.      used as a means of interthread communication.  Use locks instead.
  872.  
  873. The variables defined in the signal module are:
  874.  
  875.  - data of module signal: SIG_DFL
  876.      This is one of two standard signal handling options; it will simply
  877.      perform the default function for the signal.  For example, on most
  878.      systems the default action for SIGQUIT is to dump core and exit,
  879.      while the default action for SIGCLD is to simply ignore it.
  880.  
  881.  - data of module signal: SIG_IGN
  882.      This is another standard signal handler, which will simply ignore
  883.      the given signal.
  884.  
  885.  - data of module signal: SIG*
  886.      All the signal numbers are defined symbolically.  For example, the
  887.      hangup signal is defined as `signal.SIGHUP'; the variable names
  888.      are identical to the names used in C programs, as found in
  889.      `signal.h'.  The UNIX man page for `signal' lists the existing
  890.      signals (on some systems this is `signal(2)', on others the list
  891.      is in `signal(7)').  Note that not all systems define the same set
  892.      of signal names; only those names defined by the system are
  893.      defined by this module.
  894.  
  895.  - data of module signal: NSIG
  896.      One more than the number of the highest signal number.
  897.  
  898. The signal module defines the following functions:
  899.  
  900.  - function of module signal: alarm (TIME)
  901.      If TIME is non-zero, this function requests that a `SIGALRM'
  902.      signal be sent to the process in TIME seconds.  Any previously
  903.      scheduled alarm is canceled (i.e. only one alarm can be scheduled
  904.      at any time).  The returned value is then the number of seconds
  905.      before any previously set alarm was to have been delivered.  If
  906.      TIME is zero, no alarm id scheduled, and any scheduled alarm is
  907.      canceled.  The return value is the number of seconds remaining
  908.      before a previously scheduled alarm.  If the return value is zero,
  909.      no alarm is currently scheduled.  (See the UNIX man page
  910.      `alarm(2)'.)
  911.  
  912.  - function of module signal: getsignal (SIGNALNUM)
  913.      Return the current signal handler for the signal SIGNALNUM.  The
  914.      returned value may be a callable Python object, or one of the
  915.      special values `signal.SIG_IGN', `signal.SIG_DFL' or `None'.
  916.      Here, `signal.SIG_IGN' means that the signal was previously
  917.      ignored, `signal.SIG_DFL' means that the default way of handling
  918.      the signal was previously in use, and `None' means that the
  919.      previous signal handler was not installed from Python.
  920.  
  921.  - function of module signal: pause ()
  922.      Cause the process to sleep until a signal is received; the
  923.      appropriate handler will then be called.  Returns nothing.  (See
  924.      the UNIX man page `signal(2)'.)
  925.  
  926.  - function of module signal: signal (SIGNALNUM, HANDLER)
  927.      Set the handler for signal SIGNALNUM to the function HANDLER.
  928.      hANDLER can be any callable Python object, or one of the special
  929.      values `signal.SIG_IGN' or `signal.SIG_DFL'.  The previous signal
  930.      handler will be returned (see the description of `getsignal()'
  931.      above).  (See the UNIX man page `signal(2)'.)
  932.  
  933.      When threads are enabled, this function can only be called from the
  934.      main thread; attempting to call it from other threads will cause a
  935.      `ValueError' exception to be raised.
  936.  
  937.      The HANDLER is called with two arguments: the signal number and
  938.      the current stack frame (`None' or a frame object; see the
  939.      reference manual for a description of frame objects).
  940.  
  941. 
  942. File: pylibi,  Node: socket,  Prev: signal,  Up: Optional Operating System Services
  943.  
  944. Built-in Module `socket'
  945. ========================
  946.  
  947. This module provides access to the BSD *socket* interface.  It is
  948. available on UNIX systems that support this interface.
  949.  
  950. For an introduction to socket programming (in C), see the following
  951. papers: *An Introductory 4.3BSD Interprocess Communication Tutorial*,
  952. by Stuart Sechrest and *An Advanced 4.3BSD Interprocess Communication
  953. Tutorial*, by Samuel J.  Leffler et al, both in the UNIX Programmer's
  954. Manual, Supplementary Documents 1 (sections PS1:7 and PS1:8).  The UNIX
  955. manual pages for the various socket-related system calls are also a
  956. valuable source of information on the details of socket semantics.
  957.  
  958. The Python interface is a straightforward transliteration of the UNIX
  959. system call and library interface for sockets to Python's
  960. object-oriented style: the `socket()' function returns a "socket
  961. object" whose methods implement the various socket system calls.
  962. Parameter types are somewhat higer-level than in the C interface: as
  963. with `read()' and `write()' operations on Python files, buffer
  964. allocation on receive operations is automatic, and buffer length is
  965. implicit on send operations.
  966.  
  967. Socket addresses are represented as a single string for the `AF_UNIX'
  968. address family and as a pair `(HOST, PORT)' for the `AF_INET' address
  969. family, where HOST is a string representing either a hostname in
  970. Internet domain notation like `'daring.cwi.nl'' or an IP address like
  971. `'100.50.200.5'', and PORT is an integral port number.  Other address
  972. families are currently not supported.  The address format required by a
  973. particular socket object is automatically selected based on the address
  974. family specified when the socket object was created.
  975.  
  976. All errors raise exceptions.  The normal exceptions for invalid
  977. argument types and out-of-memory conditions can be raised; errors
  978. related to socket or address semantics raise the error `socket.error'.
  979.  
  980. Non-blocking mode is supported through the `setblocking()' method.
  981.  
  982. The module `socket' exports the following constants and functions:
  983.  
  984.  - exception of module socket: error
  985.      This exception is raised for socket- or address-related errors.
  986.      The accompanying value is either a string telling what went wrong
  987.      or a pair `(ERRNO, STRING)' representing an error returned by a
  988.      system call, similar to the value accompanying `posix.error'.
  989.  
  990.  - data of module socket: AF_UNIX
  991.  
  992.  - data of module socket: AF_INET
  993.      These constants represent the address (and protocol) families,
  994.      used for the first argument to `socket()'.  If the `AF_UNIX'
  995.      constant is not defined then this protocol is unsupported.
  996.  
  997.  - data of module socket: SOCK_STREAM
  998.  
  999.  - data of module socket: SOCK_DGRAM
  1000.  
  1001.  - data of module socket: SOCK_RAW
  1002.  
  1003.  - data of module socket: SOCK_RDM
  1004.  
  1005.  - data of module socket: SOCK_SEQPACKET
  1006.      These constants represent the socket types, used for the second
  1007.      argument to `socket()'.  (Only `SOCK_STREAM' and `SOCK_DGRAM'
  1008.      appear to be generally useful.)
  1009.  
  1010.  - data of module socket: SO_*
  1011.  
  1012.  - data of module socket: SOMAXCONN
  1013.  
  1014.  - data of module socket: MSG_*
  1015.  
  1016.  - data of module socket: SOL_*
  1017.  
  1018.  - data of module socket: IPPROTO_*
  1019.  
  1020.  - data of module socket: IPPORT_*
  1021.  
  1022.  - data of module socket: INADDR_*
  1023.  
  1024.  - data of module socket: IP_*
  1025.      Many constants of these forms, documented in the UNIX
  1026.      documentation on sockets and/or the IP protocol, are also defined
  1027.      in the socket module.  They are generally used in arguments to the
  1028.      `setsockopt' and `getsockopt' methods of socket objects.  In most
  1029.      cases, only those symbols that are defined in the UNIX header
  1030.      files are defined; for a few symbols, default values are provided.
  1031.  
  1032.  - function of module socket: gethostbyname (HOSTNAME)
  1033.      Translate a host name to IP address format.  The IP address is
  1034.      returned as a string, e.g.,  `'100.50.200.5''.  If the host name
  1035.      is an IP address itself it is returned unchanged.
  1036.  
  1037.  - function of module socket: gethostname ()
  1038.      Return a string containing the hostname of the machine where the
  1039.      Python interpreter is currently executing.  If you want to know the
  1040.      current machine's IP address, use
  1041.      `socket.gethostbyname(socket.gethostname())'.
  1042.  
  1043.  - function of module socket: gethostbyaddr (IP_ADDRESS)
  1044.      Return a triple `(hostname, aliaslist, ipaddrlist)' where
  1045.      `hostname' is the primary host name responding to the given
  1046.      IP_ADDRESS, `aliaslist' is a (possibly empty) list of alternative
  1047.      host names for the same address, and `ipaddrlist' is a list of IP
  1048.      addresses for the same interface on the same host (most likely
  1049.      containing only a single address).
  1050.  
  1051.  - function of module socket: getservbyname (SERVICENAME, PROTOCOLNAME)
  1052.      Translate an Internet service name and protocol name to a port
  1053.      number for that service.  The protocol name should be `'tcp'' or
  1054.      `'udp''.
  1055.  
  1056.  - function of module socket: socket (FAMILY, TYPE[, PROTO])
  1057.      Create a new socket using the given address family, socket type and
  1058.      protocol number.  The address family should be `AF_INET' or
  1059.      `AF_UNIX'.  The socket type should be `SOCK_STREAM', `SOCK_DGRAM'
  1060.      or perhaps one of the other `SOCK_' constants.  The protocol
  1061.      number is usually zero and may be omitted in that case.
  1062.  
  1063.  - function of module socket: fromfd (FD, FAMILY, TYPE[, PROTO])
  1064.      Build a socket object from an existing file descriptor (an integer
  1065.      as returned by a file object's `fileno' method).  Address family,
  1066.      socket type and protocol number are as for the `socket' function
  1067.      above.  The file descriptor should refer to a socket, but this is
  1068.      not checked -- subsequent operations on the object may fail if the
  1069.      file descriptor is invalid.  This function is rarely needed, but
  1070.      can be used to get or set socket options on a socket passed to a
  1071.      program as standard input or output (e.g. a server started by the
  1072.      UNIX inet daemon).
  1073.  
  1074. * Menu:
  1075.  
  1076. * Socket Objects::
  1077. * Socket Example::
  1078.  
  1079. 
  1080. File: pylibi,  Node: Socket Objects,  Next: Socket Example,  Prev: socket,  Up: socket
  1081.  
  1082. Socket Objects
  1083. --------------
  1084.  
  1085. Socket objects have the following methods.  Except for `makefile()'
  1086. these correspond to UNIX system calls applicable to sockets.
  1087.  
  1088.  - Method on socket: accept ()
  1089.      Accept a connection.  The socket must be bound to an address and
  1090.      listening for connections.  The return value is a pair `(CONN,
  1091.      ADDRESS)' where CONN is a *new* socket object usable to send and
  1092.      receive data on the connection, and ADDRESS is the address bound
  1093.      to the socket on the other end of the connection.
  1094.  
  1095.  - Method on socket: bind (ADDRESS)
  1096.      Bind the socket to ADDRESS.  The socket must not already be bound.
  1097.      (The format of ADDRESS depends on the address family -- see above.)
  1098.  
  1099.  - Method on socket: close ()
  1100.      Close the socket.  All future operations on the socket object will
  1101.      fail.  The remote end will receive no more data (after queued data
  1102.      is flushed).  Sockets are automatically closed when they are
  1103.      garbage-collected.
  1104.  
  1105.  - Method on socket: connect (ADDRESS)
  1106.      Connect to a remote socket at ADDRESS.  (The format of ADDRESS
  1107.      depends on the address family -- see above.)
  1108.  
  1109.  - Method on socket: fileno ()
  1110.      Return the socket's file descriptor (a small integer).  This is
  1111.      useful with `select'.
  1112.  
  1113.  - Method on socket: getpeername ()
  1114.      Return the remote address to which the socket is connected.  This
  1115.      is useful to find out the port number of a remote IP socket, for
  1116.      instance.  (The format of the address returned depends on the
  1117.      address family -- see above.)  On some systems this function is
  1118.      not supported.
  1119.  
  1120.  - Method on socket: getsockname ()
  1121.      Return the socket's own address.  This is useful to find out the
  1122.      port number of an IP socket, for instance.  (The format of the
  1123.      address returned depends on the address family -- see above.)
  1124.  
  1125.  - Method on socket: getsockopt (LEVEL, OPTNAME[, BUFLEN])
  1126.      Return the value of the given socket option (see the UNIX man page
  1127.      getsockopt(2)).  The needed symbolic constants (`SO_*' etc.) are
  1128.      defined in this module.  If BUFLEN is absent, an integer option is
  1129.      assumed and its integer value is returned by the function.  If
  1130.      BUFLEN is present, it specifies the maximum length of the buffer
  1131.      used to receive the option in, and this buffer is returned as a
  1132.      string.  It is up to the caller to decode the contents of the
  1133.      buffer (see the optional built-in module `struct' for a way to
  1134.      decode C structures encoded as strings).
  1135.  
  1136.  - Method on socket: listen (BACKLOG)
  1137.      Listen for connections made to the socket.  The BACKLOG argument
  1138.      specifies the maximum number of queued connections and should be at
  1139.      least 1; the maximum value is system-dependent (usually 5).
  1140.  
  1141.  - Method on socket: makefile ([MODE[, BUFSIZE]])
  1142.      Return a "file object" associated with the socket.  (File objects
  1143.      were described earlier under Built-in Types.)  The file object
  1144.      references a `dup()'ped version of the socket file descriptor, so
  1145.      the file object and socket object may be closed or
  1146.      garbage-collected independently.  The optional MODE and BUFSIZE
  1147.      arguments are interpreted the same way as by the built-in `open()'
  1148.      function.
  1149.  
  1150.  - Method on socket: recv (BUFSIZE[, FLAGS])
  1151.      Receive data from the socket.  The return value is a string
  1152.      representing the data received.  The maximum amount of data to be
  1153.      received at once is specified by BUFSIZE.  See the UNIX manual page
  1154.      for the meaning of the optional argument FLAGS; it defaults to
  1155.      zero.
  1156.  
  1157.  - Method on socket: recvfrom (BUFSIZE[, FLAGS])
  1158.      Receive data from the socket.  The return value is a pair
  1159.      `(STRING, ADDRESS)' where STRING is a string representing the data
  1160.      received and ADDRESS is the address of the socket sending the
  1161.      data.  The optional FLAGS argument has the same meaning as for
  1162.      `recv()' above.  (The format of ADDRESS depends on the address
  1163.      family -- see above.)
  1164.  
  1165.  - Method on socket: send (STRING[, FLAGS])
  1166.      Send data to the socket.  The socket must be connected to a remote
  1167.      socket.  The optional FLAGS argument has the same meaning as for
  1168.      `recv()' above.  Return the number of bytes sent.
  1169.  
  1170.  - Method on socket: sendto (STRING[, FLAGS], ADDRESS)
  1171.      Send data to the socket.  The socket should not be connected to a
  1172.      remote socket, since the destination socket is specified by
  1173.      `address'.  The optional FLAGS argument has the same meaning as
  1174.      for `recv()' above.  Return the number of bytes sent.  (The format
  1175.      of ADDRESS depends on the address family -- see above.)
  1176.  
  1177.  - Method on socket: setblocking (FLAG)
  1178.      Set blocking or non-blocking mode of the socket: if FLAG is 0, the
  1179.      socket is set to non-blocking, else to blocking mode.  Initially
  1180.      all sockets are in blocking mode.  In non-blocking mode, if a
  1181.      `recv' call doesn't find any data, or if a `send' call can't
  1182.      immediately dispose of the data, a `socket.error' exception is
  1183.      raised; in blocking mode, the calls block until they can proceed.
  1184.  
  1185.  - Method on socket: setsockopt (LEVEL, OPTNAME, VALUE)
  1186.      Set the value of the given socket option (see the UNIX man page
  1187.      setsockopt(2)).  The needed symbolic constants are defined in the
  1188.      `socket' module (`SO_*' etc.).  The value can be an integer or a
  1189.      string representing a buffer.  In the latter case it is up to the
  1190.      caller to ensure that the string contains the proper bits (see the
  1191.      optional built-in module `struct' for a way to encode C structures
  1192.      as strings).
  1193.  
  1194.  - Method on socket: shutdown (HOW)
  1195.      Shut down one or both halves of the connection.  If HOW is `0',
  1196.      further receives are disallowed.  If HOW is `1', further sends are
  1197.      disallowed.  If HOW is `2', further sends and receives are
  1198.      disallowed.
  1199.  
  1200. Note that there are no methods `read()' or `write()'; use `recv()' and
  1201. `send()' without FLAGS argument instead.
  1202.  
  1203. 
  1204. File: pylibi,  Node: Socket Example,  Prev: Socket Objects,  Up: socket
  1205.  
  1206. Example
  1207. -------
  1208.  
  1209. Here are two minimal example programs using the TCP/IP protocol: a
  1210. server that echoes all data that it receives back (servicing only one
  1211. client), and a client using it.  Note that a server must perform the
  1212. sequence `socket', `bind', `listen', `accept' (possibly repeating the
  1213. `accept' to service more than one client), while a client only needs
  1214. the sequence `socket', `connect'.  Also note that the server does not
  1215. `send'/`receive' on the socket it is listening on but on the new socket
  1216. returned by `accept'.
  1217.  
  1218.      # Echo server program
  1219.      from socket import *
  1220.      HOST = ''                 # Symbolic name meaning the local host
  1221.      PORT = 50007              # Arbitrary non-privileged server
  1222.      s = socket(AF_INET, SOCK_STREAM)
  1223.      s.bind(HOST, PORT)
  1224.      s.listen(1)
  1225.      conn, addr = s.accept()
  1226.      print 'Connected by', addr
  1227.      while 1:
  1228.          data = conn.recv(1024)
  1229.          if not data: break
  1230.          conn.send(data)
  1231.      conn.close()
  1232.  
  1233.      # Echo client program
  1234.      from socket import *
  1235.      HOST = 'daring.cwi.nl'    # The remote host
  1236.      PORT = 50007              # The same port as used by the server
  1237.      s = socket(AF_INET, SOCK_STREAM)
  1238.      s.connect(HOST, PORT)
  1239.      s.send('Hello, world')
  1240.      data = s.recv(1024)
  1241.      s.close()
  1242.      print 'Received', `data`
  1243.  
  1244. 
  1245. File: pylibi,  Node: The Python Debugger,  Next: The Python Profiler,  Prev: Optional Operating System Services,  Up: Top
  1246.  
  1247. The Python Debugger
  1248. *******************
  1249.  
  1250. The module `pdb' defines an interactive source code debugger for Python
  1251. programs.  It supports setting breakpoints and single stepping at the
  1252. source line level, inspection of stack frames, source code listing, and
  1253. evaluation of arbitrary Python code in the context of any stack frame.
  1254. It also supports post-mortem debugging and can be called under program
  1255. control.
  1256.  
  1257. The debugger is extensible -- it is actually defined as a class `Pdb'.
  1258. This is currently undocumented but easily understood by reading the
  1259. source.  The extension interface uses the (also undocumented) modules
  1260. `bdb' and `cmd'.
  1261.  
  1262. A primitive windowing version of the debugger also exists -- this is
  1263. module `wdb', which requires STDWIN (see the chapter on STDWIN specific
  1264. modules).
  1265.  
  1266. The debugger's prompt is "`(Pdb) '".  Typical usage to run a program
  1267. under control of the debugger is:
  1268.  
  1269.      >>> import pdb
  1270.      >>> import mymodule
  1271.      >>> pdb.run('mymodule.test()')
  1272.      > <string>(0)?()
  1273.      (Pdb) continue
  1274.      > <string>(1)?()
  1275.      (Pdb) continue
  1276.      NameError: 'spam'
  1277.      > <string>(1)?()
  1278.      (Pdb)
  1279.  
  1280. Typical usage to inspect a crashed program is:
  1281.  
  1282.      >>> import pdb
  1283.      >>> import mymodule
  1284.      >>> mymodule.test()
  1285.      Traceback (innermost last):
  1286.        File "<stdin>", line 1, in ?
  1287.        File "./mymodule.py", line 4, in test
  1288.          test2()
  1289.        File "./mymodule.py", line 3, in test2
  1290.          print spam
  1291.      NameError: spam
  1292.      >>> pdb.pm()
  1293.      > ./mymodule.py(3)test2()
  1294.      -> print spam
  1295.      (Pdb)
  1296.  
  1297. The module defines the following functions; each enters the debugger in
  1298. a slightly different way:
  1299.  
  1300.  - function of module pdb: run (STATEMENT[, GLOBALS[, LOCALS]])
  1301.      Execute the STATEMENT (given as a string) under debugger control.
  1302.      The debugger prompt appears before any code is executed; you can
  1303.      set breakpoints and type `continue', or you can step through the
  1304.      statement using `step' or `next' (all these commands are explained
  1305.      below).  The optional GLOBALS and LOCALS arguments specify the
  1306.      environment in which the code is executed; by default the
  1307.      dictionary of the module `__main__' is used.  (See the explanation
  1308.      of the `exec' statement or the `eval()' built-in function.)
  1309.  
  1310.  - function of module pdb: runeval (EXPRESSION[, GLOBALS[, LOCALS]])
  1311.      Evaluate the EXPRESSION (given as a a string) under debugger
  1312.      control.  When `runeval()' returns, it returns the value of the
  1313.      expression.  Otherwise this function is similar to `run()'.
  1314.  
  1315.  - function of module pdb: runcall (FUNCTION[, ARGUMENT, ...])
  1316.      Call the FUNCTION (a function or method object, not a string) with
  1317.      the given arguments.  When `runcall()' returns, it returns
  1318.      whatever the function call returned.  The debugger prompt appears
  1319.      as soon as the function is entered.
  1320.  
  1321.  - function of module pdb: set_trace ()
  1322.      Enter the debugger at the calling stack frame.  This is useful to
  1323.      hard-code a breakpoint at a given point in a program, even if the
  1324.      code is not otherwise being debugged (e.g. when an assertion
  1325.      fails).
  1326.  
  1327.  - function of module pdb: post_mortem (TRACEBACK)
  1328.      Enter post-mortem debugging of the given TRACEBACK object.
  1329.  
  1330.  - function of module pdb: pm ()
  1331.      Enter post-mortem debugging of the traceback found in
  1332.      `sys.last_traceback'.
  1333.  
  1334. * Menu:
  1335.  
  1336. * Debugger Commands::
  1337. * How It Works::
  1338.  
  1339.