Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(2)

Side by Side Diff: Doc/library/socket.rst

Issue 27744: Add AF_ALG (Linux Kernel crypto) to socket module
Patch Set: Created 3 years, 5 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
OLDNEW
1 :mod:`socket` --- Low-level networking interface 1 :mod:`socket` --- Low-level networking interface
2 ================================================ 2 ================================================
3 3
4 .. module:: socket 4 .. module:: socket
5 :synopsis: Low-level networking interface. 5 :synopsis: Low-level networking interface.
6 6
7 **Source code:** :source:`Lib/socket.py` 7 **Source code:** :source:`Lib/socket.py`
8 8
9 -------------- 9 --------------
10 10
(...skipping 112 matching lines...) Expand 10 before | Expand all | Expand 10 after
123 interface. (This depends on your OS; NetBSD and DragonFlyBSD expect 123 interface. (This depends on your OS; NetBSD and DragonFlyBSD expect
124 a Bluetooth address while everything else expects an integer.) 124 a Bluetooth address while everything else expects an integer.)
125 125
126 .. versionchanged:: 3.2 126 .. versionchanged:: 3.2
127 NetBSD and DragonFlyBSD support added. 127 NetBSD and DragonFlyBSD support added.
128 128
129 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a 129 - :const:`BTPROTO_SCO` accepts ``bdaddr`` where ``bdaddr`` is a
130 :class:`bytes` object containing the Bluetooth address in a 130 :class:`bytes` object containing the Bluetooth address in a
131 string format. (ex. ``b'12:23:34:45:56:67'``) This protocol is not 131 string format. (ex. ``b'12:23:34:45:56:67'``) This protocol is not
132 supported under FreeBSD. 132 supported under FreeBSD.
133
134 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel
135 cryptography. An algorithm socket is configured with a tuple of two to four
136 elements ``(type, name [, feat [, mask]])``, where:
137
138 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
139 ``skcipher`` or ``rng``.
140
141 - *name* is the algorithm name and operation mode as string, e.g.
142 ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``.
143
144 - *feat* and *mask* are unsigned 32bit integers.
145
146 Availability Linux 2.6.38, some algorithm types require more recent Kernels.
147
148 .. versionadded:: 3.6
133 149
134 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) 150 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
135 support specific representations. 151 support specific representations.
136 152
137 .. XXX document them! 153 .. XXX document them!
138 154
139 For IPv4 addresses, two special forms are accepted instead of a host address: 155 For IPv4 addresses, two special forms are accepted instead of a host address:
140 the empty string represents :const:`INADDR_ANY`, and the string 156 the empty string represents :const:`INADDR_ANY`, and the string
141 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not 157 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not
142 compatible with IPv6, therefore, you may want to avoid these if you intend 158 compatible with IPv6, therefore, you may want to avoid these if you intend
(...skipping 199 matching lines...) Expand 10 before | Expand all | Expand 10 after
342 :meth:`~socket.socket.ioctl` method of socket objects. 358 :meth:`~socket.socket.ioctl` method of socket objects.
343 359
344 .. versionchanged:: 3.6 360 .. versionchanged:: 3.6
345 ``SIO_LOOPBACK_FAST_PATH`` was added. 361 ``SIO_LOOPBACK_FAST_PATH`` was added.
346 362
347 363
348 .. data:: TIPC_* 364 .. data:: TIPC_*
349 365
350 TIPC related constants, matching the ones exported by the C socket API. See 366 TIPC related constants, matching the ones exported by the C socket API. See
351 the TIPC documentation for more information. 367 the TIPC documentation for more information.
368
369 .. data:: AF_ALG
370 SOL_ALG
371 ALG_*
372
373 Constants for Linux Kernel cryptography.
374
375 Availability: Linux >= 2.6.38.
376
377 .. versionadded:: 3.6
352 378
353 .. data:: AF_LINK 379 .. data:: AF_LINK
354 380
355 Availability: BSD, OSX. 381 Availability: BSD, OSX.
356 382
357 .. versionadded:: 3.4 383 .. versionadded:: 3.4
358 384
359 .. data:: has_ipv6 385 .. data:: has_ipv6
360 386
361 This constant contains a boolean value which indicates if IPv6 is supported o n 387 This constant contains a boolean value which indicates if IPv6 is supported o n
(...skipping 492 matching lines...) Expand 10 before | Expand all | Expand 10 after
854 880
855 The newly created socket is :ref:`non-inheritable <fd_inheritance>`. 881 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
856 882
857 .. versionchanged:: 3.4 883 .. versionchanged:: 3.4
858 The socket is now non-inheritable. 884 The socket is now non-inheritable.
859 885
860 .. versionchanged:: 3.5 886 .. versionchanged:: 3.5
861 If the system call is interrupted and the signal handler does not raise 887 If the system call is interrupted and the signal handler does not raise
862 an exception, the method now retries the system call instead of raising 888 an exception, the method now retries the system call instead of raising
863 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 889 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
864
865 890
866 .. method:: socket.bind(address) 891 .. method:: socket.bind(address)
867 892
868 Bind the socket to *address*. The socket must not already be bound. (The for mat 893 Bind the socket to *address*. The socket must not already be bound. (The for mat
869 of *address* depends on the address family --- see above.) 894 of *address* depends on the address family --- see above.)
870 895
871 896
872 .. method:: socket.close() 897 .. method:: socket.close()
873 898
874 Mark the socket closed. The underlying system resource (e.g. a file 899 Mark the socket closed. The underlying system resource (e.g. a file
(...skipping 411 matching lines...) Expand 10 before | Expand all | Expand 10 after
1286 return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, arr ay.array("i", fds))]) 1311 return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, arr ay.array("i", fds))])
1287 1312
1288 Availability: most Unix platforms, possibly others. 1313 Availability: most Unix platforms, possibly others.
1289 1314
1290 .. versionadded:: 3.3 1315 .. versionadded:: 3.3
1291 1316
1292 .. versionchanged:: 3.5 1317 .. versionchanged:: 3.5
1293 If the system call is interrupted and the signal handler does not raise 1318 If the system call is interrupted and the signal handler does not raise
1294 an exception, the method now retries the system call instead of raising 1319 an exception, the method now retries the system call instead of raising
1295 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1320 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1321
1322 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]])
1323
1324 Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
1325 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t.
1326
1327 Availability: Linux >= 2.6.38
1328
1329 .. versionadded:: 3.6
1296 1330
1297 .. method:: socket.sendfile(file, offset=0, count=None) 1331 .. method:: socket.sendfile(file, offset=0, count=None)
1298 1332
1299 Send a file until EOF is reached by using high-performance 1333 Send a file until EOF is reached by using high-performance
1300 :mod:`os.sendfile` and return the total number of bytes which were sent. 1334 :mod:`os.sendfile` and return the total number of bytes which were sent.
1301 *file* must be a regular file object opened in binary mode. If 1335 *file* must be a regular file object opened in binary mode. If
1302 :mod:`os.sendfile` is not available (e.g. Windows) or *file* is not a 1336 :mod:`os.sendfile` is not available (e.g. Windows) or *file* is not a
1303 regular file :meth:`send` will be used instead. *offset* tells from where to 1337 regular file :meth:`send` will be used instead. *offset* tells from where to
1304 start reading the file. If specified, *count* is the total number of bytes 1338 start reading the file. If specified, *count* is the total number of bytes
1305 to transmit as opposed to sending the file until EOF is reached. File 1339 to transmit as opposed to sending the file until EOF is reached. File
(...skipping 29 matching lines...) Expand all
1335 Set a timeout on blocking socket operations. The *value* argument can be a 1369 Set a timeout on blocking socket operations. The *value* argument can be a
1336 nonnegative floating point number expressing seconds, or ``None``. 1370 nonnegative floating point number expressing seconds, or ``None``.
1337 If a non-zero value is given, subsequent socket operations will raise a 1371 If a non-zero value is given, subsequent socket operations will raise a
1338 :exc:`timeout` exception if the timeout period *value* has elapsed before 1372 :exc:`timeout` exception if the timeout period *value* has elapsed before
1339 the operation has completed. If zero is given, the socket is put in 1373 the operation has completed. If zero is given, the socket is put in
1340 non-blocking mode. If ``None`` is given, the socket is put in blocking mode. 1374 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1341 1375
1342 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. 1376 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`.
1343 1377
1344 1378
1345 .. method:: socket.setsockopt(level, optname, value) 1379 .. method:: socket.setsockopt(level, optname, value: int)
1380 .. method:: socket.setsockopt(level, optname, value: buffer)
1381 .. method:: socket.setsockopt(level, optname, None, optlen: int)
1346 1382
1347 .. index:: module: struct 1383 .. index:: module: struct
1348 1384
1349 Set the value of the given socket option (see the Unix manual page 1385 Set the value of the given socket option (see the Unix manual page
1350 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1386 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
1351 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer or 1387 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer,
1352 a :term:`bytes-like object` representing a buffer. In the latter case it is 1388 None or or a :term:`bytes-like object` representing a buffer. In the later
Martin Panter 2016/09/04 16:01:03 “or” is doubled
christian.heimes 2016/09/04 16:58:44 thanks, fixed
1353 up to the caller to 1389 case it is up to the caller to ensure that the bytestring contains the
1354 ensure that the bytestring contains the proper bits (see the optional built-i n 1390 proper bits (see the optional built-in module :mod:`struct` for a way to
1355 module :mod:`struct` for a way to encode C structures as bytestrings). 1391 encode C structures as bytestrings). When value is set to None,
1392 optlen argument is required. It's equivalent to call setsockopt C
1393 function with optval=NULL and optlen=optlen.
1394
1356 1395
1357 .. versionchanged:: 3.5 1396 .. versionchanged:: 3.5
1358 Writable :term:`bytes-like object` is now accepted. 1397 Writable :term:`bytes-like object` is now accepted.
1359 1398
1399 .. versionchanged:: 3.6
1400 setsockopt(level, optname, None, optlen: int) form added.
1401
1360 1402
1361 .. method:: socket.shutdown(how) 1403 .. method:: socket.shutdown(how)
1362 1404
1363 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , 1405 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` ,
1364 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends 1406 further receives are disallowed. If *how* is :const:`SHUT_WR`, further sends
1365 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re 1407 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re
1366 disallowed. 1408 disallowed.
1367 1409
1368 1410
1369 .. method:: socket.share(process_id) 1411 .. method:: socket.share(process_id)
(...skipping 308 matching lines...) Expand 10 before | Expand all | Expand 10 after
1678 1720
1679 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et 1721 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et
1680 al, 1722 al,
1681 1723
1682 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1724 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
1683 PS1:7 and PS1:8). The platform-specific reference material for the various 1725 PS1:7 and PS1:8). The platform-specific reference material for the various
1684 socket-related system calls are also a valuable source of information on the 1726 socket-related system calls are also a valuable source of information on the
1685 details of socket semantics. For Unix, refer to the manual pages; for Window s, 1727 details of socket semantics. For Unix, refer to the manual pages; for Window s,
1686 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay 1728 see the WinSock (or Winsock 2) specification. For IPv6-ready APIs, readers m ay
1687 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6. 1729 want to refer to :rfc:`3493` titled Basic Socket Interface Extensions for IPv 6.
OLDNEW
« no previous file with comments | « configure.ac ('k') | Lib/test/test_socket.py » ('j') | Lib/test/test_socket.py » ('J')

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+