Programming Languages — C++ Extensions for Networking

ISO/IEC TS 19216:2018 describes extensions to the C++ Standard Library. This document specifies requirements for implementations of an interface that computer programs written in the C++ programming language may use to perform operations related to networking, such as operations involving sockets, timers, bu˙er management, host name resolution and internet protocols. This document is applicable to information technology systems that can perform network operations, such as those with operating systems that conform to the POSIX interface. This document is applicable only to vendors who wish to provide the interface it describes.

Langages de programmation — Extensions C++ pour mise en réseau

General Information

Status
Published
Publication Date
23-Apr-2018
Current Stage
9093 - International Standard confirmed
Start Date
20-Sep-2021
Completion Date
20-Sep-2021
Ref Project

Buy Standard

Technical specification
ISO/IEC TS 19216:2018 - Programming Languages -- C++ Extensions for Networking
English language
227 pages
sale 15% off
Preview
sale 15% off
Preview

Standards Content (sample)

TECHNICAL ISO/IEC TS
SPECIFICATION 19216
First edition
2018-04
Programming Languages — C++
Extensions for Networking
Langages de programmation — Extensions C++ pour mise en réseau
Reference number
ISO/IEC TS 19216:2018(E)
ISO/IEC 2018
---------------------- Page: 1 ----------------------
ISO/IEC TS 19216:2018(E)
COPYRIGHT PROTECTED DOCUMENT
© ISO/IEC 2018

All rights reserved. Unless otherwise specified, or required in the context of its implementation, no part of this publication may

be reproduced or utilized otherwise in any form or by any means, electronic or mechanical, including photocopying, or posting

on the internet or an intranet, without prior written permission. Permission can be requested from either ISO at the address

below or ISO’s member body in the country of the requester.
ISO copyright office
CP 401 • Ch. de Blandonnet 8
CH-1214 Vernier, Geneva
Phone: +41 22 749 01 11
Fax: +41 22 749 09 47
Email: copyright@iso.org
Website: www.iso.org
Published in Switzerland
ii © ISO/IEC 2018 – All rights reserved
---------------------- Page: 2 ----------------------
ISO/IEC TS 19216:2018(E)
Contents
Foreword vi
1 Scope 1
2 Normative references 2
3 Terms and definitions 3
4 General Principles 4

4.1 Conformance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

4.2 Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

5 Namespaces and headers 5
6 Future plans (Informative) 6
7 Feature test macros (Informative) 7
8 Method of description (Informative) 8

8.1 Structure of each clause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

8.2 Other conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

9 Error reporting 9

9.1 Synchronous operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

9.2 Asynchronous operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

9.3 Error conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

9.4 Suppression of signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

10 Library summary 11
11 Convenience header 13

11.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

12 Forward declarations 14

12.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14

13 Asynchronous model 16

13.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

13.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

13.3 Class template async_result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

13.4 Class template async_completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

13.5 Class template associated_allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

13.6 Function get_associated_allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

13.7 Class execution_context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

13.8 Class execution_context::service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

13.9 Class template is_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

13.10 Executor argument tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

13.11 uses_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

�ISO/IEC 2018 – All rights reserved iii
---------------------- Page: 3 ----------------------
ISO/IEC TS 19216:2018(E)

13.12 Class template associated_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

13.13 Function get_associated_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

13.14 Class template executor_binder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

13.15 Function bind_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

13.16 Class template executor_work_guard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

13.17 Function make_work_guard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

13.18 Class system_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

13.19 Class system_context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

13.20 Class bad_executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

13.21 Class executor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

13.22 Function dispatch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

13.23 Function post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

13.24 Function defer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

13.25 Class template strand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

13.26 Class template use_future_t . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

13.27 Partial specialization of async_result for packaged_task . . . . . . . . . . . . . . . . . . . 59

14 Basic I/O services 61

14.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . 61

14.2 Class io_context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

14.3 Class io_context::executor_type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

15 Timers 67

15.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

15.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

15.3 Class template wait_traits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68

15.4 Class template basic_waitable_timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

16 Buffers 73

16.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

16.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

16.3 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.4 Class mutable_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

16.5 Class const_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

16.6 Buffer type traits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

16.7 Buffer sequence access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.8 Function buffer_size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.9 Function buffer_copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

16.10 Buffer arithmetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

16.11 Buffer creation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

16.12 Class template dynamic_vector_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

16.13 Class template dynamic_string_buffer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

16.14 Dynamic buffer creation functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

17 Buffer-oriented streams 92

17.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

17.2 Class transfer_all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

17.3 Class transfer_at_least . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

17.4 Class transfer_exactly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

17.5 Synchronous read operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

17.6 Asynchronous read operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

�ISO/IEC 2018 – All rights reserved iv
---------------------- Page: 4 ----------------------
ISO/IEC TS 19216:2018(E)

17.7 Synchronous write operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

17.8 Asynchronous write operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

17.9 Synchronous delimited read operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

17.10 Asynchronous delimited read operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102

18 Sockets 104

18.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

18.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106

18.3 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115

18.4 Class socket_base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

18.5 Socket options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118

18.6 Class template basic_socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121

18.7 Class template basic_datagram_socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

18.8 Class template basic_stream_socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

18.9 Class template basic_socket_acceptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

19 Socket iostreams 157

19.1 Class template basic_socket_streambuf . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

19.2 Class template basic_socket_iostream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

20 Socket algorithms 164

20.1 Synchronous connect operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

20.2 Asynchronous connect operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

21 Internet protocol 167

21.1 Header synopsis . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

21.2 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

21.3 Error codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

21.4 Class ip::address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

21.5 Class ip::address_v4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

21.6 Class ip::address_v6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

21.7 Class ip::bad_address_cast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

21.8 Hash support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

21.9 Class template ip::basic_address_iterator specializations . . . . . . . . . . . . . . . . . 187

21.10 Class template ip::basic_address_range specializations . . . . . . . . . . . . . . . . . . . 188

21.11 Class template ip::network_v4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

21.12 Class template ip::network_v6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

21.13 Class template ip::basic_endpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

21.14 Class template ip::basic_resolver_entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

21.15 Class template ip::basic_resolver_results . . . . . . . . . . . . . . . . . . . . . . . . . 201

21.16 Class ip::resolver_base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

21.17 Class template ip::basic_resolver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

21.18 Host name functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

21.19 Class ip::tcp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

21.20 Class ip::udp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

21.21 Internet socket options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

Index 219
Index of library names 221
Index of implementation-defined behavior 227
�ISO/IEC 2018 – All rights reserved v
---------------------- Page: 5 ----------------------
ISO/IEC TS 19216:2018(E)
Foreword

ISO (the International Organization for Standardization) and IEC (the International Electrotechnical

Commission) form the specialized system for worldwide standardization. National bodies that are members

of ISO or IEC participate in the development of International Standards through technical committees

established by the respective organization to deal with particular fields of technical activity. ISO and IEC

technical committees collaborate in fields of mutual interest. Other international organizations, governmental

and non-governmental, in liaison with ISO and IEC, also take part in the work. In the field of information

technology, ISO and IEC have established a joint technical committee, ISO/IEC JTC 1.

The procedures used to develop this document and those intended for its further maintenance are described

in the ISO/IEC Directives, Part 1. In particular the different approval criteria needed for the different types

of ISO documents should be noted. This document was drafted in accordance with the editorial rules of the

ISO/IEC Directives, Part 2 (see www.iso.org/directives).

Attention is drawn to the possibility that some of the elements of this document may be the subject of patent

rights. ISO shall not be held responsible for identifying any or all such patent rights. Details of any patent

rights identified during the development of the document will be in the Introduction and/or on the ISO list

of patent declarations received (see www.iso.org/patents).

Any trade name used in this document is information given for the convenience of users and does not

constitute an endorsement.

For an explanation on the voluntary nature of standards, the meaning of ISO specific terms and ex-

pressions related to conformity assessment, as well as information about ISO’s adherence to the World

Trade Organization (WTO) principles in the Technical Barriers to Trade (TBT) see the following URL:

www.iso.org/iso/foreword.html.

This document was prepared by Technical Committee ISO/IEC JTC 1, Information technology, Subcommittee

SC 22, Programming languages, their environments and system software interfaces.
Foreword �ISO/IEC 2018 – All rights reserved vi
---------------------- Page: 6 ----------------------
ISO/IEC TS 19216:2018(E)
1 Scope [scope]

This document describes extensions to the C Standard Library. This document specifies requirements for

implementations of an interface that computer programs written in the C programming language may use

to perform operations related to networking, such as operations involving sockets, timers, buffer management,

host name resolution and internet protocols. This document is applicable to information technology systems

that can perform network operations, such as those with operating systems that conform to the POSIX

interface. This document is applicable only to vendors who wish to provide the interface it describes.

Scope �ISO/IEC 2018 – All rights reserved 1
---------------------- Page: 7 ----------------------
ISO/IEC TS 19216:2018(E)
2 Normative references [references]

The following referenced documents are indispensable for the application of this document. For dated

references, only the edition cited applies. For undated references, the latest edition of the referenced document

(including any amendments) applies.
(1.1)
— ISO/IEC 14882:2014, Programming languages — C++
(1.2)
— ISO/IEC TS 19568:2015, C++ Extensions for Library Fundamentals
(1.3)

— ISO/IEC 9945:2009, Information Technology — Portable Operating System Interface (POSIX)

(1.4)
— ISO/IEC 2382-1:1993, Information technology — Vocabulary

The programming language and library described in ISO/IEC 14882 is herein called the C Standard.

++ ++

References to clauses within the C Standard are written as “C 2014, Clause 17”. The operating system

interface described in ISO/IEC 9945 is herein called POSIX.

This document mentions commercially available operating systems for purposes of exposition. POSIX�R is a

registered trademark of The IEEE. Windows�R is a registered trademark of Microsoft Corporation. This

information is given for the convenience of users of this document and does not constitute an endorsement by

ISO or IEC of these products.
++ ++

Unless otherwise specified, the whole of the C Standard’s Library introduction (C 2014, Clause 17) is

included into this document by reference.
Normative references �ISO/IEC 2018 – All rights reserved 2
---------------------- Page: 8 ----------------------
ISO/IEC TS 19216:2018(E)
3 Terms and definitions [defs]

For the purposes of this document, the terms and definitions given in ISO/IEC 14882:2014, ISO/IEC

2382-1:1993, and the following apply.

ISO and IEC maintain terminological databases for use in standardization at the following addresses:

(2.1)
— IEC Electropedia: available at http://www.electropedia.org/
(2.2)
— ISO Online browsing platform: available at http://www.iso.org/obp

Terms that are used only in a small portion of this document are defined where they are used and italicized

where they are defined.
3.1 [defs.host.byte.order]
host byte order

the arrangement of bytes in any integer type when using a specific machine architecture

[SOURCE: ISO/IEC 9945:2009, 3.193]
3.2 [defs.net.byte.order]
network byte order

the way of representing any integer type such that, when transmitted over a network via a network endpoint,

the int type is transmitted as an appropriate number of octets with the most significant octet first, followed

by any other octets in descending order of significance
[SOURCE: ISO/IEC 9945:2009, 3.237]
3.3 [defs.sync.op]
synchronous operation
operation where control is not returned until the operation completes
3.4 [defs.async.op]
asynchronous operation

operation where control is returned immediately without waiting for the operation to complete

[Note 1 to entry: Multiple asynchronous operations may be executed concurrently.—end note]

§ 3.4 �ISO/IEC 2018 – All rights reserved 3
---------------------- Page: 9 ----------------------
ISO/IEC TS 19216:2018(E)
4 General Principles [general]
4.1 Conformance [conformance]

Conformance is specified in terms of behavior. Ideal behavior is not always implementable, so the conformance

subclauses take that into account.
4.1.1 POSIX conformance [conformance.9945]

Some behavior is specified by reference to POSIX. How such behavior is actually implemented is unspecified.

[Note: This constitutes an “as if” rule allowing implementations to call native operating system or other

APIs. —end note]

Implementations are encouraged to provide such behavior as it is defined by POSIX. Implementations shall

document any behavior that differs from the behavior defined by POSIX. Implementations that do not support

exact POSIX behavior are encouraged to provide behavior as close to POSIX behavior as is reasonable

given the limitations of actual operating systems and file systems. If an implementation cannot provide any

reasonable behavior, the implementation shall report an error as specified in Error Reporting (9).

[Note: This allows users to rely on an exception being thrown or an error code being set when an implemen-

tation cannot provide any reasonable behavior. —end note]

Implementations are not required to provide behavior that is not supported by a particular operating system.

4.1.2 Conditionally-supported features [conformance.conditional]

This document defines conditionally-supported features, in the form of additional member functions on types

thatsatisfyProtocol(18.2.6),Endpoint(18.2.4),SettableSocketOption(18.2.9),GettableSocketOption(18.2.8)

or IoControlCommand (18.2.12) requirements.
2 ++

[Note: This is so that, when the additional member functions are available, C programs can extend the

library to add support for other protocols and socket options. —end note]

For the purposes of this document, implementations that provide all of the additional member functions are

known as extensible implementations.

[Note: Implementations are encouraged to provide the additional member functions, where possible. It is

intended that POSIX and Windows implementations will provide them. —end note]
4.2 Acknowledgments [intro.ack]

The design of this specification is based, in part, on the Asio library written by Christopher Kohlhoff.

§ 4.2 �ISO/IEC 2018 – All rights reserved 4
---------------------- Page: 10 ----------------------
ISO/IEC TS 19216:2018(E)
5 Namespaces and headers [namespaces]

The components described in this document are experimental and not part of the C standard library.

All components described in this document are declared in namespace std::experimental::net::v1 or a

sub-namespace thereof unless otherwise specified. The headers described in this document shall import the

contents of std::experimental::net::v1 into std::experimental::net as if by:
namespace std {
namespace experimental {
namespace net {
inline namespace v1 {}

Unless otherwise specified, references to other entities described in this document are assumed to be qualified

with std::experimental::net::v1::, references to entities described in the C standard are assumed to

be qualified with std::, and references to entities described in C Extensions for Library Fundamentals are

assumed to be qualified with std::experimental::fundamentals_v2::.
Namespaces and headers �ISO/IEC 2018 – All rights reserved 5
---------------------- Page: 11 ----------------------
ISO/IEC TS 19216:2018(E)
6 Future plans (Informative) [plans]

This clause describes tentative plans for future versions of this document and plans for moving content into

future versions of the C Standard.
2 ++

The C committee may release new versions of this document, containing networking library extensions

we hope to add to a near-future version of the C Standard. Future versions will define their contents

in std::experimental::net::v2, std::experimental::net::v3, etc., with the most recent implemented

version inlined into std::experimental::net.

When an extension defined in this or a future version of this document represents enough existing practice, it

will be moved into the next version of the C Standard by replacing the experimental::net::vN segment

of its namespace with net, and by removing the experimental/ prefix from its header’s path.

Future plans (Informative) �ISO/IEC 2018 – All rights reserved 6
---------------------- Page: 12 ----------------------
ISO/IEC TS 19216:2018(E)
7 Feature test macros (Informative)
[feature.test]

These macros allow users to determine which version of this document is supported by the headers defined

by the specification. All headers in this document shall define the __cpp_lib_experimental_net feature

test macro in Table 1.

If an implementation supplies all of the conditionally-supported features specified in 4.1.2, all headers in this

document shall additionally define the __cpp_lib_experimental_net_extensible feature test macro.

Table 1 — Feature-test macro(s)
Macro name Value
__cpp_lib_experimental_net 201707
__cpp_lib_experimental_net_extensible 201707
Feature test macros (Informative)�ISO/IEC 2018 – All rights reserved 7
---------------------- Page: 13 ----------------------
ISO/IEC TS 19216:2018(E)
8 Method of description (Informative)
[description]

This subclause describes the conventions used to specify this document, in addition to those conventions

specified in C 2014, 17.5.
8.1 Structure of each clause [structure]
8.1.1 Detailed specifications [structure.specifications]

In addition to the elements defined in C 2014, 17.5.1.4, descriptions of function semantics contain the

following elements (as appropriate):
(1.1)

— Completion signature: if the function initiates an asynchronous operation, specifies the signature of a

completion handler used to receive the result of the operation.
8.2 Other conventions [conventions]
8.2.1 Nested classes [nested.class]

Severalclassesdefinedinthisdocumentarenestedclasses. Foraspecifiednestedclass A::B,animplementation

is permitted to define A::B as a synonym for a class with equivalent functionality to class A::B. [Note: When

A::B is a synonym for another type A provides a nested type B, to emulate the injected class name. —end

note]
§ 8.2.1 �ISO/IEC 2018 – All rights reserved 8
---------------------- Page: 14 ----------------------
ISO/IEC TS 19216:2018(E)
9 Error reporting [err.report]
9.1 Synchronous operations [err.report.sync]

Most synchronous network library functions provide two overloads, one that throws an exception to report

system errors, and another that sets an error_code (C 2014, 19.5).
[Note: This supports two common use cases:
(1.1)

— Uses where system errors are truly exceptional and indicate a serious failure. Throwing an exception is

the most appropriate response.
(1.2)

— Uses where system errors are routine and do not necessarily represent failure. Returning an error code

is the most appropriate response. This allows application specific error handling, including simply

ignoring the error.
—end note]

Functions not having an argument of type error_code& report errors as follows, unless otherwise specified:

(2.1)

— When a call by the implementation to an operating system or other underlying API results in an error

that prevents the function from meeting its specifications, the function exits via an exception of a type

that would match a handler of type system_error.
(2.2)
— Destructors throw nothing.

Functions having an argument of type error_code& report errors as follows, unless otherwise specified:

(3.1)

— If a call by the implementation to an operating system or other underlying API results in an error

that prevents the function from meeting its specifications, the error_code& argument ec is set as

appropriate for the specific error. Otherwise, the ec argument is set such that !ec is true.

Where a function is specified as two overloads, with and without an argument of type error_code&:

R f(A1 a1, A2 a2, ..., AN aN);
R f(A1 a1, A2 a2, ..., AN aN, error_code& ec);
then, when R is non-void, the effects of the first overload are as if:
error_code ec;
R r(f(a1, a2, ..., aN, ec));
if (ec) throw system_error(ec, S);
return r;
otherwise, when R is void, the effects of the first overload are as if:
error_code ec;
f(a1, a2, ..., aN, ec);
if (ec) throw system_error(ec, S);

except that the type thrown may differ as specified above. S is an ntbs indicating where the exception was

thrown. [Note: A possible value for S is __func__. —end note]

For both overloads, failure to allocate storage is reported by throwing an exception as described in the C

standard (C 2014, 17.6.5.12).

In this document, when a type requirement is specified using two function call expressions f, with and without

an argument ec of type error_code:
§ 9.1 �ISO/IEC 2018 – All rights reserved 9
---------------------- Page: 15 ----------------------
ISO/IEC TS 19216:2018(E)
f(a1, a2, ..., aN)
f(a1, a2, ..., aN, ec)

then the effects of the first call expression of f shall be as described for the first overload above.

9.2 Asynchronous operations [err.report.async]

Asynchronous network library functions in this document are identified by having the prefix async_ and

take a completion handler (13.2.7.2). These asynchronous operations report errors as follows:

(1.1)

— If a call by the implementation to an operating system or other underlying API results in an error

that prevents the asynchronous operation from meeting its specifications, the completion handler is

invoked with an error_code value ec that is set as appropriate for the specific error. Otherwise, the

error_code value ec is set such that !ec is true.
(1.2)

— Asynchronous operations shall not fail with an error condition that indicates interruption of an

operating system or underlying API by a signal. [Note: Such as POSIX error number EINTR —end

note] Asynchronous operations shall not fail with any error condition associated with non-blocking

operations. [Note: Such as POSIX error numbers EWOULDBLOCK, EAGAIN, or EINPROGRESS; Windows

error numbers WSAEWOULDBLOCK or WSAEINPROGRESS —end note]

In this document, when a type requirement is specified as a call to a function or member function having the

prefix async_, then the function shall satisfy the error reporting requirements described above.

9.3 Error conditions [err.report.conditions]

Unless otherwise specified, when the behavior of a synchronous or asynchronous operation is defined “as

if” implemented by a POSIX function, the error_code produced by the function shall meet the following

requirements:
(1.1)

— If the failure condition is one that is listed by POSIX for that function, the error_code shall compare

equal to the error’s corresponding enum class errc (C 2014, 19.5) or enum class resolver_-

errc (21.3) constant.
(1.2)

— Otherwise, the error_code shall be set to an implementation-defined value that reflects the underlying

operating system error.
[Example: The POSIX specification for shut
...

Questions, Comments and Discussion

Ask us and Technical Secretary will try to provide an answer. You can facilitate discussion about the standard in here.