From a86af582b7834e9963422ad947bcf87a28d900fa Mon Sep 17 00:00:00 2001 From: CAM Gerlach Date: Thu, 9 Jun 2022 08:55:06 -0500 Subject: [PATCH] Doc: Update references and examples of old, unsupported OSes and uarches (GH-92791) (cherry picked from commit a5ba0f4ebca5020f6c77718a20663e0ac6e194ac) Co-authored-by: CAM Gerlach --- Doc/c-api/init_config.rst | 5 ++--- Doc/faq/library.rst | 10 ++++++++-- Doc/howto/sockets.rst | 19 ++++++++++++------- Doc/library/mmap.rst | 2 +- Doc/library/platform.rst | 2 +- Doc/library/posix.rst | 2 +- Doc/library/struct.rst | 7 ++++--- 7 files changed, 29 insertions(+), 18 deletions(-) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index 657d8e9caf1eab..2b6da2a7810bc4 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -689,9 +689,8 @@ PyConfig * ``"utf-8"`` if :c:member:`PyPreConfig.utf8_mode` is non-zero. * ``"ascii"`` if Python detects that ``nl_langinfo(CODESET)`` announces - the ASCII encoding (or Roman8 encoding on HP-UX), whereas the - ``mbstowcs()`` function decodes from a different encoding (usually - Latin1). + the ASCII encoding, whereas the ``mbstowcs()`` function + decodes from a different encoding (usually Latin1). * ``"utf-8"`` if ``nl_langinfo(CODESET)`` returns an empty string. * Otherwise, use the :term:`locale encoding`: ``nl_langinfo(CODESET)`` result. diff --git a/Doc/faq/library.rst b/Doc/faq/library.rst index b9e541c150dc43..85b04c963f5906 100644 --- a/Doc/faq/library.rst +++ b/Doc/faq/library.rst @@ -483,8 +483,14 @@ including :func:`~shutil.copyfile`, :func:`~shutil.copytree`, and How do I copy a file? --------------------- -The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. Note -that on MacOS 9 it doesn't copy the resource fork and Finder info. +The :mod:`shutil` module contains a :func:`~shutil.copyfile` function. +Note that on Windows NTFS volumes, it does not copy +`alternate data streams +`_ +nor `resource forks `__ +on macOS HFS+ volumes, though both are now rarely used. +It also doesn't copy file permissions and metadata, though using +:func:`shutil.copy2` instead will preserve most (though not all) of it. How do I read (or write) binary data? diff --git a/Doc/howto/sockets.rst b/Doc/howto/sockets.rst index e58f78a7cb0245..0bbf97da39768d 100644 --- a/Doc/howto/sockets.rst +++ b/Doc/howto/sockets.rst @@ -252,20 +252,25 @@ Binary Data ----------- It is perfectly possible to send binary data over a socket. The major problem is -that not all machines use the same formats for binary data. For example, a -Motorola chip will represent a 16 bit integer with the value 1 as the two hex -bytes 00 01. Intel and DEC, however, are byte-reversed - that same 1 is 01 00. +that not all machines use the same formats for binary data. For example, +`network byte order `_ +is big-endian, with the most significant byte first, +so a 16 bit integer with the value ``1`` would be the two hex bytes ``00 01``. +However, most common processors (x86/AMD64, ARM, RISC-V), are little-endian, +with the least significant byte first - that same ``1`` would be ``01 00``. + Socket libraries have calls for converting 16 and 32 bit integers - ``ntohl, htonl, ntohs, htons`` where "n" means *network* and "h" means *host*, "s" means *short* and "l" means *long*. Where network order is host order, these do nothing, but where the machine is byte-reversed, these swap the bytes around appropriately. -In these days of 32 bit machines, the ascii representation of binary data is +In these days of 64-bit machines, the ASCII representation of binary data is frequently smaller than the binary representation. That's because a surprising -amount of the time, all those longs have the value 0, or maybe 1. The string "0" -would be two bytes, while binary is four. Of course, this doesn't fit well with -fixed-length messages. Decisions, decisions. +amount of the time, most integers have the value 0, or maybe 1. +The string ``"0"`` would be two bytes, while a full 64-bit integer would be 8. +Of course, this doesn't fit well with fixed-length messages. +Decisions, decisions. Disconnecting diff --git a/Doc/library/mmap.rst b/Doc/library/mmap.rst index da174753361b2f..79733ed7d2d070 100644 --- a/Doc/library/mmap.rst +++ b/Doc/library/mmap.rst @@ -102,7 +102,7 @@ To map anonymous memory, -1 should be passed as the fileno along with the length To ensure validity of the created memory mapping the file specified by the descriptor *fileno* is internally automatically synchronized - with physical backing store on macOS and OpenVMS. + with the physical backing store on macOS. This example shows a simple way of using :class:`~mmap.mmap`:: diff --git a/Doc/library/platform.rst b/Doc/library/platform.rst index 346063d66afab9..dc2d871b47d5ef 100644 --- a/Doc/library/platform.rst +++ b/Doc/library/platform.rst @@ -53,7 +53,7 @@ Cross Platform .. function:: machine() - Returns the machine type, e.g. ``'i386'``. An empty string is returned if the + Returns the machine type, e.g. ``'AMD64'``. An empty string is returned if the value cannot be determined. diff --git a/Doc/library/posix.rst b/Doc/library/posix.rst index ad417a17879c1f..90be191aa2f8d7 100644 --- a/Doc/library/posix.rst +++ b/Doc/library/posix.rst @@ -37,7 +37,7 @@ Large File Support .. sectionauthor:: Steve Clift -Several operating systems (including AIX, HP-UX and Solaris) provide +Several operating systems (including AIX and Solaris) provide support for files that are larger than 2 GiB from a C programming model where :c:type:`int` and :c:type:`long` are 32-bit values. This is typically accomplished by defining the relevant size and offset types as 64-bit values. Such files are diff --git a/Doc/library/struct.rst b/Doc/library/struct.rst index eccba20fb8fe7e..978eeabe37b1a3 100644 --- a/Doc/library/struct.rst +++ b/Doc/library/struct.rst @@ -146,9 +146,10 @@ If the first character is not one of these, ``'@'`` is assumed. Native byte order is big-endian or little-endian, depending on the host system. For example, Intel x86 and AMD64 (x86-64) are little-endian; -Motorola 68000 and PowerPC G5 are big-endian; ARM and Intel Itanium feature -switchable endianness (bi-endian). Use ``sys.byteorder`` to check the -endianness of your system. +IBM z and most legacy architectures are big-endian; +and ARM, RISC-V and IBM Power feature switchable endianness +(bi-endian, though the former two are nearly always little-endian in practice). +Use ``sys.byteorder`` to check the endianness of your system. Native size and alignment are determined using the C compiler's ``sizeof`` expression. This is always combined with native byte order.