Advertisement
Not a member of Pastebin yet?
Sign Up,
it unlocks many cool features!
- socket
- 17.2 socket - Low-level networking interface
- This module provides access to the BSD socket interface. It is available
- on all modern UNIX systems, Windows, Mac OS X, BeOS, OS/2, and probably
- additional platforms.
- Note: Some behavior may be platform dependent, since calls are made to
- the operating system socket APIs.
- For an introduction to socket programming (in C), see the following papers:
- An introductory 4.3BSD Interprocess Communication Tutorial, by Stuart Sechrest
- and An Advanced 4.3BSD Interprocess Communication Tutorial, by Samuel J.
- Leffler et al, both in the UNIX Programmer's Manual, Supplementary Documents 1
- (sections PS1:7 and PS1:8). The platform-specific reference material for the
- various socket related system calls are also a valuable source of information
- on the details of socket semantics. For Unix, refer to the manual pages.
- The Python interface is a straightforward transliteration of the Unix
- system call and library interface for sockets to Python's object-oriented
- style: the socket() function returns a socket whose methods implement
- the various socket system calls. Parameter types are somewhat higher-level
- than in the C interface: as with read() and write() operations on Python files
- buffer allocation on receive operations is automatic, and buffer length is
- implicit on send operations.
- Socket addresses are represented as follows: A single string is used for the
- AF_INET address family, where the host is a string representing either
- a hostname in Internet domain notation like 'daring.cwi.nl' or an IPv4
- address like '100.50.200.5', and port is an integer. For AF_INET6 address
- family, a four-tuple (host, port, flowinfo, scopeid) is used, where flowinfo
- and scopeid represents sin6_flowinfo and sin6_scope_id member in struct
- sockaddr_in6 in C. For socket module methods, flowinfo and scopeid can be
- ommitted for backward compatibility. Note however, omission of scopeid can
- cause problems in manipulating scoped ipv6 addresses. Other address families
- are not currently supported. The address format required by a particular
- socket object is automatically selected based on the address family specified
- when the socket object was created.
- For IPv4 addresses, two special forms are accepted instead of a host address:
- the empty string represents INADDR_ANY, and the string '<broadcast>'
- represents INADDR_BROADCAST. The behavior is not available for IPv6 for
- backward compatibility, therefore you may want to avoid these if you intend
- to support IPv6 with your Python programs.
- If you use a hostname in the portion of IPv4/v6 socket address, the program
- may show a nondeterministic behavior, as Python uses the first address
- returned from the DNS resolution. The socket address will be resolved
- differently into an actual IPv4/v6 address, depending on the results from DNS
- resolution and or the host configuration. For deterministic behavior use a
- numeric address in host portion.
- New in version 2.5:AF_NETLINK sockets are represented as pairs pid, groups.
- New in version 2.6: Linux-only support for TIPC is also available using the
- AF_TIPC address family. TIPC is an open, non-IP based networked protocol
- designed for use in clustered computer environments. Addresses are
- represented by a tuple, and the fields depend on the address type. The
- general tuple form is (addr_type, v1, v2, v3 [, scope]), where:
- * addr_type is one of TIPC_ADDR_NAMESEQ, TIPC_ADDR_NAME, or TIPC_ADDR_ID.
- * scope is one of TIPC_ZONE_SCOPE, TIPC_CLUSTER_SCOPE, and TIPC_NODE_SCOPE.
- * if addr_type is TIPC_ADDR_NAME, then v1 is the server type, v2 is the port identifier, and v3 should be 0
- * if addr_type is TIPC_ADDR_NAMESEQ, then v1 is the server type, v2 is the lower port number, and v3 is the upper port number.
- * if addr_type is TIPC_ADDR_ID, then v1 is the node, v2 is the reference, and v3 should be set to 0.
- All errors raise exceptions. The normal exceptions for invalid argument types
- and out-of-memory conditions can be raised; errors related to socket or
- address semantics raise the error socket.error.
- Non-blocking mode is supported through setblocking(). A generalization of
- this based on the timeouts is supported through settimeout().
- The module socket exports the following constants and functions:
- exception socket.error
- This exception is raised for socket-related errors. The accompanying
- value is either a string telling what went wrong or a pair (erron, string)
- representing an error returned by a system call, similar to the value
- accompanying os.error. See the module errno, which contains names for the
- error codes defined by the underlying operating system.
- changed in version 2.6: socket.error is no a child class of IOError.
- exception socket.herror
- This exception is raised for address-related errors, i.e. for functions
- that use h_errno in the C API, including gethostbyname_ex() and
- gethostbyaddr().
- The accompanying value is a pair (h_errno, string) representing an error returned by a library call. string represents the description of h_errno, as returned by the hstrerror() C function.
- exception socket.gaierror
- This exception is raised for address-related errors, for getaddrinfo()
- and getnameinfo(). The accompanying value is a pair (error, string)
- representing an error returned by a library call. string represents the
- description of error, as returned by the gai_strerror()C function. The
- error value will match one of the EAI_* constants defined in this module.
- exception socket.timeout
- This exception is raised when a timeout occurs on a socket which has had
- timeouts enabled via a prior call to settimeout(). The accompanying
- value is a string whose value is currently always "timed out".
- New in version 2.3
- socket.AF_UNIX
- socket.AF_INET
- socket.AF_INET6
- These constants represent the address and protocol families, used for
- the first argument to socket(). If the AF_UNIX constant is not defined
- then this protocol is unsupported.
- socket.SOCK_STREAM
- socket.SOCK_DGRAM
- socket.SOCK_RAW
- socket.SOCK_RDM
- socket.SOCK_SEQPACKET
- These constants represent the socket types, used for the second argument to socket(). (Only SOCK_STREAM and SOCK_DGRAM appear to be generally useful.)
- SO_*
- socket.SOMAXCONN
- MSG_*
- SOL_*
- IPPROTO_*
- IPPORT_*
- INADDR_*
- IP_*
- IPV6_*
- EAI_*
- AI_*
- NI_*
- TCP_*
- Many constants of these forms, documented in the Unix documentation on
- sockets and/or IP protocol, are also defined in the socket module. They
- are generally used in arguments to the setsockopt() and getsockopt()
- methods of socket objects. In most cases, only those symbols that are
- defined in the Unix header files are defined; for a few symbols, default
- values are provided.
- SIO_*
- RCVALL_*
- Constant for Windows' WSAloctl(). The constants are used as arguments to
- the ioctl() method of socket objects.
- New in version 2.6
- TIPC_*
- TIPC related constants, matching the ones exported by the C socket API. See the TIPC documentation for more information.
- New in version 2.6
- socket.has_ipv6
- This constant contains a boolean value which indicates if IPv6 is supported on this platform.
- New in version 2.3
- socket.create_connection(address[, timeout[, source_address]])
- Connect to a TCP service listening on the Internet address (a 2-tuple (
- host, port)), and return the socket object. This is a higher-level
- function than socket.connect(): if host is a non-numeric hostname, it
- will try to resolve it for both AF_INET and AF_INET6, and then try to
- connect to all possible addresses in turn until a connection succeeds.
- This makes it easy to write clients that are compatible to both IPv4 and
- IPv6.
- Passing the optional timeout parameter will set the timeout on the
- socket instance before attempting to connect. If no timeout is supplied,
- the global default timeout setting returned by getdefaulttimeout() is
- used.
- If supplied, source_address must be a 2-tuple (host, port) for the
- socketto bind to as its source address before connecting. If host or
- port are '' or 0 respectively the OS default behavior will be used.
- New in version 2.6
- Changed in version 2.7: source_address was added.
- socket.getaddrinfo(host, port[, family[, socktype[, proto[, flags]]]])
- Translate the host/port argument into a sequence of 5-tuples that
- contain all the necessary arguments for creating a socket connected to
- that service. host is a domain name, a string representation of an
- IPv4/v6 address or None. port is a string service name such as 'http', a
- numeric port number or None. By passing None as the value of host and
- port, you can pass NULL to the underlying C API.
- The family, socktype and proto arguments can be optionally specified in
- order to narrow the list of addresses returned. By default, their value
- is 0, meaning that the full range of results is selected. The flags
- argument can be one or several of the AI_* constants, and will influence
- how results are computed and returned. Its default value is 0. For
- example, AI_NUMERICHOST will disable domain name resolution and will
- raise an error if the host is a domain name.
- The function returns a list of 5-tuples with the following structure:
- (family, socktype, proto, canonname, sockaddr)
- If these tuples, family, socktype, proto are all integers and are meant
- to be passed to the socket() function canonname will be empty. sockaddr
- is a tuple describing a socket address, whose format depends on the
- returned family (a (address, port) 2-tuple for AF_INET, a (address,
- port, flow info, scope id) 4-tuple for AF_INET6), and is meant to be
- passed to the socket.connect() method.
- The following example fetches address information for a hypothetical TCP
- connection to www.python.org on port 80 (results may differ on your
- system if IPv6 isn't enabled):
- >>> socket.getaddrinfo("www.python.org", 80, 0, 0, socket.SOL_TCP)
- [(2, 1, 6, '', ('82.94.164.162', 80)),
- (10, 1, 6, '', ('2001:888:2000:d::a2', 80, 0, 0))]
- socket.getfqdn([name])
- Return a fully qualified domain name for name. If name is omitted or
- empty, it is interpreted as the local host. To find the fully qualified
- name, the hostname returned by gethostbyaddr() is checked, followed by
- aliases for the host, if available. The first name which includes a
- period is selected. In case no fully qualified domain name is available,
- the hostname as returned by gethostname() is returned.
- socket.gethostbyname(hostname)
- translate a host name to IPv4 address format. The IPv4 address is
- returned as a string, such as '100.50.200.5'. If the host name is an
- IPv4 address itself it is returned unchanged. See gethostbyname_ex() for
- a more complete interface. gethostbyname() does not support IPv6 name
- resolution, and getaddrinfo() should be used instead for IPv4/v6 dual
- stack support.
- socket.gethostbyname_ex(hostname)
- Translate a host name to IPv4 address format, extended interface. Return
- a triple (hostname, aliaslist, ipaddrlist) where hostname is the primary
- host name responding to the given ip_address, aliaslist is a possibly
- empty list of alternative host names for the same address, and
- ipaddrlist is a list of IPv4 addresses for the same interface on the
- same host (often but not always a single address). gethostbyname_ex()
- does not support IPv6 name resolution, and getaddrinfo()should be used
- instead for IPv4/v6 dual stack support.
- socket.gethostname()
- Return a string containing the hostname of the machine where the Python
- interpreter is currently executing.
- If you want to know the current machines IP address, you may want to use
- gethostbyname(gethostname()). This operation assumes that there is a
- valid address-to-host mapping for the host, and the assumption does not
- always hold.
- Note: gethostname() doesn't always return the fqdn; use getfqdn() (see
- above).
- socket.gethostbyaddr(ip_address)
- Return a triple (hostname, aliaslist, ipaddrlist) where hostname is the
- primary host name responding to the given ip_address, aliaslist is a (
- possibly empty) list of alternative host names for the same address, and
- ipaddrlist is a list of IPv4/v6 addresses for the same interface on the
- same host (most likely containing only a single address). To find the
- fully qualified domain name, use the function getfqdn(). gethostbyaddr()
- supports both IPv4 and IPv6.
- socket.getnameinfo(sockaddr, flags)
- Translate a socket address sockaddr into a 2-tuple (host, port).
- Depending on the settings of flags, the result can contain a fully-
- qualified domain name or numeric address representation in host.
- Similarly, port can contain a string port name or a numeric port number.
- socket.getprotobyname(protocolname)
- Translate an Internet protocol name (for example, 'icmp') to a constant
- suitable for passing as the (optional) third argument to the socket()
- function. This is usually only needed for sockets opened in "raw" mode (
- SOCK_RAW); for the normal socket modes, the correct protocol is chosen
- automatically if the protocol is omitted or zero.
- socket.getservbyname(servicename[, protocolname])
- Translate an Internet service name and protocol name to a port number
- for that service. The optional protocol name, if given, should be 'tcp'
- or 'udp', otherwise any protocol will match.
- socket.getservbyport(port[, protocolname])
- Translate an Internet port number and protocol name to a service name
- for that service. The optional protocol name, if given, should be 'tcp'
- or 'udp', otherwise any protocol will match.
- socket.socket([family[, type[, proto]]])
- Create a new socket using the given address family, socket type and
- protocol number. The address family should be AF_INET (the default),
- AF_INET6 or AF_UNIX. The socket type should be SOCK_STREAM (the default)
- , SOCK_DGRAM or perhaps one of the other sock_ constants. The protocol
- number is usually zero and may be omitted in that case.
- socket.socketpair([family[, type[, proto]]])
- Build a pair of connected socket objects using the given address family,
- socket type, and protocol number. Address family, socket type and
- protocol number are as for the socket() function above. The default
- family is AF_UNIX if defined on the platform; otherwise the default is
- AF_INET. Availability: Unix.
- socket.fromfd(fd, family, type[, proto])
- Duplicate the file descriptor fd (an integer as returned by a file
- object’s fileno() method) and build a socket object from the result.
- Address family, socket type and protocol number are as for the socket()
- function above. The file descriptor should refer to a socket, but this
- is not checked — subsequent operations on the object may fail if the
- file descriptor is invalid. This function is rarely needed, but can be
- used to get or set socket options on a socket passed to a program as
- standard input or output (such as a server started by the Unix inet
- daemon). The socket is assumed to be in blocking mode. Availability: Unix
- socket.ntohl(x)
- Convert 32-bit positive integers from network to host byte order. On
- machines where the host byte order is the same as network byte order,
- this is a no-op; otherwise, it performs a 4-byte swap operation.
- socket.ntohs(x)
- Convert 16-bit positive integers from network to host byte order. On
- machines where the host byte order is the same as network byte order,
- this is a no-op; otherwise, it performs a 2-byte swap operation.
- socket.htonl(x)
- Convert 32-bit positive integers from host to network byte order. On
- machines where the host byte order is the same as network byte order,
- this is a no-op; otherwise, it performs a 4-byte swap operation.
- socket.htons(x)
- Convert 16-bit positive integers from host to network byte order. On
- machines where the host byte order is the same as network byte order,
- this is a no-op; otherwise, it performs a 2-byte swap operation.
- socket.inet_aton(ip_string)
- Convert an IPv4 address from dotted-quad string format (for example, ‘123
- .45.67.89’) to 32-bit packed binary format, as a string four characters
- in length. This is useful when conversing with a program that uses the
- standard C library and needs objects of type struct in_addr, which is
- the C type for the 32-bit packed binary this function returns.
- inet_aton() also accepts strings with less than three dots; see the Unix
- manual page inet(3) for details.
- If the IPv4 address string passed to this function is invalid, socket.
- error will be raised. Note that exactly what is valid depends on the
- underlying C implementation of inet_aton().
- inet_aton() does not support IPv6, and inet_pton() should be used
- instead for IPv4/v6 dual stack support.
- socket.inet_ntoa(packed_ip)
- Convert a 32-bit packed IPv4 address (a string four characters in length)
- to its standard dotted-quad string representation (for example, ‘123.45.
- 67.89’). This is useful when conversing with a program that uses the
- standard C library and needs objects of type struct in_addr, which is
- the C type for the 32-bit packed binary data this function takes as an
- argument.
- If the string passed to this function is not exactly 4 bytes in length,
- socket.error will be raised. inet_ntoa() does not support IPv6, and
- inet_ntop() should be used instead for IPv4/v6 dual stack support.
- socket.inet_pton(address_family, ip_string)
- Convert an IP address from its family-specific string format to a
- packed, binary format. inet_pton() is useful when a library or network
- protocol calls for an object of type struct in_addr (similar to inet_aton
- ()) or struct in6_addr.
- Supported values for address_family are currently AF_INET and AF_INET6.
- If the IP address string ip_string is invalid, socket.error will be
- raised. Note that exactly what is valid depends on both the value of
- address_family and the underlying implementation of inet_pton().
- Availability: Unix (maybe not all platforms).
- socket.inet_ntop(address_family, packed_ip)
- Convert a packed IP address (a string of some number of characters) to
- its standard, family-specific string representation (for example, '7.10.0
- .5' or '5aef:2b::8') inet_ntop() is useful when a library or network
- protocol returns an object of type struct in_addr (similar to inet_ntoa()
- ) or struct in6_addr.
- Supported values for address_family are currently AF_INET and AF_INET6.
- If the string packed_ip is not the correct length for the specified
- address family, ValueError will be raised. A socket.error is raised for
- errors from the call to inet_ntop().
- Availability: Unix (maybe not all platforms).
- socket.getdefaulttimeout()
- Return the default timeout in seconds (float) for new socket objects. A
- value of None indicates that new socket objects have no timeout. When
- the socket module is first imported, the default is None.
- socket.setdefaulttimeout(timeout)
- Set the default timeout in seconds (float) for new socket objects. A
- value of None indicates that new socket objects have no timeout. When
- the socket module is first imported, the default is None.
- socket.SocketType
- This is a Python type object that represents the socket object type. It
- is the same as type(socket(...)).
Advertisement
Add Comment
Please, Sign In to add comment
Advertisement