Skip to content

C
cpython
Commit 82a5c66a authored by Guido van Rossum's avatar Guido van Rossum
Browse files
Options

Added copious docstrings, plus two minor layout tweaks.

parent a4289a79
Hide whitespace changes
Inline Side-by-side
Showing with 309 additions and 39 deletions
Modules/socketmodule.c
View file @ 82a5c66a
......@@ -580,6 +580,13 @@ BUILD_FUNC_DEF_2(PySocketSock_accept,PySocketSockObject *,s, PyObject *,args)
return res;
}
static char accept_doc[] =
"accept() -> (socket object, address info)\n\
\n\
Wait for an incoming connection. Return a new socket representing the\n\
connection, and the address of the client. For IP sockets, the address\n\
info is a pair (hostaddr, port).";
/* s.setblocking(1 | 0) method */
......@@ -615,6 +622,12 @@ BUILD_FUNC_DEF_2(PySocketSock_setblocking,PySocketSockObject*,s,PyObject*,args)
return Py_None;
}
static char setblocking_doc[] =
"setblocking(flag)\n\
\n\
Set the socket to blocking (flag is true) or non-blocking (false).\n\
This uses the FIONBIO ioctl with the O_NDELAY flag.";
/* s.setsockopt() method.
With an integer third argument, sets an integer option.
......@@ -648,6 +661,12 @@ BUILD_FUNC_DEF_2(PySocketSock_setsockopt,PySocketSockObject *,s, PyObject *,args
return Py_None;
}
static char setsockopt_doc[] =
"setsockopt(level, option, value)\n\
\n\
Set a socket option. See the Unix manual for level and option.\n\
The value argument can either be an integer or a string.";
/* s.getsockopt() method.
With two arguments, retrieves an integer option.
......@@ -693,6 +712,13 @@ BUILD_FUNC_DEF_2(PySocketSock_getsockopt,PySocketSockObject *,s, PyObject *,args
return buf;
}
static char getsockopt_doc[] =
"getsockopt(level, option[, buffersize]) -> value\n\
\n\
Get a socket option. See the Unix manual for level and option.\n\
If a nonzero buffersize argument is given, the return value is a\n\
string of that length; otherwise it is an integer.";
/* s.bind(sockaddr) method */
......@@ -713,6 +739,12 @@ BUILD_FUNC_DEF_2(PySocketSock_bind,PySocketSockObject *,s, PyObject *,args)
return Py_None;
}
static char bind_doc[] =
"bind(address)\n\
\n\
Bind the socket to a local address. For IP sockets, the address is a\n\
pair (host, port); the host must refer to the local host.";
/* s.close() method.
Set the file descriptor to -1 so operations tried subsequently
......@@ -733,6 +765,11 @@ BUILD_FUNC_DEF_2(PySocketSock_close,PySocketSockObject *,s, PyObject *,args)
return Py_None;
}
static char close_doc[] =
"close()\n\
\n\
Close the socket. It cannot be used after this call.";
/* s.connect(sockaddr) method */
......@@ -753,6 +790,12 @@ BUILD_FUNC_DEF_2(PySocketSock_connect,PySocketSockObject *,s, PyObject *,args)
return Py_None;
}
static char connect_doc[] =
"connect(address)\n\
\n\
Connect the socket to a remote address. For IP sockets, the address\n\
is a pair (host, port).";
/* s.connect_ex(sockaddr) method */
......@@ -772,6 +815,12 @@ BUILD_FUNC_DEF_2(PySocketSock_connect_ex,PySocketSockObject *,s, PyObject *,args
return PyInt_FromLong((long) res);
}
static char connect_ex_doc[] =
"connect_ex(address)\n\
\n\
This is like connect(address), but returns an error code (the errno value)\n\
instead of raising an exception when an error occurs.";
/* s.fileno() method */
......@@ -783,6 +832,11 @@ BUILD_FUNC_DEF_2(PySocketSock_fileno,PySocketSockObject *,s, PyObject *,args)
return PyInt_FromLong((long) s->sock_fd);
}
static char fileno_doc[] =
"fileno() -> integer\n\
\n\
Return the integer file descriptor of the socket.";
#ifndef NO_DUP
/* s.dup() method */
......@@ -805,6 +859,12 @@ BUILD_FUNC_DEF_2(PySocketSock_dup,PySocketSockObject *,s, PyObject *,args)
close(newfd);
return sock;
}
static char dup_doc[] =
"dup() -> socket object\n\
\n\
Return a new socket object connected to the same system resource.";
#endif
......@@ -828,6 +888,12 @@ BUILD_FUNC_DEF_2(PySocketSock_getsockname,PySocketSockObject *,s, PyObject *,arg
return makesockaddr((struct sockaddr *) addrbuf, addrlen);
}
static char getsockname_doc[] =
"getsockname() -> address info\n\
\n\
Return the address of the local endpoint. For IP sockets, the address\n\
info is a pair (hostaddr, port).";
#ifdef HAVE_GETPEERNAME /* Cray APP doesn't have this :-( */
/* s.getpeername() method */
......@@ -848,6 +914,13 @@ BUILD_FUNC_DEF_2(PySocketSock_getpeername,PySocketSockObject *,s, PyObject *,arg
return PySocket_Err();
return makesockaddr((struct sockaddr *) addrbuf, addrlen);
}
static char getpeername_doc[] =
"getpeername() -> address info\n\
\n\
Return the address of the remote endpoint. For IP sockets, the address\n\
info is a pair (hostaddr, port).";
#endif /* HAVE_GETPEERNAME */
......@@ -871,6 +944,14 @@ BUILD_FUNC_DEF_2(PySocketSock_listen,PySocketSockObject *,s, PyObject *,args)
return Py_None;
}
static char listen_doc[] =
"listen(backlog)\n\
\n\
Enable a server to accept connections. The backlog argument must be at\n\
least 1; it specifies the number of unaccepted connection that the system\n\
will allow before refusing new connections.";
#ifndef NO_DUP
/* s.makefile(mode) method.
Create a new open file object referring to a dupped version of
......@@ -892,12 +973,12 @@ BUILD_FUNC_DEF_2(PySocketSock_makefile,PySocketSockObject *,s, PyObject *,args)
if (!PyArg_ParseTuple(args, "|si", &mode, &bufsize))
return NULL;
#ifdef MS_WIN32
if ( ((fd = _open_osfhandle( s->sock_fd, _O_BINARY )) < 0) ||
((fd = dup(fd)) < 0) || ((fp = fdopen(fd, mode)) == NULL)) {
if (((fd = _open_osfhandle(s->sock_fd, _O_BINARY)) < 0) ||
((fd = dup(fd)) < 0) || ((fp = fdopen(fd, mode)) == NULL))
#else
if ((fd = dup(s->sock_fd)) < 0 ||
(fp = fdopen(fd, mode)) == NULL) {
if ((fd = dup(s->sock_fd)) < 0 || (fp = fdopen(fd, mode)) == NULL)
#endif
{
if (fd >= 0)
close(fd);
return PySocket_Err();
......@@ -907,8 +988,16 @@ BUILD_FUNC_DEF_2(PySocketSock_makefile,PySocketSockObject *,s, PyObject *,args)
PyFile_SetBufSize(f, bufsize);
return f;
}
static char makefile_doc[] =
"makefile([mode[, buffersize]]) -> file object\n\
\n\
Return a regular file object corresponding to the socket.\n\
The mode and buffersize arguments are as for the built-in open() function.";
#endif /* NO_DUP */
/* s.recv(nbytes [,flags]) method */
static PyObject *
......@@ -933,6 +1022,14 @@ BUILD_FUNC_DEF_2(PySocketSock_recv,PySocketSockObject *,s, PyObject *,args)
return buf;
}
static char recv_doc[] =
"recv(buffersize[, flags]) -> data\n\
\n\
Receive up to buffersize bytes from the socket. For the optional flags\n\
argument, see the Unix manual. When no data is available, block until\n\
at least one byte is available or until the remote end is closed. When\n\
the remote end is closed and all data is read, return the empty string.";
/* s.recvfrom(nbytes [,flags]) method */
......@@ -982,6 +1079,11 @@ BUILD_FUNC_DEF_2(PySocketSock_recvfrom,PySocketSockObject *,s, PyObject *,args)
return ret;
}
static char recvfrom_doc[] =
"recvfrom(buffersize[, flags]) -> (data, address info)\n\
\n\
Like recv(buffersize, flags) but also return the sender's address info.";
/* s.send(data [,flags]) method */
......@@ -1000,6 +1102,12 @@ BUILD_FUNC_DEF_2(PySocketSock_send,PySocketSockObject *,s, PyObject *,args)
return PyInt_FromLong((long)n);
}
static char send_doc[] =
"send(data[, flags])\n\
\n\
Send a data string to the socket. For the optional flags\n\
argument, see the Unix manual.";
/* s.sendto(data, [flags,] sockaddr) method */
......@@ -1026,6 +1134,12 @@ BUILD_FUNC_DEF_2(PySocketSock_sendto,PySocketSockObject *,s, PyObject *,args)
return PyInt_FromLong((long)n);
}
static char sendto_doc[] =
"sendto(data[, flags], address)\n\
\n\
Like send(data, flags) but allows specifying the destination address.\n\
For IP sockets, the address is a pair (hostaddr, port).";
/* s.shutdown(how) method */
......@@ -1045,35 +1159,60 @@ BUILD_FUNC_DEF_2(PySocketSock_shutdown,PySocketSockObject *,s, PyObject *,args)
return Py_None;
}
static char shutdown_doc[] =
"shutdown(flag)\n\
\n\
Shut down the reading side of the socket (flag == 0), the writing side\n\
of the socket (flag == 1), or both ends (flag == 2).";
/* List of methods for socket objects */
static PyMethodDef PySocketSock_methods[] = {
{"accept", (PyCFunction)PySocketSock_accept},
{"setblocking", (PyCFunction)PySocketSock_setblocking},
{"setsockopt", (PyCFunction)PySocketSock_setsockopt},
{"getsockopt", (PyCFunction)PySocketSock_getsockopt, 1},
{"bind", (PyCFunction)PySocketSock_bind},
{"close", (PyCFunction)PySocketSock_close},
{"connect", (PyCFunction)PySocketSock_connect},
{"connect_ex", (PyCFunction)PySocketSock_connect_ex},
{"fileno", (PyCFunction)PySocketSock_fileno},
{"accept", (PyCFunction)PySocketSock_accept, 0,
accept_doc},
{"bind", (PyCFunction)PySocketSock_bind, 0,
bind_doc},
{"close", (PyCFunction)PySocketSock_close, 0,
close_doc},
{"connect", (PyCFunction)PySocketSock_connect, 0,
connect_doc},
{"connect_ex", (PyCFunction)PySocketSock_connect_ex, 0,
connect_ex_doc},
#ifndef NO_DUP
{"dup", (PyCFunction)PySocketSock_dup},
{"dup", (PyCFunction)PySocketSock_dup, 0,
dup_doc},
#endif
{"getsockname", (PyCFunction)PySocketSock_getsockname},
{"fileno", (PyCFunction)PySocketSock_fileno, 0,
fileno_doc},
#ifdef HAVE_GETPEERNAME
{"getpeername", (PyCFunction)PySocketSock_getpeername},
#endif
{"listen", (PyCFunction)PySocketSock_listen},
{"getpeername", (PyCFunction)PySocketSock_getpeername, 0,
getpeername_doc},
#endif
{"getsockname", (PyCFunction)PySocketSock_getsockname, 0,
getsockname_doc},
{"getsockopt", (PyCFunction)PySocketSock_getsockopt, 1,
getsockopt_doc},
{"listen", (PyCFunction)PySocketSock_listen, 0,
listen_doc},
#ifndef NO_DUP
{"makefile", (PyCFunction)PySocketSock_makefile, 1},
#endif
{"recv", (PyCFunction)PySocketSock_recv, 1},
{"recvfrom", (PyCFunction)PySocketSock_recvfrom, 1},
{"send", (PyCFunction)PySocketSock_send, 1},
{"sendto", (PyCFunction)PySocketSock_sendto},
{"shutdown", (PyCFunction)PySocketSock_shutdown},
{"makefile", (PyCFunction)PySocketSock_makefile, 1,
makefile_doc},
#endif
{"recv", (PyCFunction)PySocketSock_recv, 1,
recv_doc},
{"recvfrom", (PyCFunction)PySocketSock_recvfrom, 1,
recvfrom_doc},
{"send", (PyCFunction)PySocketSock_send, 1,
send_doc},
{"sendto", (PyCFunction)PySocketSock_sendto, 0,
sendto_doc},
{"setblocking", (PyCFunction)PySocketSock_setblocking, 0,
setblocking_doc},
{"setsockopt", (PyCFunction)PySocketSock_setsockopt, 0,
setsockopt_doc},
{"shutdown", (PyCFunction)PySocketSock_shutdown, 0,
shutdown_doc},
{NULL, NULL} /* sentinel */
};
......@@ -1148,6 +1287,11 @@ BUILD_FUNC_DEF_2(PySocket_gethostname,PyObject *,self, PyObject *,args)
return PyString_FromString(buf);
}
static char gethostname_doc[] =
"gethostname() -> string\n\
\n\
Return the current host name.";
/* Python interface to gethostbyname(name). */
......@@ -1164,6 +1308,12 @@ BUILD_FUNC_DEF_2(PySocket_gethostbyname,PyObject *,self, PyObject *,args)
return makeipaddr(&addrbuf);
}
static char gethostbyname_doc[] =
"gethostbyname(host) -> address\n\
\n\
Return the IP address (a string of the form '255.255.255.255') for a host.";
/* Python interface to gethostbyaddr(IP). */
/*ARGSUSED*/
......@@ -1249,6 +1399,12 @@ BUILD_FUNC_DEF_2(PySocket_gethostbyaddr,PyObject *,self, PyObject *, args)
return rtn_tuple;
}
static char gethostbyaddr_doc[] =
"gethostbyaddr(host) -> (name, aliaslist, addresslist)\n\
\n\
Return the true host name, a list of aliases, and a list of IP addresses,\n\
for a host. The host argument is a string giving a host name or IP number.";
/* Python interface to getservbyname(name).
This only returns the port number, since the other info is already
......@@ -1272,6 +1428,12 @@ BUILD_FUNC_DEF_2(PySocket_getservbyname,PyObject *,self, PyObject *,args)
return PyInt_FromLong((long) ntohs(sp->s_port));
}
static char getservbyname_doc[] =
"getservbyname(servicename, protocolname) -> integer\n\
\n\
Return a port number from a service name and protocol name.\n\
The protocol name should be 'tcp' or 'udp'.";
/* Python interface to getprotobyname(name).
This only returns the protocol number, since the other info is
......@@ -1295,6 +1457,11 @@ BUILD_FUNC_DEF_2(PySocket_getprotobyname,PyObject *,self, PyObject *,args)
return PyInt_FromLong((long) sp->p_proto);
}
static char getprotobyname_doc[] =
"getprotobyname(name) -> integer\n\
\n\
Return the protocol number for the named protocol. (Rarely used.)";
/* Python interface to socket(family, type, proto).
The third (protocol) argument is optional.
......@@ -1335,6 +1502,16 @@ BUILD_FUNC_DEF_2(PySocket_socket,PyObject *,self, PyObject *,args)
return (PyObject *) s;
}
static char socket_doc[] =
"socket(family, type[, proto]) -> socket object\n\
\n\
Open a socket of the given type. The family argument specifies the\n\
address family; it is normally AF_INET, sometimes AF_UNIX.\n\
The type argument specifies whether this is a stream (SOCK_STREAM)\n\
or datagram (SOCK_DGRAM) socket. The protocol argument defaults to 0,\n\
specifying the default protocol.";
#ifndef NO_DUP
/* Create a socket object from a numeric file description.
Useful e.g. if stdin is a socket.
......@@ -1360,8 +1537,16 @@ BUILD_FUNC_DEF_2(PySocket_fromfd,PyObject *,self, PyObject *,args)
#endif
return (PyObject *) s;
}
static char fromfd_doc[] =
"fromfd(fd, family, type[, proto]) -> socket object\n\
\n\
Create a socket object from the given file descriptor.\n\
The remaining arguments are the same as for socket().";
#endif /* NO_DUP */
static PyObject *
BUILD_FUNC_DEF_2(PySocket_ntohs, PyObject *, self, PyObject *, args)
{
......@@ -1374,6 +1559,12 @@ BUILD_FUNC_DEF_2(PySocket_ntohs, PyObject *, self, PyObject *, args)
return PyInt_FromLong(x2);
}
static char ntohs_doc[] =
"ntohs(integer) -> integer\n\
\n\
Convert a 16-bit integer from network to host byte order.";
static PyObject *
BUILD_FUNC_DEF_2(PySocket_ntohl, PyObject *, self, PyObject *, args)
{
......@@ -1386,6 +1577,12 @@ BUILD_FUNC_DEF_2(PySocket_ntohl, PyObject *, self, PyObject *, args)
return PyInt_FromLong(x2);
}
static char ntohl_doc[] =
"ntohl(integer) -> integer\n\
\n\
Convert a 32-bit integer from network to host byte order.";
static PyObject *
BUILD_FUNC_DEF_2(PySocket_htons, PyObject *, self, PyObject *, args)
{
......@@ -1398,6 +1595,12 @@ BUILD_FUNC_DEF_2(PySocket_htons, PyObject *, self, PyObject *, args)
return PyInt_FromLong(x2);
}
static char htons_doc[] =
"htons(integer) -> integer\n\
\n\
Convert a 16-bit integer from host to network byte order.";
static PyObject *
BUILD_FUNC_DEF_2(PySocket_htonl, PyObject *, self, PyObject *, args)
{
......@@ -1410,22 +1613,28 @@ BUILD_FUNC_DEF_2(PySocket_htonl, PyObject *, self, PyObject *, args)
return PyInt_FromLong(x2);
}
static char htonl_doc[] =
"htonl(integer) -> integer\n\
\n\
Convert a 32-bit integer from host to network byte order.";
/* List of functions exported by this module. */
static PyMethodDef PySocket_methods[] = {
{"gethostbyname", PySocket_gethostbyname},
{"gethostbyaddr", PySocket_gethostbyaddr},
{"gethostname", PySocket_gethostname},
{"getservbyname", PySocket_getservbyname},
{"getprotobyname", PySocket_getprotobyname},
{"socket", PySocket_socket, 1},
{"gethostbyname", PySocket_gethostbyname, 0, gethostbyname_doc},
{"gethostbyaddr", PySocket_gethostbyaddr, 0, gethostbyaddr_doc},
{"gethostname", PySocket_gethostname, 0, gethostname_doc},
{"getservbyname", PySocket_getservbyname, 0, getservbyname_doc},
{"getprotobyname", PySocket_getprotobyname, 0,getprotobyname_doc},
{"socket", PySocket_socket, 1, socket_doc},
#ifndef NO_DUP
{"fromfd", PySocket_fromfd, 1},
{"fromfd", PySocket_fromfd, 1, fromfd_doc},
#endif
{"ntohs", PySocket_ntohs},
{"ntohl", PySocket_ntohl},
{"htons", PySocket_htons},
{"htonl", PySocket_htonl},
{"ntohs", PySocket_ntohs, 0, ntohs_doc},
{"ntohl", PySocket_ntohl, 0, ntohl_doc},
{"htons", PySocket_htons, 0, htons_doc},
{"htonl", PySocket_htonl, 0, htonl_doc},
{NULL, NULL} /* Sentinel */
};
......@@ -1534,6 +1743,66 @@ OS2init()
* operating system's filesystem layer.
*/
static char module_doc[] =
"This module provides socket operations and some related functions.\n\
On Unix, it supports IP (Internet Protocol) and Unix domain sockets.\n\
On other systems, it only supports IP.\n\
\n\
Functions:\n\
\n\
socket() -- create a new socket object\n\
fromfd() -- create a socket object from an open file descriptor (*)\n\
gethostname() -- return the current hostname\n\
gethostbyname() -- map a hostname to its IP number\n\
gethostbyaddr() -- map an IP number or hostname to DNS info\n\
getservbyname() -- map a service name and a protocol name to a port number\n\
getprotobyname() -- mape a protocol name (e.g. 'tcp') to a number\n\
ntohs(), ntohl() -- convert 16, 32 bit int from network to host byte order\n\
htons(), htonl() -- convert 16, 32 bit int from host to network byte order\n\
\n\
(*) not available on all platforms!)\n\
\n\
Special objects:\n\
\n\
SocketType -- type object for socket objects\n\
error -- exception raised for I/O errors\n\
\n\
Integer constants:\n\
\n\
AF_INET, AF_UNIX -- socket domains (first argument to socket() call)\n\
SOCK_STREAM, SOCK_DGRAM, SOCK_RAW -- socket types (second argument)\n\
\n\
Many other constants may be defined; these may be used in calls to\n\
the setsockopt() and getsockopt() methods.\n\
";
static char sockettype_doc[] =
"A socket represents one endpoint of a network connection.\n\
\n\
Methods:\n\
\n\
accept() -- accept a connection, returning new socket and client address\n\
bind() -- bind the socket to a local address\n\
close() -- close the socket\n\
connect() -- connect the socket to a remote address\n\
connect_ex() -- connect, return an error code instead of an exception \n\
dup() -- return a new socket object identical to the current one (*)\n\
fileno() -- return underlying file descriptor\n\
getpeername() -- return remote address (*)\n\
getsockname() -- return local address\n\
getsockopt() -- get socket options\n\
listen() -- start listening for incoming connections\n\
makefile() -- return a file object corresponding tot the socket (*)\n\
recv() -- receive data\n\
recvfrom() -- receive data and sender's address\n\
send() -- send data\n\
sendto() -- send data to a given address\n\
setblocking() -- set or clear the blocking I/O flag\n\
setsockopt() -- set socket options\n\
shutdown() -- shut down traffic in one or both directions\n\
\n\
(*) not available on all platforms!)";
void
#if defined(MS_WINDOWS) || defined(PYOS_OS2)
init_socket()
......@@ -1545,14 +1814,14 @@ initsocket()
#ifdef MS_WINDOWS
if (!NTinit())
return;
m = Py_InitModule("_socket", PySocket_methods);
m = Py_InitModule3("_socket", PySocket_methods, module_doc);
#else
#if defined(__TOS_OS2__)
if (!OS2init())
return;
m = Py_InitModule("_socket", PySocket_methods);
m = Py_InitModule3("_socket", PySocket_methods, module_doc);
#else
m = Py_InitModule("socket", PySocket_methods);
m = Py_InitModule3("socket", PySocket_methods, module_doc);
#endif
#endif
d = PyModule_GetDict(m);
......@@ -1561,6 +1830,7 @@ initsocket()
return;
PyDict_SetItemString(d, "error", PySocket_Error);
PySocketSock_Type.ob_type = &PyType_Type;
PySocketSock_Type.tp_doc = sockettype_doc;
Py_INCREF(&PySocketSock_Type);
if (PyDict_SetItemString(d, "SocketType",
(PyObject *)&PySocketSock_Type) != 0)
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7