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 118 matching lines...) Expand 10 before | Expand all | Expand 10 after
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. ``aead``, ``hash``, 138 - *type* is the algorithm type as string, e.g. ``aead``, ``hash``,
139 ``skcipher`` 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 ``gcm(aes)``, ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or 142 ``sha256``, ``hmac(sha256)``, ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``.
143 ``drbg_nopr_ctr_aes256``. 143
144 144 - *feat* and *mask* are unsigned 32bit integers.
145 - *feat* and *mask* are unsigned int32 values. 145
146 Availability Linux 2.6.38, some algorithm types require more recent Kernels.
146 147
147 .. versionadded:: 3.6 148 .. versionadded:: 3.6
148 149
149 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) 150 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
150 support specific representations. 151 support specific representations.
151 152
152 .. XXX document them! 153 .. XXX document them!
153 154
154 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:
155 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
289 NI_* 290 NI_*
290 TCP_* 291 TCP_*
291 292
292 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
293 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
294 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt` 295 generally used in arguments to the :meth:`setsockopt` and :meth:`getsockopt`
295 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
296 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
297 provided. 298 provided.
298 299
300 .. versionchanged:: 3.6
301 ``SO_DOMAIN``, ``SO_PROTOCOL``, ``SO_PEERSEC``, ``SO_PASSSEC``
302 were added.
303
299 .. data:: AF_CAN 304 .. data:: AF_CAN
300 PF_CAN 305 PF_CAN
301 SOL_CAN_* 306 SOL_CAN_*
302 CAN_* 307 CAN_*
303 308
304 Many constants of these forms, documented in the Linux documentation, are 309 Many constants of these forms, documented in the Linux documentation, are
305 also defined in the socket module. 310 also defined in the socket module.
306 311
307 Availability: Linux >= 2.6.25. 312 Availability: Linux >= 2.6.25.
308 313
(...skipping 27 matching lines...) Expand all
336 SOL_RDS 341 SOL_RDS
337 RDS_* 342 RDS_*
338 343
339 Many constants of these forms, documented in the Linux documentation, are 344 Many constants of these forms, documented in the Linux documentation, are
340 also defined in the socket module. 345 also defined in the socket module.
341 346
342 Availability: Linux >= 2.6.30. 347 Availability: Linux >= 2.6.30.
343 348
344 .. versionadded:: 3.3 349 .. versionadded:: 3.3
345 350
351
346 .. data:: SIO_RCVALL 352 .. data:: SIO_RCVALL
347 SIO_KEEPALIVE_VALS 353 SIO_KEEPALIVE_VALS
348 SIO_LOOPBACK_FAST_PATH 354 SIO_LOOPBACK_FAST_PATH
349 RCVALL_* 355 RCVALL_*
350 356
351 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
352 :meth:`~socket.socket.ioctl` method of socket objects. 358 :meth:`~socket.socket.ioctl` method of socket objects.
353 359
354 .. versionchanged:: 3.6 360 .. versionchanged:: 3.6
355 ``SIO_LOOPBACK_FAST_PATH`` was added. 361 ``SIO_LOOPBACK_FAST_PATH`` was added.
356 362
357 363
358 .. data:: TIPC_* 364 .. data:: TIPC_*
359 365
360 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
361 the TIPC documentation for more information. 367 the TIPC documentation for more information.
362 368
363 .. data:: AF_ALG 369 .. data:: AF_ALG
364 SO_ALG 370 SOL_ALG
365 ALG_* 371 ALG_*
366 RDS_*
367 372
368 Constants for Linux Kernel cryptography. 373 Constants for Linux Kernel cryptography.
369 374
370 Availability: Linux >= 2.6.38. 375 Availability: Linux >= 2.6.38.
371 376
372 .. versionadded:: 3.6 377 .. versionadded:: 3.6
373 378
374 .. data:: AF_LINK 379 .. data:: AF_LINK
375 380
376 Availability: BSD, OSX. 381 Availability: BSD, OSX.
(...skipping 932 matching lines...) Expand 10 before | Expand all | Expand 10 after
1309 1314
1310 .. versionadded:: 3.3 1315 .. versionadded:: 3.3
1311 1316
1312 .. versionchanged:: 3.5 1317 .. versionchanged:: 3.5
1313 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
1314 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
1315 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1320 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1316 1321
1317 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]]) 1322 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]])
1318 1323
1324 Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
1319 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t. 1325 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t.
1320 1326
1321 Availability: Linux >= 2.6.38 1327 Availability: Linux >= 2.6.38
1322 1328
1323 .. versionadded:: 3.6 1329 .. versionadded:: 3.6
1324 1330
1325 .. method:: socket.sendfile(file, offset=0, count=None) 1331 .. method:: socket.sendfile(file, offset=0, count=None)
1326 1332
1327 Send a file until EOF is reached by using high-performance 1333 Send a file until EOF is reached by using high-performance
1328 :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.
(...skipping 34 matching lines...) Expand 10 before | Expand all | Expand 10 after
1363 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
1364 nonnegative floating point number expressing seconds, or ``None``. 1370 nonnegative floating point number expressing seconds, or ``None``.
1365 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
1366 :exc:`timeout` exception if the timeout period *value* has elapsed before 1372 :exc:`timeout` exception if the timeout period *value* has elapsed before
1367 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
1368 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.
1369 1375
1370 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>`.
1371 1377
1372 1378
1373 .. 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)
1374 1382
1375 .. index:: module: struct 1383 .. index:: module: struct
1376 1384
1377 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
1378 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the 1386 :manpage:`setsockopt(2)`). The needed symbolic constants are defined in the
1379 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer, 1387 :mod:`socket` module (:const:`SO_\*` etc.). The value can be an integer,
1380 a tuple in the form (None, integer) or or a :term:`bytes-like object` 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
1381 representing a buffer. In the latter case it is up to the caller to 1389 case it is up to the caller to ensure that the bytestring contains the
1382 ensure that the bytestring contains the proper bits (see the optional 1390 proper bits (see the optional built-in module :mod:`struct` for a way to
1383 built-in module :mod:`struct` for a way to encode C structures as 1391 encode C structures as bytestrings). When value is set to None,
1384 bytestrings). In the tuple form (None, number) sets optval=NULL and 1392 optlen argument is required. It's equivalent to call setsockopt C
1385 optlen=number. 1393 function with optval=NULL and optlen=optlen.
1386 1394
1387 1395
1388 .. versionchanged:: 3.5 1396 .. versionchanged:: 3.5
1389 Writable :term:`bytes-like object` is now accepted. 1397 Writable :term:`bytes-like object` is now accepted.
1390 1398
1391 .. versionchanged:: 3.6 1399 .. versionchanged:: 3.6
1392 (None, number) form added. 1400 setsockopt(level, optname, None, optlen: int) form added.
1393 1401
1394 1402
1395 .. method:: socket.shutdown(how) 1403 .. method:: socket.shutdown(how)
1396 1404
1397 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` ,
1398 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
1399 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
1400 disallowed. 1408 disallowed.
1401 1409
1402 1410
(...skipping 309 matching lines...) Expand 10 before | Expand all | Expand 10 after
1712 1720
1713 - *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
1714 al, 1722 al,
1715 1723
1716 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1724 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections
1717 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
1718 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
1719 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,
1720 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
1721 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+