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

Delta Between Two Patch Sets: Doc/library/socket.rst

Issue 27744: Add AF_ALG (Linux Kernel crypto) to socket module
Left Patch Set: Created 3 years, 6 months ago
Right 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:
Left: Side by side diff | Download
Right: Side by side diff | Download
LEFTRIGHT
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 117 matching lines...) Expand 10 before | Expand all | Expand 10 after
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 133
134 - :const:`AF_ALG` is a Linux-only socket based interface to Kernel 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 135 cryptography. An algorithm socket is configured with a tuple of two to four
136 elements ``(type, name [, feat [, mask]])``, where: 136 elements ``(type, name [, feat [, mask]])``, where:
137 137
138 - *type* is the algorithm type as string, e.g. ``hash``, ``skcipher`` 138 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
139 or ``rng``. 139 ``skcipher`` or ``rng``.
140 140
141 - *name* is the algorithm name and operation mode as string, e.g. 141 - *name* is the algorithm name and operation mode as string, e.g.
142 ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``. 142 ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``.
143 143
144 - *feat* and *mask* are unsigned int 32 values. 144 - *feat* and *mask* are unsigned 32bit integers.
145
146 Availability Linux 2.6.38, some algorithm types require more recent Kernels.
145 147
146 .. versionadded:: 3.6 148 .. versionadded:: 3.6
147 149
148 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) 150 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
149 support specific representations. 151 support specific representations.
150 152
151 .. XXX document them! 153 .. XXX document them!
152 154
153 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:
154 the empty string represents :const:`INADDR_ANY`, and the string 156 the empty string represents :const:`INADDR_ANY`, and the string
(...skipping 133 matching lines...) Expand 10 before | Expand all | Expand 10 after
288 NI_* 290 NI_*
289 TCP_* 291 TCP_*
290 292
291 Many constants of these forms, documented in the Unix documentation on socket s 293 Many constants of these forms, documented in the Unix documentation on socket s
292 and/or the IP protocol, are also defined in the socket module. They are 294 and/or the IP protocol, are also defined in the socket module. They are
293 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt` 295 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
294 methods of socket objects. In most cases, only those symbols that are define d 296 methods of socket objects. In most cases, only those symbols that are define d
295 in the Unix header files are defined; for a few symbols, default values are 297 in the Unix header files are defined; for a few symbols, default values are
296 provided. 298 provided.
297 299
300 .. versionchanged:: 3.6
301 ``SO_DOMAIN``, ``SO_PROTOCOL``, ``SO_PEERSEC``, ``SO_PASSSEC``
302 were added.
303
298 .. data:: AF_CAN 304 .. data:: AF_CAN
299 PF_CAN 305 PF_CAN
300 SOL_CAN_* 306 SOL_CAN_*
301 CAN_* 307 CAN_*
302 308
303 Many constants of these forms, documented in the Linux documentation, are 309 Many constants of these forms, documented in the Linux documentation, are
304 also defined in the socket module. 310 also defined in the socket module.
305 311
306 Availability: Linux >= 2.6.25. 312 Availability: Linux >= 2.6.25.
307 313
(...skipping 27 matching lines...) Expand all
335 SOL_RDS 341 SOL_RDS
336 RDS_* 342 RDS_*
337 343
338 Many constants of these forms, documented in the Linux documentation, are 344 Many constants of these forms, documented in the Linux documentation, are
339 also defined in the socket module. 345 also defined in the socket module.
340 346
341 Availability: Linux >= 2.6.30. 347 Availability: Linux >= 2.6.30.
342 348
343 .. versionadded:: 3.3 349 .. versionadded:: 3.3
344 350
351
345 .. data:: SIO_RCVALL 352 .. data:: SIO_RCVALL
346 SIO_KEEPALIVE_VALS 353 SIO_KEEPALIVE_VALS
347 SIO_LOOPBACK_FAST_PATH 354 SIO_LOOPBACK_FAST_PATH
348 RCVALL_* 355 RCVALL_*
349 356
350 Constants for Windows' WSAIoctl(). The constants are used as arguments to the 357 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
351 :meth:`~socket.socket.ioctl` method of socket objects. 358 :meth:`~socket.socket.ioctl` method of socket objects.
352 359
353 .. versionchanged:: 3.6 360 .. versionchanged:: 3.6
354 ``SIO_LOOPBACK_FAST_PATH`` was added. 361 ``SIO_LOOPBACK_FAST_PATH`` was added.
355 362
356 363
357 .. data:: TIPC_* 364 .. data:: TIPC_*
358 365
359 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
360 the TIPC documentation for more information. 367 the TIPC documentation for more information.
361 368
362 .. data:: AF_ALG 369 .. data:: AF_ALG
363 SO_ALG 370 SOL_ALG
364 ALG_* 371 ALG_*
365 RDS_*
366 372
367 Constants for Linux Kernel cryptography. 373 Constants for Linux Kernel cryptography.
368 374
369 Availability: Linux >= 2.6.38. 375 Availability: Linux >= 2.6.38.
370 376
371 .. versionadded:: 3.6 377 .. versionadded:: 3.6
372 378
373 .. data:: AF_LINK 379 .. data:: AF_LINK
374 380
375 Availability: BSD, OSX. 381 Availability: BSD, OSX.
(...skipping 498 matching lines...) Expand 10 before | Expand all | Expand 10 after
874 880
875 The newly created socket is :ref:`non-inheritable <fd_inheritance>`. 881 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
876 882
877 .. versionchanged:: 3.4 883 .. versionchanged:: 3.4
878 The socket is now non-inheritable. 884 The socket is now non-inheritable.
879 885
880 .. versionchanged:: 3.5 886 .. versionchanged:: 3.5
881 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
882 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
883 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 889 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
884
885 .. method:: socket.algset(op[, iv[, assoclen[, flags]]])
886
887 Set mode, IV, AEAD assoc length and flags for :const:`AF_ALG` socket.
haypo 2016/08/17 13:20:25 "op" or "mode" (or "type" in the C code :-p)? "AE
888
889 .. versionadded:: 3.6
haypo 2016/08/17 13:20:25 Need also: Availability: Linux >= 2.6.38.
890 890
891 .. method:: socket.bind(address) 891 .. method:: socket.bind(address)
892 892
893 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
894 of *address* depends on the address family --- see above.) 894 of *address* depends on the address family --- see above.)
895 895
896 896
897 .. method:: socket.close() 897 .. method:: socket.close()
898 898
899 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 412 matching lines...) Expand 10 before | Expand all | Expand 10 after
1312 1312
1313 Availability: most Unix platforms, possibly others. 1313 Availability: most Unix platforms, possibly others.
1314 1314
1315 .. versionadded:: 3.3 1315 .. versionadded:: 3.3
1316 1316
1317 .. versionchanged:: 3.5 1317 .. versionchanged:: 3.5
1318 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
1319 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
1320 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1320 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1321 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
1330
1322 .. method:: socket.sendfile(file, offset=0, count=None) 1331 .. method:: socket.sendfile(file, offset=0, count=None)
1323 1332
1324 Send a file until EOF is reached by using high-performance 1333 Send a file until EOF is reached by using high-performance
1325 :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.
1326 *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
1327 :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
1328 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
1329 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
1330 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
1331 position is updated on return or also in case of error in which case 1340 position is updated on return or also in case of error in which case
(...skipping 28 matching lines...) Expand all
1360 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
1361 nonnegative floating point number expressing seconds, or ``None``. 1370 nonnegative floating point number expressing seconds, or ``None``.
1362 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
1363 :exc:`timeout` exception if the timeout period *value* has elapsed before 1372 :exc:`timeout` exception if the timeout period *value* has elapsed before
1364 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
1365 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.
1366 1375
1367 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>`.
1368 1377
1369 1378
1370 .. 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)
1371 1382
1372 .. index:: module: struct 1383 .. index:: module: struct
1373 1384
1374 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
1375 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1386 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
1376 :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,
1377 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
1378 up to the caller to 1389 case it is up to the caller to ensure that the bytestring contains the
1379 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
1380 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
1381 1395
1382 .. versionchanged:: 3.5 1396 .. versionchanged:: 3.5
1383 Writable :term:`bytes-like object` is now accepted. 1397 Writable :term:`bytes-like object` is now accepted.
1398
1399 .. versionchanged:: 3.6
1400 setsockopt(level, optname, None, optlen: int) form added.
1384 1401
1385 1402
1386 .. method:: socket.shutdown(how) 1403 .. method:: socket.shutdown(how)
1387 1404
1388 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` ,
1389 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
1390 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
1391 disallowed. 1408 disallowed.
1392 1409
1393 1410
(...skipping 309 matching lines...) Expand 10 before | Expand all | Expand 10 after
1703 1720
1704 - *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
1705 al, 1722 al,
1706 1723
1707 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1724 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
1708 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
1709 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
1710 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,
1711 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
1712 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.
LEFTRIGHT

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