idnits 2.17.1 draft-dreibholz-taps-neat-socketapi-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 11, 2017) is 2570 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-05) exists of draft-gjessing-taps-minset-04 == Outdated reference: A later version (-09) exists of draft-ietf-taps-transports-usage-04 Summary: 0 errors (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Dreibholz 3 Internet-Draft Simula Research Laboratory 4 Intended status: Experimental April 11, 2017 5 Expires: October 13, 2017 7 NEAT Sockets API 8 draft-dreibholz-taps-neat-socketapi-00.txt 10 Abstract 12 This document describes the NEAT Sockets API. 14 Status of This Memo 16 This Internet-Draft is submitted in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF). Note that other groups may also distribute 21 working documents as Internet-Drafts. The list of current Internet- 22 Drafts is at http://datatracker.ietf.org/drafts/current/. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 This Internet-Draft will expire on October 13, 2017. 31 Copyright Notice 33 Copyright (c) 2017 IETF Trust and the persons identified as the 34 document authors. All rights reserved. 36 This document is subject to BCP 78 and the IETF Trust's Legal 37 Provisions Relating to IETF Documents 38 (http://trustee.ietf.org/license-info) in effect on the date of 39 publication of this document. Please review these documents 40 carefully, as they describe your rights and restrictions with respect 41 to this document. Code Components extracted from this document must 42 include Simplified BSD License text as described in Section 4.e of 43 the Trust Legal Provisions and are provided without warranty as 44 described in the Simplified BSD License. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 49 1.1. Conventions . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Initialisation and Clean-Up . . . . . . . . . . . . . . . . . 3 51 2.1. nsa_cleanup() . . . . . . . . . . . . . . . . . . . . . . 4 52 2.2. nsa_map_socket() . . . . . . . . . . . . . . . . . . . . 4 53 2.3. nsa_unmap_socket() . . . . . . . . . . . . . . . . . . . 4 54 3. Connection Establishment and Teardown . . . . . . . . . . . . 5 55 3.1. nsa_socket() . . . . . . . . . . . . . . . . . . . . . . 5 56 3.2. nsa_close() . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.3. nsa_fcntl() . . . . . . . . . . . . . . . . . . . . . . . 6 58 3.4. nsa_bind() . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.5. nsa_bindx() . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.6. nsa_bindn() . . . . . . . . . . . . . . . . . . . . . . . 8 61 3.7. nsa_connect() . . . . . . . . . . . . . . . . . . . . . . 8 62 3.8. nsa_connectx() . . . . . . . . . . . . . . . . . . . . . 9 63 3.9. nsa_connectn() . . . . . . . . . . . . . . . . . . . . . 9 64 3.10. nsa_listen() . . . . . . . . . . . . . . . . . . . . . . 10 65 3.11. nsa_accept() . . . . . . . . . . . . . . . . . . . . . . 10 66 3.12. nsa_shutdown() . . . . . . . . . . . . . . . . . . . . . 11 67 4. Options Handling . . . . . . . . . . . . . . . . . . . . . . 11 68 4.1. nsa_getsockopt() . . . . . . . . . . . . . . . . . . . . 11 69 4.2. nsa_setsockopt() . . . . . . . . . . . . . . . . . . . . 12 70 4.3. nsa_opt_info() . . . . . . . . . . . . . . . . . . . . . 13 71 5. Security . . . . . . . . . . . . . . . . . . . . . . . . . . 13 72 5.1. nsa_set_secure_identity() . . . . . . . . . . . . . . . . 13 73 5.2. ... . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 74 6. Input/Output Handling . . . . . . . . . . . . . . . . . . . . 13 75 6.1. nsa_write() . . . . . . . . . . . . . . . . . . . . . . . 13 76 6.2. nsa_send() . . . . . . . . . . . . . . . . . . . . . . . 14 77 6.3. nsa_sendto() . . . . . . . . . . . . . . . . . . . . . . 14 78 6.4. nsa_sendmsg() . . . . . . . . . . . . . . . . . . . . . . 15 79 6.5. nsa_sendv() . . . . . . . . . . . . . . . . . . . . . . . 16 80 6.6. nsa_read() . . . . . . . . . . . . . . . . . . . . . . . 16 81 6.7. nsa_recv() . . . . . . . . . . . . . . . . . . . . . . . 17 82 6.8. nsa_recvfrom() . . . . . . . . . . . . . . . . . . . . . 17 83 6.9. nsa_recvmsg() . . . . . . . . . . . . . . . . . . . . . . 18 84 6.10. nsa_recvv() . . . . . . . . . . . . . . . . . . . . . . . 19 85 7. Poll and Select . . . . . . . . . . . . . . . . . . . . . . . 20 86 7.1. nsa_poll() . . . . . . . . . . . . . . . . . . . . . . . 20 87 7.2. nsa_select() . . . . . . . . . . . . . . . . . . . . . . 20 88 8. Address Handling . . . . . . . . . . . . . . . . . . . . . . 20 89 8.1. nsa_getsockname() . . . . . . . . . . . . . . . . . . . . 20 90 8.2. nsa_getpeername() . . . . . . . . . . . . . . . . . . . . 21 91 8.3. nsa_getladdrs() . . . . . . . . . . . . . . . . . . . . . 22 92 8.4. nsa_freeladdrs() . . . . . . . . . . . . . . . . . . . . 22 93 8.5. nsa_getpaddrs() . . . . . . . . . . . . . . . . . . . . . 22 94 8.6. nsa_freepaddrs() . . . . . . . . . . . . . . . . . . . . 23 95 9. Miscellaneous . . . . . . . . . . . . . . . . . . . . . . . . 23 96 9.1. nsa_open() . . . . . . . . . . . . . . . . . . . . . . . 23 97 9.2. nsa_creat() . . . . . . . . . . . . . . . . . . . . . . . 23 98 9.3. nsa_pipe() . . . . . . . . . . . . . . . . . . . . . . . 24 99 9.4. nsa_ioctl() . . . . . . . . . . . . . . . . . . . . . . . 24 100 10. Code Examples . . . . . . . . . . . . . . . . . . . . . . . . 24 101 11. Testbed Platform . . . . . . . . . . . . . . . . . . . . . . 24 102 12. Security Considerations . . . . . . . . . . . . . . . . . . . 24 103 13. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 104 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 25 105 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 25 106 15.1. Normative References . . . . . . . . . . . . . . . . . . 25 107 15.2. Informative References . . . . . . . . . . . . . . . . . 25 108 15.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 26 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 27 111 1. Introduction 113 The NEAT project [9], [4], [3], [7] wants to achieve a complete 114 redesign of the way in which Internet applications interact with the 115 network. Our goal is to allow network "services" offered to 116 applications - such as reliability, low-delay communication or 117 security - to be dynamically tailored based on application demands, 118 current network conditions, hardware capabilities or local policies, 119 and also to support the integration of new network functionality in 120 an evolutionary fashion, without applications having to be rewritten. 121 This architectural change will make the Internet truly "enhanceable", 122 by allowing applications to seamlessly and more easily take advantage 123 of new network features as they evolve. 125 This document describes the NEAT Sockets API on top of the callback- 126 based NEAT Core API [9], [10], [11], [12]. It provides a BSD 127 Sockets-like API that is intended to simplify using NEAT in network 128 applications. 130 1.1. Conventions 132 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 133 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 134 document are to be interpreted as described in [1]. 136 2. Initialisation and Clean-Up 137 2.1. nsa_cleanup() 139 nsa_cleanup() is used to free all resources allocated by NEAT. Note, 140 that the NEAT Sockets API is automatically initialized when creating 141 a NEAT socket. 143 Function Prototype: 145 void nsa_cleanup() 147 2.2. nsa_map_socket() 149 nsa_map_socket() is used to map a system socket descriptor into the 150 NEAT socket descriptor space. This is useful for using NEAT API 151 functions as wrapper to calls on non-NEAT sockets. Mapped socket 152 descriptors can be unmapped by using nsa_unmap_socket(). 154 Function Prototype: 156 int nsa_map_socket(int systemSD, int neatSD) 158 Arguments: 160 systemSD: System socket descriptor. 162 neatSD: Desired NEAT socket descriptor; -1 for automatic allocation. 164 Return Value: 166 nsa_map_socket() returns the new NEAT socket descriptor, or -1 in 167 case of error. The error code will be set in the errno variable. 169 2.3. nsa_unmap_socket() 171 nsa_unmap_socket() is used to unmap a system socket descriptor from 172 the NEAT socket descriptor space. 174 Function Prototype: 176 int nsa_unmap_socket(int neatSD) 178 Arguments: 180 neatSD: NEAT socket descriptor. 182 3. Connection Establishment and Teardown 184 3.1. nsa_socket() 186 nsa_socket() creates a new NEAT socket. The NEAT socket can either 187 be a wrapper around the NEAT Core API (if properties are specified) 188 or be a wrapper around a system socket (if no properties are 189 specified). 191 Function Prototype: 193 int nsa_socket(int domain, int type, int protocol, 194 const char* properties) 196 Arguments: 198 domain: Domain for system socket (e.g. AF_INET). 200 type: Type for system socket (SOCK_SEQPACKET). 202 protocol: Protocol for system socket (IPPROTO_SCTP). 204 properties: Properties for NEAT Core socket. 206 Return Value: 208 nsa_socket() returns the NEAT socket descriptor in case of success, 209 or -1 in case of error. The error code will be set in the errno 210 variable. 212 See the socket() documentation for details. 214 3.2. nsa_close() 216 nsa_close() closes a given NEAT socket. 218 Function Prototype: 220 int nsa_close(int sockfd) 222 Arguments: 224 sockfd: NEAT socket descriptor. 226 nsa_close() returns 0 in case of success, or -1 in case of error. 227 The error code will be set in the errno variable. 229 See the close() documentation for details. 231 3.3. nsa_fcntl() 233 nsa_fcntl() manipulates a given NEAT socket. 235 Function Prototype: 237 int nsa_fcntl(int sockfd, int cmd, ...) 239 Arguments: 241 sockfd: NEAT socket descriptor. 243 cmd: Command. 245 ...: Command-specific arguments. 247 nsa_fcntl() returns a command-specific value. 249 For NEAT sockets, the following commands are specified: 251 F_GETFL: Obtain value of the socket descriptor status flags. For 252 NEAT sockets, the flag O_NONBLOCK specifies whether the socket is 253 non-blocking. By default, it is blocking (i.e. O_NONBLOCK is not 254 set). 256 F_SETFL: Set value of the socket descriptor status flags. For NEAT 257 sockets, the flag O_NONBLOCK specifies whether the socket is non- 258 blocking. By default, it is blocking (i.e. O_NONBLOCK is not 259 set). F_SETFL can then be used to change the blocking mode. 261 See the fcntl() documentation for details. 263 3.4. nsa_bind() 265 nsa_bind() binds a given NEAT socket to a given address. Note: this 266 function is provided as legacy wrapper, and it is RECOMMENDED to use 267 nsa_bindn() instead. Note further, that nsa_bind() also supports a 268 single address only (i.e. no multi-homing). nsa_bindx() SHOULD be 269 used instead to support multi-homing. 271 Function Prototype: 273 int nsa_bind(int sockfd, 274 const struct sockaddr* addr, socklen_t addrlen, 275 struct neat_tlv* opt, const int optcnt) 277 Arguments: 279 sockfd: NEAT socket descriptor. 281 addr: Address to bind to. 283 addrlen: Length of the address structure "addr". 285 opt: NEAT options (NULL, if there are none). 287 optcnt: Number of NEAT options provided by "opt". 289 nsa_bind() returns 0 in case of success, or -1 in case of error. The 290 error code will be set in the errno variable. 292 See the bind() documentation for details. 294 3.5. nsa_bindx() 296 nsa_bindx() binds a given NEAT socket to a given set of addresses. 297 Note: this function is provided as legacy wrapper, and it is 298 RECOMMENDED to use nsa_bindn() instead. 300 Function Prototype: 302 int nsa_bindx(int sockfd, const struct sockaddr* addrs, int addrcnt, 303 int flags, 304 struct neat_tlv* opt, const int optcnt) 306 Arguments: 308 sockfd: NEAT socket descriptor. 310 addrs: Addresses to bind to. 312 addrcnt: Number of addresses in "addr". 314 flags: Optional flags (0, if there are none). 316 opt: NEAT options (NULL, if there are none). 318 optcnt: Number of NEAT options provided by "opt". 320 nsa_bindx() returns 0 in case of success, or -1 in case of error. 321 The error code will be set in the errno variable. 323 See the sctp_bindx() documentation for details. 325 3.6. nsa_bindn() 327 nsa_bindn() binds a given NEAT socket to a given port. NEAT takes 328 care of handling local addresses. 330 Function Prototype: 332 int nsa_bindn(int sockfd, uint16_t port, int flags, 333 struct neat_tlv* opt, const int optcnt) 335 Arguments: 337 sockfd: NEAT socket descriptor. 339 port: Port number to bind to. 341 flags: Optional flags (0, if there are none). 343 opt: NEAT options (NULL, if there are none). 345 optcnt: Number of NEAT options provided by "opt". 347 nsa_bindn() returns 0 in case of success, or -1 in case of error. 348 The error code will be set in the errno variable. 350 3.7. nsa_connect() 352 nsa_connect() connects a given NEAT socket to a given remote address. 353 Note: this function is provided as legacy wrapper, and it is 354 RECOMMENDED to use nsa_connectn() instead. Note further, that 355 nsa_connect() also supports a single address only (i.e. no multi- 356 homing). nsa_connectx() SHOULD be used instead to support multi- 357 homing. 359 Function Prototype: 361 int nsa_connect(int sockfd, 362 const struct sockaddr* addr, socklen_t addrlen, 363 struct neat_tlv* opt, const int optcnt) 365 Arguments: 367 sockfd: NEAT socket descriptor. 369 addr: Address to connect to. 371 addrlen: Length of the address structure "addr". 373 opt: NEAT options (NULL, if there are none). 375 optcnt: Number of NEAT options provided by "opt". 377 nsa_connect() returns 0 in case of success, or -1 in case of error. 378 The error code will be set in the errno variable. 380 See the connect() documentation for details. 382 3.8. nsa_connectx() 384 nsa_connectx() connects a given NEAT socket to a given set of remote 385 addresses. Note: this function is provided as legacy wrapper, and it 386 is RECOMMENDED to use nsa_connectn() instead. 388 Function Prototype: 390 int nsa_connectx(int sockfd, 391 const struct sockaddr* addrs, int addrcnt, 392 neat_assoc_t* id, 393 struct neat_tlv* opt, const int optcnt) 395 Arguments: 397 sockfd: NEAT socket descriptor. 399 addrs: Addresses to connect to. 401 addrcnt: Number of addresses in "addr". 403 id Pointer to store association ID to (not used yet, use NULL!). 405 opt: NEAT options (NULL, if there are none). 407 optcnt: Number of NEAT options provided by "opt". 409 nsa_connectx() returns 0 in case of success, or -1 in case of error. 410 The error code will be set in the errno variable. 412 See the sctp_connectx() documentation for details. 414 3.9. nsa_connectn() 416 nsa_connectn() connects a given NEAT socket to a given remote name 417 and port. The remote name is resolved by NEAT to corresponding 418 remote addresses. 420 Function Prototype: 422 int nsa_connectn(int sockfd, const char* name, const uint16_t port, 423 neat_assoc_t* id, 424 struct neat_tlv* opt, const int optcnt) 426 Arguments: 428 sockfd: NEAT socket descriptor. 430 name: Remote name to connect to. 432 port: Remote port number to connect to. 434 id Pointer to store association ID to (not used yet, use NULL!). 436 opt: NEAT options (NULL, if there are none). 438 optcnt: Number of NEAT options provided by "opt". 440 nsa_connectn() returns 0 in case of success, or -1 in case of error. 441 The error code will be set in the errno variable. 443 3.10. nsa_listen() 445 nsa_listen() marks a given NEAT socket as listening socket, i.e. 446 accepting incoming connections. 448 Function Prototype: 450 int nsa_listen(int sockfd, int backlog) 452 Arguments: 454 sockfd: NEAT socket descriptor. 456 backlog: Defines the maximum length to which the queue of pending 457 connections for "sockfd" may grow. 459 nsa_listen() returns 0 in case of success, or -1 in case of error. 460 The error code will be set in the errno variable. 462 See the listen() documentation for details. 464 3.11. nsa_accept() 466 nsa_accept() extracts the first connection request in the queue of 467 pending connections for a listening NEAT socket, creates a new 468 connected socket, and returns a new NEAT socket descriptor referring 469 to that socket. 471 Function Prototype: 473 int nsa_accept(int sockfd, struct sockaddr* addr, socklen_t* addrlen) 475 Arguments: 477 sockfd: NEAT socket descriptor. 479 addr: Pointer to storage space to store the peer's primary address 480 to (or NULL, if address is not needed). 482 addrlen: Pointer to variable with size of the storage in "addr" (or 483 NULL, if address is not needed). 485 nsa_accept() returns the new NEAT socket descriptor in case of 486 success, or -1 in case of error. The error code will be set in the 487 errno variable. In case of success, the peer's primary address is 488 stored in "addr", if there is sufficient space. The variable pointer 489 to by "addrlen" will then contain the actual address size. 491 See the accept() documentation for details. 493 3.12. nsa_shutdown() 495 nsa_shutdown() shuts down the connection of a given NEAT socket. 497 Function Prototype: 499 int nsa_shutdown(int sockfd, int how) 501 Arguments: 503 sockfd: NEAT socket descriptor. 505 how: Not used for NEAT sockets (set to SHUT_RDWR). 507 nsa_shutdown() returns 0 in case of success, or -1 in case of error. 508 The error code will be set in the errno variable. 510 See the shutdown() documentation for details. 512 4. Options Handling 514 4.1. nsa_getsockopt() 516 nsa_getsockopt() gets a socket option of a given NEAT socket. 518 Function Prototype: 520 int nsa_getsockopt(int sockfd, int level, int optname, 521 void* optval, socklen_t* optlen) 523 Arguments: 525 sockfd: NEAT socket descriptor. 527 level: Option level. 529 optname: Option number. 531 optval: Buffer to store option value to. 533 optlen: Pointer to variable with length of the buffer in "optval". 535 nsa_getsockopt() returns 0 in case of success, or -1 in case of 536 error. The error code will be set in the errno variable. 538 See the getsockopt() documentation for details. 540 4.2. nsa_setsockopt() 542 nsa_getsockopt() sets a socket option of a given NEAT socket. 544 Function Prototype: 546 int nsa_setsockopt(int sockfd, int level, int optname, 547 const void* optval, socklen_t optlen) 549 Arguments: 551 sockfd: NEAT socket descriptor. 553 level: Option level. 555 optname: Option number. 557 optval: Buffer with option value to set. 559 optlen: Length of buffer with option value. 561 nsa_setsockopt() returns 0 in case of success, or -1 in case of 562 error. The error code will be set in the errno variable. 564 See the setsockopt() documentation for details. 566 4.3. nsa_opt_info() 568 nsa_opt_info() gets a socket option of a given NEAT socket. 570 Function Prototype: 572 int nsa_opt_info(int sockfd, neat_assoc_t id, 573 int opt, void* arg, socklen_t* size) 575 Arguments: 577 sockfd: NEAT socket descriptor. 579 id: Association identifier (0 in case of 1:1-style sockets). 581 opt: Option number. 583 arg: Buffer to store option value to. 585 size: Pointer to variable with length of the buffer in "arg". 587 nsa_opt_info() returns 0 in case of success, or -1 in case of error. 588 The error code will be set in the errno variable. 590 See the sctp_opt_info() documentation for details. 592 5. Security 594 5.1. nsa_set_secure_identity() 596 TBD. 598 5.2. ... 600 TBD. 602 6. Input/Output Handling 604 6.1. nsa_write() 606 nsa_write() sends data over a given connected NEAT socket. For NEAT 607 sockets, nsa_write() is equal to nsa_send() with "flags" set to 0. 609 Function Prototype: 611 ssize_t nsa_write(int fd, const void* buf, size_t len) 613 Arguments: 615 fd: NEAT socket descriptor. 617 buf: Data to send. 619 len: Length of data to send. 621 nsa_write() returns the number of sent bytes in case of success, or 622 -1 in case of error. The error code will be set in the errno 623 variable. 625 See the write() documentation for details. 627 6.2. nsa_send() 629 nsa_send() sends data over a given connected NEAT socket. 631 Function Prototype: 633 ssize_t nsa_send(int sockfd, const void* buf, size_t len, int flags) 635 Arguments: 637 sockfd: NEAT socket descriptor. 639 buf: Data to send. 641 len: Length of data to send. 643 flags: Optional flags (0, if there are none). 645 nsa_send() returns the number of sent bytes in case of success, or -1 646 in case of error. The error code will be set in the errno variable. 648 See the send() documentation for details. 650 6.3. nsa_sendto() 652 nsa_sendto() is a wrapper around the sendto() call, using NEAT socket 653 descriptors instead. Note: this function is provided as legacy 654 wrapper, and it is RECOMMENDED to use nsa_send() instead. On NEAT 655 sockets, a provided destination address is ignored. 657 Function Prototype: 659 ssize_t nsa_sendto(int sockfd, const void* buf, size_t len, 660 int flags, 661 const struct sockaddr* to, socklen_t tolen) 663 Arguments: 665 sockfd: NEAT socket descriptor. 667 buf: Data to send. 669 len: Length of data to send. 671 flags: Optional flags (0, if there are none). 673 to: Address to send data to (ignored for NEAT sockets). 675 tolen: Length of address to send data to (ignored for NEAT sockets). 677 nsa_sendto() returns the number of sent bytes in case of success, or 678 -1 in case of error. The error code will be set in the errno 679 variable. 681 See the send() documentation for details. 683 6.4. nsa_sendmsg() 685 nsa_sendmsg() sends data over a given connected NEAT socket. The 686 data and control information is provided by a msghdr structure. On 687 NEAT sockets, a provided destination address is ignored. 689 Function Prototype: 691 ssize_t nsa_sendmsg(int sockfd, const struct msghdr* msg, int flags) 693 Arguments: 695 sockfd: NEAT socket descriptor. 697 msg: Data to send and corresponding control information as msghdr 698 structure. 700 flags: Optional flags (0, if there are none). 702 nsa_sendmsg() returns the number of sent bytes in case of success, or 703 -1 in case of error. The error code will be set in the errno 704 variable. 706 See the sendmsg() documentation for details. 708 6.5. nsa_sendv() 710 nsa_sendv() sends data over a given connected NEAT socket. The data 711 and control information is provided by iovec and info structures. On 712 NEAT sockets, a provided destination address is ignored. 714 Function Prototype: 716 ssize_t nsa_sendv(int sockfd, struct iovec* iov, int iovcnt, 717 struct sockaddr* to, int tocnt, 718 void* info, socklen_t infolen, 719 unsigned int infotype, int flags) 721 Arguments: 723 sockfd: NEAT socket descriptor. 725 iov: Data to send provided as iovec structures. 727 iovcnt: Number of provided iovec structures. 729 to: Address(es) to send data to (ignored for NEAT sockets). 731 tocnt: Number of of addresses to send data to (ignored for NEAT 732 sockets). 734 info: Control information. 736 infolen: Length of control information. 738 infotype: Type of control information. 740 flags: Optional flags (0, if there are none). 742 nsa_sendmsg() returns the number of sent bytes in case of success, or 743 -1 in case of error. The error code will be set in the errno 744 variable. 746 See the sctp_sendv() documentation for details. 748 6.6. nsa_read() 750 nsa_read() reads data from a given connected NEAT socket. For NEAT 751 sockets, nsa_read() is equal to nsa_recv() with "flags" set to 0. 753 Function Prototype: 755 ssize_t nsa_read(int fd, void* buf, size_t len) 756 Arguments: 758 fd: NEAT socket descriptor. 760 buf: Buffer to store read data to. 762 len: Length of the storage buffer. 764 nsa_read() returns the number of read bytes in case of success, 0 in 765 case of connection shutdown, or -1 in case of error. The error code 766 will be set in the errno variable. 768 See the read() documentation for details. 770 6.7. nsa_recv() 772 nsa_recv() reads data from a given connected NEAT socket. 774 Function Prototype: 776 ssize_t nsa_recv(int sockfd, void* buf, size_t len, int flags) 778 Arguments: 780 sockfd: NEAT socket descriptor. 782 buf: Buffer to store read data to. 784 len: Length of the storage buffer. 786 flags: Optional flags (0, if there are none). 788 nsa_recv() returns the number of read bytes in case of success, 0 in 789 case of connection shutdown, or -1 in case of error. The error code 790 will be set in the errno variable. 792 See the recv() documentation for details. 794 6.8. nsa_recvfrom() 796 nsa_recvfrom() reads data from a given connected NEAT socket. The 797 peer's sending address of the data (if possible and useful for 798 underlying transport protocol) is obtained as well. Note: this 799 function is provided as legacy wrapper, and it is RECOMMENDED to use 800 nsa_recv() instead. 802 Function Prototype: 804 ssize_t nsa_recvfrom(int sockfd, void* buf, size_t len, int flags, 805 struct sockaddr* from, socklen_t* fromlen) 807 sockfd: NEAT socket descriptor. 809 buf: Buffer to store read data to. 811 len: Length of the storage buffer. 813 flags: Optional flags (0, if there are none). 815 from: Pointer to storage space to store the peer's primary address 816 to (or NULL, if address is not needed). 818 fromlen: Pointer to variable with size of the storage in "from" (or 819 NULL, if address is not needed). 821 nsa_recvfrom() returns the number of read bytes in case of success, 0 822 in case of connection shutdown, or -1 in case of error. The error 823 code will be set in the errno variable. In case of success, the 824 peer's sending address (if possible and useful for underlying 825 transport protocol) may be stored in "from", if there is sufficient 826 space. The variable pointer to by "fromlen" will then contain the 827 actual address size. 829 See the recvfrom() documentation for details. 831 6.9. nsa_recvmsg() 833 nsa_recvmsg() reads data from a given connected NEAT socket. The 834 data and control information buffers are provided by a msghdr 835 structure. 837 Function Prototype: 839 ssize_t nsa_recvmsg(int sockfd, struct msghdr* msg, int flags) 841 Arguments: 843 sockfd: NEAT socket descriptor. 845 msg: Data to send and corresponding control information as msghdr 846 structure. 848 flags: Optional flags (0, if there are none). 850 nsa_recvmsg() returns the number of read bytes in case of success, 0 851 in case of connection shutdown, or -1 in case of error. The error 852 code will be set in the errno variable. 854 See the recvmsg() documentation for details. 856 6.10. nsa_recvv() 858 nsa_recvv() reads data from a given connected NEAT socket. The data 859 and control information buffers are provided by iovec and info 860 structures. 862 Function Prototype: 864 ssize_t nsa_recvv(int sockfd, struct iovec* iov, int iovcnt, 865 struct sockaddr* from, socklen_t* fromlen, 866 void* info, socklen_t* infolen, 867 unsigned int* infotype, int* msg_flags) 869 Arguments: 871 sockfd: NEAT socket descriptor. 873 iov: Data to send provided as iovec structures. 875 iovcnt: Number of provided iovec structures. 877 from: Pointer to storage space to store the peer's primary address 878 to (or NULL, if address is not needed). 880 fromlen: Pointer to variable with size of the storage in "from" (or 881 NULL, if address is not needed). 883 info: Pointer to storage space for control information. 885 infolen: Pointer to variable with length of control information. 887 infotype: Pointer to variable for storing the control information 888 type to. 890 flags: Pointer to variable with optional flags. 892 nsa_recvv() returns the number of sent received in case of success, 893 or -1 in case of error. The error code will be set in the errno 894 variable. 896 See the sctp_recvv() documentation for details. 898 7. Poll and Select 900 7.1. nsa_poll() 902 nsa_poll() waits for activity (input/output/error/...) on a set of 903 given NEAT sockets. 905 Function Prototype: 907 int nsa_poll(struct pollfd* ufds, const nfds_t nfds, int timeout) 909 Arguments: 911 ufds: NEAT socket descriptor and requested activity for each NEAT 912 socket. 914 nfds: Number of sockets given by "ufds". 916 timeout: Timeout in milliseconds. 918 nsa_poll() returns the number of NEAT sockets with activity in case 919 of success, 0 in case of timeout, or -1 in case of error. The error 920 code will be set in the errno variable. 922 See the poll() documentation for details. 924 7.2. nsa_select() 926 nsa_select() is a wrapper around the select() call, using NEAT socket 927 descriptors instead. Note: this function is provided as legacy 928 wrapper, and it is RECOMMENDED to use nsa_poll() instead. 930 Function Prototype: 932 int nsa_select(int n, 933 fd_set* readfds, fd_set* writefds, fd_set* exceptfds, 934 struct timeval* timeout) 936 See the select() documentation for details. 938 8. Address Handling 940 8.1. nsa_getsockname() 942 nsa_getsockname() obtains the first local address of a socket. Note: 943 this function is provided as legacy wrapper, and it is RECOMMENDED to 944 use nsa_getladdrs() instead to support multi-homed transport 945 protocols! 946 Function Prototype: 948 int nsa_getsockname(int sockfd, 949 struct sockaddr* name, socklen_t* namelen) 951 Arguments: 953 sockfd: NEAT socket descriptor. 955 name: Storage space for the address. 957 namelen: Pointer to variable with the storage space's size. 959 Return Value: 961 nsa_getsockname() returns 0 in case of success (with the actual 962 address size stored into the "namelen" variable), or -1 in case of 963 error. The error code will be set in the errno variable. 965 See the getsockname() documentation for details. 967 8.2. nsa_getpeername() 969 nsa_getpeername() obtains the first remote address of a connected 970 socket. Note: this function is provided as legacy wrapper, and it is 971 RECOMMENDED to use nsa_getpaddrs() instead to support multi-homed 972 transport protocols! 974 Function Prototype: 976 int nsa_getpeername(int sockfd, 977 struct sockaddr* name, socklen_t* namelen) 979 Arguments: 981 sockfd: NEAT socket descriptor. 983 name: Storage space for the address. 985 namelen: Pointer to variable with the storage space's size. 987 Return Value: 989 nsa_getpeername() returns 0 in case of success (with the actual 990 address size stored into the "namelen" variable), or -1 in case of 991 error. The error code will be set in the errno variable. 993 See the getpeername() documentation for details. 995 8.3. nsa_getladdrs() 997 nsa_getladdrs() obtains the local addresses of a socket. The storage 998 space for the addresses will be automatically allocated and needs to 999 be freed by nsa_freeladdrs(). 1001 Function Prototype: 1003 int nsa_getladdrs(int sockfd, neat_assoc_t id, 1004 struct sockaddr** addrs) 1006 Arguments: 1008 sockfd: NEAT socket descriptor. 1010 id: Association identifier (0 in case of 1:1-style sockets). 1012 addrs: Pointer to variable to store pointer to addresses to. 1014 nsa_getladdrs() returns the number of addresses stored into a newly 1015 allocated space. The pointer to this space is stored into the 1016 variable provided by "addrs". In case of error, -1 is returned, and 1017 the error code will be set in the errno variable. 1019 8.4. nsa_freeladdrs() 1021 nsa_freeladdrs() frees addresses obtained by nsa_getladdrs(). 1023 Function Prototype: 1025 void nsa_freeladdrs(struct sockaddr* addrs) 1027 Arguments: 1029 addrs: Pointer to addresses to be freed. 1031 8.5. nsa_getpaddrs() 1033 nsa_getpaddrs() obtains the remote addresses of a connected socket. 1034 The storage space for the addresses will be automatically allocated 1035 and needs to be freed by nsa_freepaddrs(). 1037 Function Prototype: 1039 int nsa_getpaddrs(int sockfd, neat_assoc_t id, 1040 struct sockaddr** addrs) 1042 Arguments: 1044 sockfd: NEAT socket descriptor. 1046 id: Association identifier (0 in case of 1:1-style sockets). 1048 addrs: Pointer to variable to store pointer to addresses to. 1050 nsa_getpaddrs() returns the number of addresses stored into a newly 1051 allocated space. The pointer to this space is stored into the 1052 variable provided by "addrs". In case of error, -1 is returned, and 1053 the error code will be set in the errno variable. 1055 8.6. nsa_freepaddrs() 1057 nsa_freepaddrs() frees addresses obtained by nsa_getpaddrs(). 1059 Function Prototype: 1061 void nsa_freepaddrs(struct sockaddr* addrs) 1063 Arguments: 1065 addrs: Pointer to addresses to be freed. 1067 9. Miscellaneous 1069 9.1. nsa_open() 1071 nsa_open() is a wrapper around the open() call, returning a NEAT 1072 socket descriptor instead. 1074 Function Prototype: 1076 int nsa_open(const char* pathname, int flags, mode_t mode) 1078 See the open() documentation for details. 1080 9.2. nsa_creat() 1082 nsa_creat() is a wrapper around the creat() call, returning a NEAT 1083 socket descriptor instead. 1085 Function Prototype: 1087 int nsa_creat(const char* pathname, mode_t mode) 1089 See the creat() documentation for details. 1091 9.3. nsa_pipe() 1093 nsa_pipe() is a wrapper around the pipe() call, returning NEAT socket 1094 descriptors instead. 1096 Function Prototype: 1098 int nsa_pipe(int fds[2]) 1100 See the pipe() documentation for details. 1102 9.4. nsa_ioctl() 1104 nsa_ioctl() is a wrapper around the ioctl() call, using a NEAT socket 1105 descriptor instead. 1107 Function Prototype: 1109 int nsa_ioctl(int fd, int request, const void* argp) 1111 See the ioctl() documentation for details. 1113 10. Code Examples 1115 Running code examples can be found in the NEAT Git repository: 1117 URL: https://github.com/NEAT-project/neat 1119 Branch: dreibh/neat-socketapi [2] 1121 Directory: socketapi/examples/ [3] 1123 11. Testbed Platform 1125 A large-scale and realistic Internet testbed platform with support 1126 for the multi-homing feature of the underlying SCTP and MPTCP 1127 protocols is NorNet. A description of NorNet is provided in [5], 1128 [6], some further information can be found on the project website 1129 [8]. 1131 12. Security Considerations 1133 Security considerations for the SCTP sockets API are described in 1134 [2]. 1136 13. IANA Considerations 1138 This document does not require IANA actions. 1140 14. Acknowledgments 1142 The authors would like to thank (ADD NAMES HERE) for their support. 1144 15. References 1146 15.1. Normative References 1148 [1] Bradner, S., "Key words for use in RFCs to Indicate 1149 Requirement Levels", BCP 14, RFC 2119, 1150 DOI 10.17487/RFC2119, March 1997, 1151 . 1153 [2] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1154 Yasevich, "Sockets API Extensions for the Stream Control 1155 Transmission Protocol (SCTP)", RFC 6458, 1156 DOI 10.17487/RFC6458, December 2011, 1157 . 1159 [3] Gjessing, S. and M. Welzl, "A Minimal Set of Transport 1160 Services for TAPS Systems", draft-gjessing-taps-minset-04 1161 (work in progress), March 2017. 1163 [4] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 1164 Transport Features Provided by IETF Transport Protocols", 1165 draft-ietf-taps-transports-usage-04 (work in progress), 1166 April 2017. 1168 15.2. Informative References 1170 [5] Dreibholz, T., "NorNet - Building an Inter-Continental 1171 Internet Testbed based on Open Source Software", 1172 Proceedings of the LinuxCon Europe, October 2016, 1173 . 1176 [6] Gran, E., Dreibholz, T., and A. Kvalbein, "NorNet Core - A 1177 Multi-Homed Research Testbed", Computer Networks, Special 1178 Issue on Future Internet Testbeds Volume 61, Pages 75-87, 1179 ISSN 1389-1286, DOI 10.1016/j.bjp.2013.12.035, March 2014, 1180 . 1182 [7] Dreibholz, T., "NEAT - A New, Evolutive API and Transport- 1183 Layer Architecture for the Internet", Online: 1184 https://www.neat-project.org/, 2017, . 1187 [8] Dreibholz, T., "NorNet - A Real-World, Large-Scale Multi- 1188 Homing Testbed", Online: https://www.nntb.no/, 2017, 1189 . 1191 [9] Fairhurst, G., Jones, T., Bozakov, Z., Brunstroem, A., 1192 Damjanović, D., Eckert, K., Grinnemo, K., Hansen, A., 1193 Khademi, N., Mangiante, S., McManus, P., Papastergiou, G., 1194 Ros, D., Tuexen, M., Vyncke, E., and M. Welzl, "NEAT 1195 Architecture", Number D1.1, December 2015, 1196 . 1199 [10] Welzl, M., Brunstroem, A., Damjanović, D., Evensen, 1200 K., Eckert, T., Fairhurst, G., Khademi, N., Mangiante, S., 1201 Petlund, A., Ros, D., and M. Tuexen, "NEAT - First Version 1202 of Services and APIs", Number D1.2, March 2016, 1203 . 1206 [11] Khademi, N., Bozakov, Z., Brunstroem, A., Damjanović, 1207 D., Evensen, K., Fairhurst, G., Grinnemo, K., Jones, T., 1208 Mangiante, S., Papastergiou, G., Ros, D., Tuexen, M., and 1209 M. Welzl, "NEAT - First Version of Low-Level Core 1210 Transport System", Number D2.1, March 2016, 1211 . 1214 [12] Khademi, N., Bozakov, Z., Brunstroem, A., Dale, Oe., 1215 Damjanović, D., Evensen, K., Fairhurst, G., Grinnemo, 1216 K., Jones, T., Mangiante, S., Petlund, A., Ros, D., 1217 Stenberg, D., Tuexen, M., Weinrank, F., and M. Welzl, 1218 "NEAT - Core Transport System, with both Low-level and 1219 High-level Components", Number D2.2, March 2017, 1220 . 1223 15.3. URIs 1225 [2] https://github.com/NEAT-project/neat/tree/dreibh/neat-socketapi 1227 [3] https://github.com/NEAT-project/neat/tree/dreibh/neat- 1228 socketapi/socketapi/examples 1230 Author's Address 1232 Thomas Dreibholz 1233 Simula Research Laboratory, Network Systems Group 1234 Martin Linges vei 17 1235 1364 Fornebu, Akershus 1236 Norway 1238 Phone: +47-6782-8200 1239 Fax: +47-6782-8201 1240 Email: dreibh@simula.no 1241 URI: https://simula.no/people/dreibh