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

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:
haypo 2016/08/29 00:11:35 feat: feature?
137
138 - *type* is the algorithm type as string, e.g. ``aead``, ``akcipher``,
139 ``hash``, ``skcipher`` or ``rng``.
140
141 - *name* is the algorithm name and operation mode as string, e.g.
142 ``gcm(aes)``, ``pkcs1pad(rsa,sha256)``, ``sha256``, ``hmac(sha256)``,
143 ``cbc(aes)`` or ``drbg_nopr_ctr_aes256``.
haypo 2016/08/29 00:11:35 Are all these algorithms always available on all p
christian.heimes 2016/08/29 08:10:37 It depends on the Kernel version which algorithms
144
145 - *feat* and *mask* are unsigned int32 values.
haypo 2016/08/29 00:11:35 unsigned 32 bit integer values? For me, "int32" i
christian.heimes 2016/08/29 08:10:37 sounds good
146
147 .. versionadded:: 3.6
133 148
134 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`) 149 - Certain other address families (:const:`AF_PACKET`, :const:`AF_CAN`)
135 support specific representations. 150 support specific representations.
136 151
137 .. XXX document them! 152 .. XXX document them!
138 153
139 For IPv4 addresses, two special forms are accepted instead of a host address: 154 For IPv4 addresses, two special forms are accepted instead of a host address:
140 the empty string represents :const:`INADDR_ANY`, and the string 155 the empty string represents :const:`INADDR_ANY`, and the string
141 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not 156 ``'<broadcast>'`` represents :const:`INADDR_BROADCAST`. This behavior is not
142 compatible with IPv6, therefore, you may want to avoid these if you intend 157 compatible with IPv6, therefore, you may want to avoid these if you intend
(...skipping 181 matching lines...) Expand 10 before | Expand all | Expand 10 after
324 PF_RDS 339 PF_RDS
325 SOL_RDS 340 SOL_RDS
326 RDS_* 341 RDS_*
327 342
328 Many constants of these forms, documented in the Linux documentation, are 343 Many constants of these forms, documented in the Linux documentation, are
329 also defined in the socket module. 344 also defined in the socket module.
330 345
331 Availability: Linux >= 2.6.30. 346 Availability: Linux >= 2.6.30.
332 347
333 .. versionadded:: 3.3 348 .. versionadded:: 3.3
334
haypo 2016/08/29 00:11:35 i like two empty lines for readability, please kee
335 349
336 .. data:: SIO_RCVALL 350 .. data:: SIO_RCVALL
337 SIO_KEEPALIVE_VALS 351 SIO_KEEPALIVE_VALS
338 SIO_LOOPBACK_FAST_PATH 352 SIO_LOOPBACK_FAST_PATH
339 RCVALL_* 353 RCVALL_*
340 354
341 Constants for Windows' WSAIoctl(). The constants are used as arguments to the 355 Constants for Windows' WSAIoctl(). The constants are used as arguments to the
342 :meth:`~socket.socket.ioctl` method of socket objects. 356 :meth:`~socket.socket.ioctl` method of socket objects.
343 357
344 .. versionchanged:: 3.6 358 .. versionchanged:: 3.6
345 ``SIO_LOOPBACK_FAST_PATH`` was added. 359 ``SIO_LOOPBACK_FAST_PATH`` was added.
346 360
347 361
348 .. data:: TIPC_* 362 .. data:: TIPC_*
349 363
350 TIPC related constants, matching the ones exported by the C socket API. See 364 TIPC related constants, matching the ones exported by the C socket API. See
351 the TIPC documentation for more information. 365 the TIPC documentation for more information.
366
367 .. data:: AF_ALG
368 SO_ALG
369 ALG_*
370 RDS_*
371
372 Constants for Linux Kernel cryptography.
373
374 Availability: Linux >= 2.6.38.
375
376 .. versionadded:: 3.6
352 377
353 .. data:: AF_LINK 378 .. data:: AF_LINK
354 379
355 Availability: BSD, OSX. 380 Availability: BSD, OSX.
356 381
357 .. versionadded:: 3.4 382 .. versionadded:: 3.4
358 383
359 .. data:: has_ipv6 384 .. data:: has_ipv6
360 385
361 This constant contains a boolean value which indicates if IPv6 is supported o n 386 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 879
855 The newly created socket is :ref:`non-inheritable <fd_inheritance>`. 880 The newly created socket is :ref:`non-inheritable <fd_inheritance>`.
856 881
857 .. versionchanged:: 3.4 882 .. versionchanged:: 3.4
858 The socket is now non-inheritable. 883 The socket is now non-inheritable.
859 884
860 .. versionchanged:: 3.5 885 .. versionchanged:: 3.5
861 If the system call is interrupted and the signal handler does not raise 886 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 887 an exception, the method now retries the system call instead of raising
863 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 888 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
864
865 889
866 .. method:: socket.bind(address) 890 .. method:: socket.bind(address)
867 891
868 Bind the socket to *address*. The socket must not already be bound. (The for mat 892 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.) 893 of *address* depends on the address family --- see above.)
870 894
871 895
872 .. method:: socket.close() 896 .. method:: socket.close()
873 897
874 Mark the socket closed. The underlying system resource (e.g. a file 898 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))]) 1310 return sock.sendmsg([msg], [(socket.SOL_SOCKET, socket.SCM_RIGHTS, arr ay.array("i", fds))])
1287 1311
1288 Availability: most Unix platforms, possibly others. 1312 Availability: most Unix platforms, possibly others.
1289 1313
1290 .. versionadded:: 3.3 1314 .. versionadded:: 3.3
1291 1315
1292 .. versionchanged:: 3.5 1316 .. versionchanged:: 3.5
1293 If the system call is interrupted and the signal handler does not raise 1317 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 1318 an exception, the method now retries the system call instead of raising
1295 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale). 1319 an :exc:`InterruptedError` exception (see :pep:`475` for the rationale).
1320
1321 .. method:: socket.sendmsg_afalg([msg], *, op[, iv[, assoclen[, flags]]])
1322
1323 Specialized version of :meth:`~socket.sendmsg` for :const:`AF_ALG` socket.
haypo 2016/08/29 00:11:35 Is it possible to implement sendmsg_afalg() in pur
christian.heimes 2016/08/29 08:10:37 It is possible to implement this with sendmsg(). I
1324 Set mode, IV, AEAD associated data length and flags for :const:`AF_ALG` socke t.
1325
1326 Availability: Linux >= 2.6.38
1327
1328 .. versionadded:: 3.6
1296 1329
1297 .. method:: socket.sendfile(file, offset=0, count=None) 1330 .. method:: socket.sendfile(file, offset=0, count=None)
1298 1331
1299 Send a file until EOF is reached by using high-performance 1332 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. 1333 :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 1334 *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 1335 :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 1336 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 1337 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 1338 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 1368 Set a timeout on blocking socket operations. The *value* argument can be a
1336 nonnegative floating point number expressing seconds, or ``None``. 1369 nonnegative floating point number expressing seconds, or ``None``.
1337 If a non-zero value is given, subsequent socket operations will raise a 1370 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 1371 :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 1372 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. 1373 non-blocking mode. If ``None`` is given, the socket is put in blocking mode.
1341 1374
1342 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`. 1375 For further information, please consult the :ref:`notes on socket timeouts <s ocket-timeouts>`.
1343 1376
1344 1377
1345 .. method:: socket.setsockopt(level, optname, value) 1378 .. method:: socket.setsockopt(level, optname, value[, intvalue])
haypo 2016/08/28 23:53:21 Ditto: I suggest to document the 3 syntaxes: .. m
christian.heimes 2016/08/29 08:10:37 I like that :)
1346 1379
1347 .. index:: module: struct 1380 .. index:: module: struct
1348 1381
1349 Set the value of the given socket option (see the Unix manual page 1382 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 1383 :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 1384 :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 1385 None or or a :term:`bytes-like object` representing a buffer. In the later
1353 up to the caller to 1386 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 1387 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). 1388 encode C structures as bytestrings). When value is set to None,
1389 intvalue argument is required. It's equivalent to call setsockopt C
1390 function with optval=NULL and optlen=intvalue.
1391
1356 1392
1357 .. versionchanged:: 3.5 1393 .. versionchanged:: 3.5
1358 Writable :term:`bytes-like object` is now accepted. 1394 Writable :term:`bytes-like object` is now accepted.
1359 1395
1396 .. versionchanged:: 3.6
1397 None, intvalue form added
haypo 2016/08/28 23:53:21 setsockopt(level, optname, None, length: int) form
1398
1360 1399
1361 .. method:: socket.shutdown(how) 1400 .. method:: socket.shutdown(how)
1362 1401
1363 Shut down one or both halves of the connection. If *how* is :const:`SHUT_RD` , 1402 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 1403 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 1404 are disallowed. If *how* is :const:`SHUT_RDWR`, further sends and receives a re
1366 disallowed. 1405 disallowed.
1367 1406
1368 1407
1369 .. method:: socket.share(process_id) 1408 .. method:: socket.share(process_id)
(...skipping 308 matching lines...) Expand 10 before | Expand all | Expand 10 after
1678 1717
1679 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et 1718 - *An Advanced 4.3BSD Interprocess Communication Tutorial*, by Samuel J. Lef fler et
1680 al, 1719 al,
1681 1720
1682 both in the UNIX Programmer's Manual, Supplementary Documents 1 (sections 1721 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 1722 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 1723 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, 1724 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 1725 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. 1726 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+