idnits 2.17.1 draft-dreibholz-taps-neat-socketapi-01.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 (July 04, 2017) is 2487 days in the past. Is this intentional? Checking references for intended status: Experimental ---------------------------------------------------------------------------- == Outdated reference: A later version (-09) exists of draft-ietf-taps-transports-usage-06 Summary: 0 errors (**), 0 flaws (~~), 2 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 July 04, 2017 5 Expires: January 5, 2018 7 NEAT Sockets API 8 draft-dreibholz-taps-neat-socketapi-01.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 January 5, 2018. 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() . . . . . . . . . . . . . . . . . . . . . . 3 52 2.2. nsa_map_socket() . . . . . . . . . . . . . . . . . . . . 4 53 2.3. nsa_unmap_socket() . . . . . . . . . . . . . . . . . . . 4 54 3. Connection Establishment and Teardown . . . . . . . . . . . . 4 55 3.1. nsa_socket() . . . . . . . . . . . . . . . . . . . . . . 4 56 3.2. nsa_close() . . . . . . . . . . . . . . . . . . . . . . . 5 57 3.3. nsa_fcntl() . . . . . . . . . . . . . . . . . . . . . . . 5 58 3.4. nsa_bind() . . . . . . . . . . . . . . . . . . . . . . . 6 59 3.5. nsa_bindx() . . . . . . . . . . . . . . . . . . . . . . . 7 60 3.6. nsa_bindn() . . . . . . . . . . . . . . . . . . . . . . . 7 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() . . . . . . . . . . . . . . . . . . . . . 12 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() . . . . . . . . . . . . . . . . . . . . . . . 15 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() . . . . . . . . . . . . . . . . . . . . . . . 18 85 7. Poll and Select . . . . . . . . . . . . . . . . . . . . . . . 19 86 7.1. nsa_poll() . . . . . . . . . . . . . . . . . . . . . . . 19 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() . . . . . . . . . . . . . . . . . . . . . 21 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() . . . . . . . . . . . . . . . . . . . . . . . 23 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 . . . . . . . . . . . . . . . . . . . . . 24 104 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 105 15. References . . . . . . . . . . . . . . . . . . . . . . . . . 24 106 15.1. Normative References . . . . . . . . . . . . . . . . . . 25 107 15.2. Informative References . . . . . . . . . . . . . . . . . 25 108 15.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 26 109 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 26 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. 122 This document describes the NEAT Sockets API on top of the callback- 123 based NEAT Core API [9], [10], [11], [12]. It provides a BSD 124 Sockets-like API that facilitates porting existing applications to 125 use a subset of NEAT's functionality. 127 1.1. Conventions 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [1]. 133 2. Initialisation and Clean-Up 135 2.1. nsa_cleanup() 137 nsa_cleanup() is used to free all resources allocated by NEAT. Note, 138 that the NEAT Sockets API is automatically initialized when creating 139 a NEAT socket. 141 Function Prototype: 143 void nsa_cleanup() 145 2.2. nsa_map_socket() 147 nsa_map_socket() is used to map a system socket descriptor into the 148 NEAT socket descriptor space. This is useful for using NEAT API 149 functions as wrapper to calls on non-NEAT sockets. Mapped socket 150 descriptors can be unmapped by using nsa_unmap_socket(). 152 Function Prototype: 154 int nsa_map_socket(int systemSD, int neatSD) 156 Arguments: 158 systemSD: System socket descriptor. 160 neatSD: Desired NEAT socket descriptor; -1 for automatic allocation. 162 Return Value: 164 nsa_map_socket() returns the new NEAT socket descriptor, or -1 in 165 case of error. The error code will be set in the errno variable. 167 2.3. nsa_unmap_socket() 169 nsa_unmap_socket() is used to unmap a system socket descriptor from 170 the NEAT socket descriptor space. 172 Function Prototype: 174 int nsa_unmap_socket(int neatSD) 176 Arguments: 178 neatSD: NEAT socket descriptor. 180 3. Connection Establishment and Teardown 182 3.1. nsa_socket() 184 nsa_socket() creates a new NEAT socket. The NEAT socket can either 185 be a wrapper around the NEAT Core API (if properties are specified) 186 or be a wrapper around a system socket (if no properties are 187 specified). 189 Function Prototype: 191 int nsa_socket(int domain, int type, int protocol, 192 const char* properties) 194 Arguments: 196 domain: Domain for system socket (e.g. AF_INET). 198 type: Type for system socket (SOCK_SEQPACKET). 200 protocol: Protocol for system socket (IPPROTO_SCTP). 202 properties: Properties for NEAT Core socket. 204 Return Value: 206 nsa_socket() returns the NEAT socket descriptor in case of success, 207 or -1 in case of error. The error code will be set in the errno 208 variable. 210 See the socket() documentation for details. 212 3.2. nsa_close() 214 nsa_close() closes a given NEAT socket. 216 Function Prototype: 218 int nsa_close(int sockfd) 220 Arguments: 222 sockfd: NEAT socket descriptor. 224 nsa_close() returns 0 in case of success, or -1 in case of error. 225 The error code will be set in the errno variable. 227 See the close() documentation for details. 229 3.3. nsa_fcntl() 231 nsa_fcntl() manipulates a given NEAT socket. 233 Function Prototype: 235 int nsa_fcntl(int sockfd, int cmd, ...) 237 Arguments: 239 sockfd: NEAT socket descriptor. 241 cmd: Command. 243 ...: Command-specific arguments. 245 nsa_fcntl() returns a command-specific value. 247 For NEAT sockets, the following commands are specified: 249 F_GETFL: Obtain value of the socket descriptor status flags. For 250 NEAT sockets, the flag O_NONBLOCK specifies whether the socket is 251 non-blocking. By default, it is blocking (i.e. O_NONBLOCK is not 252 set). 254 F_SETFL: Set value of the socket descriptor status flags. For NEAT 255 sockets, the flag O_NONBLOCK specifies whether the socket is non- 256 blocking. By default, it is blocking (i.e. O_NONBLOCK is not 257 set). F_SETFL can then be used to change the blocking mode. 259 See the fcntl() documentation for details. 261 3.4. nsa_bind() 263 nsa_bind() binds a given NEAT socket to a given address. Note: this 264 function is provided as legacy wrapper, and it is RECOMMENDED to use 265 nsa_bindn() instead. Note further, that nsa_bind() also supports a 266 single address only (i.e. no multi-homing). nsa_bindx() SHOULD be 267 used instead to support multi-homing. 269 Function Prototype: 271 int nsa_bind(int sockfd, 272 const struct sockaddr* addr, socklen_t addrlen, 273 struct neat_tlv* opt, const int optcnt) 275 Arguments: 277 sockfd: NEAT socket descriptor. 279 addr: Address to bind to. 281 addrlen: Length of the address structure "addr". 283 opt: NEAT options (NULL, if there are none). 285 optcnt: Number of NEAT options provided by "opt". 287 nsa_bind() returns 0 in case of success, or -1 in case of error. The 288 error code will be set in the errno variable. 290 See the bind() documentation for details. 292 3.5. nsa_bindx() 294 nsa_bindx() binds a given NEAT socket to a given set of addresses. 295 Note: this function is provided as legacy wrapper, and it is 296 RECOMMENDED to use nsa_bindn() instead. 298 Function Prototype: 300 int nsa_bindx(int sockfd, const struct sockaddr* addrs, int addrcnt, 301 int flags, 302 struct neat_tlv* opt, const int optcnt) 304 Arguments: 306 sockfd: NEAT socket descriptor. 308 addrs: Addresses to bind to. 310 addrcnt: Number of addresses in "addr". 312 flags: Optional flags (0, if there are none). 314 opt: NEAT options (NULL, if there are none). 316 optcnt: Number of NEAT options provided by "opt". 318 nsa_bindx() returns 0 in case of success, or -1 in case of error. 319 The error code will be set in the errno variable. 321 See the sctp_bindx() documentation for details. 323 3.6. nsa_bindn() 325 nsa_bindn() binds a given NEAT socket to a given port. NEAT takes 326 care of handling local addresses. 328 Function Prototype: 330 int nsa_bindn(int sockfd, uint16_t port, int flags, 331 struct neat_tlv* opt, const int optcnt) 333 Arguments: 335 sockfd: NEAT socket descriptor. 337 port: Port number to bind to. 339 flags: Optional flags (0, if there are none). 341 opt: NEAT options (NULL, if there are none). 343 optcnt: Number of NEAT options provided by "opt". 345 nsa_bindn() returns 0 in case of success, or -1 in case of error. 346 The error code will be set in the errno variable. 348 3.7. nsa_connect() 350 nsa_connect() connects a given NEAT socket to a given remote address. 351 Note: this function is provided as legacy wrapper, and it is 352 RECOMMENDED to use nsa_connectn() instead. Note further, that 353 nsa_connect() also supports a single address only (i.e. no multi- 354 homing). nsa_connectx() SHOULD be used instead to support multi- 355 homing. 357 Function Prototype: 359 int nsa_connect(int sockfd, 360 const struct sockaddr* addr, socklen_t addrlen, 361 struct neat_tlv* opt, const int optcnt) 363 Arguments: 365 sockfd: NEAT socket descriptor. 367 addr: Address to connect to. 369 addrlen: Length of the address structure "addr". 371 opt: NEAT options (NULL, if there are none). 373 optcnt: Number of NEAT options provided by "opt". 375 nsa_connect() returns 0 in case of success, or -1 in case of error. 376 The error code will be set in the errno variable. 378 See the connect() documentation for details. 380 3.8. nsa_connectx() 382 nsa_connectx() connects a given NEAT socket to a given set of remote 383 addresses. Note: this function is provided as legacy wrapper, and it 384 is RECOMMENDED to use nsa_connectn() instead. 386 Function Prototype: 388 int nsa_connectx(int sockfd, 389 const struct sockaddr* addrs, int addrcnt, 390 neat_assoc_t* id, 391 struct neat_tlv* opt, const int optcnt) 393 Arguments: 395 sockfd: NEAT socket descriptor. 397 addrs: Addresses to connect to. 399 addrcnt: Number of addresses in "addr". 401 id Pointer to store association ID to (not used yet, use NULL!). 403 opt: NEAT options (NULL, if there are none). 405 optcnt: Number of NEAT options provided by "opt". 407 nsa_connectx() returns 0 in case of success, or -1 in case of error. 408 The error code will be set in the errno variable. 410 See the sctp_connectx() documentation for details. 412 3.9. nsa_connectn() 414 nsa_connectn() connects a given NEAT socket to a given remote name 415 and port. The remote name is resolved by NEAT to corresponding 416 remote addresses. 418 Function Prototype: 420 int nsa_connectn(int sockfd, const char* name, const uint16_t port, 421 neat_assoc_t* id, 422 struct neat_tlv* opt, const int optcnt) 424 Arguments: 426 sockfd: NEAT socket descriptor. 428 name: Remote name to connect to. 430 port: Remote port number to connect to. 432 id Pointer to store association ID to (not used yet, use NULL!). 434 opt: NEAT options (NULL, if there are none). 436 optcnt: Number of NEAT options provided by "opt". 438 nsa_connectn() returns 0 in case of success, or -1 in case of error. 439 The error code will be set in the errno variable. 441 3.10. nsa_listen() 443 nsa_listen() marks a given NEAT socket as listening socket, i.e. 444 accepting incoming connections. 446 Function Prototype: 448 int nsa_listen(int sockfd, int backlog) 450 Arguments: 452 sockfd: NEAT socket descriptor. 454 backlog: Defines the maximum length to which the queue of pending 455 connections for "sockfd" may grow. 457 nsa_listen() returns 0 in case of success, or -1 in case of error. 458 The error code will be set in the errno variable. 460 See the listen() documentation for details. 462 3.11. nsa_accept() 464 nsa_accept() extracts the first connection request in the queue of 465 pending connections for a listening NEAT socket, creates a new 466 connected socket, and returns a new NEAT socket descriptor referring 467 to that socket. 469 Function Prototype: 471 int nsa_accept(int sockfd, struct sockaddr* addr, socklen_t* addrlen) 473 Arguments: 475 sockfd: NEAT socket descriptor. 477 addr: Pointer to storage space to store the peer's primary address 478 to (or NULL, if address is not needed). 480 addrlen: Pointer to variable with size of the storage in "addr" (or 481 NULL, if address is not needed). 483 nsa_accept() returns the new NEAT socket descriptor in case of 484 success, or -1 in case of error. The error code will be set in the 485 errno variable. In case of success, the peer's primary address is 486 stored in "addr", if there is sufficient space. The variable pointer 487 to by "addrlen" will then contain the actual address size. 489 See the accept() documentation for details. 491 3.12. nsa_shutdown() 493 nsa_shutdown() shuts down the connection of a given NEAT socket. 495 Function Prototype: 497 int nsa_shutdown(int sockfd, int how) 499 Arguments: 501 sockfd: NEAT socket descriptor. 503 how: Not used for NEAT sockets (set to SHUT_RDWR). 505 nsa_shutdown() returns 0 in case of success, or -1 in case of error. 506 The error code will be set in the errno variable. 508 See the shutdown() documentation for details. 510 4. Options Handling 512 4.1. nsa_getsockopt() 514 nsa_getsockopt() gets a socket option of a given NEAT socket. 516 Function Prototype: 518 int nsa_getsockopt(int sockfd, int level, int optname, 519 void* optval, socklen_t* optlen) 521 Arguments: 523 sockfd: NEAT socket descriptor. 525 level: Option level. 527 optname: Option number. 529 optval: Buffer to store option value to. 531 optlen: Pointer to variable with length of the buffer in "optval". 533 nsa_getsockopt() returns 0 in case of success, or -1 in case of 534 error. The error code will be set in the errno variable. 536 See the getsockopt() documentation for details. 538 4.2. nsa_setsockopt() 540 nsa_getsockopt() sets a socket option of a given NEAT socket. 542 Function Prototype: 544 int nsa_setsockopt(int sockfd, int level, int optname, 545 const void* optval, socklen_t optlen) 547 Arguments: 549 sockfd: NEAT socket descriptor. 551 level: Option level. 553 optname: Option number. 555 optval: Buffer with option value to set. 557 optlen: Length of buffer with option value. 559 nsa_setsockopt() returns 0 in case of success, or -1 in case of 560 error. The error code will be set in the errno variable. 562 See the setsockopt() documentation for details. 564 4.3. nsa_opt_info() 566 nsa_opt_info() gets a socket option of a given NEAT socket. 568 Function Prototype: 570 int nsa_opt_info(int sockfd, neat_assoc_t id, 571 int opt, void* arg, socklen_t* size) 573 Arguments: 575 sockfd: NEAT socket descriptor. 577 id: Association identifier (0 in case of 1:1-style sockets). 579 opt: Option number. 581 arg: Buffer to store option value to. 583 size: Pointer to variable with length of the buffer in "arg". 585 nsa_opt_info() returns 0 in case of success, or -1 in case of error. 586 The error code will be set in the errno variable. 588 See the sctp_opt_info() documentation for details. 590 5. Security 592 5.1. nsa_set_secure_identity() 594 TBD. 596 5.2. ... 598 TBD. 600 6. Input/Output Handling 602 6.1. nsa_write() 604 nsa_write() sends data over a given connected NEAT socket. For NEAT 605 sockets, nsa_write() is equal to nsa_send() with "flags" set to 0. 607 Function Prototype: 609 ssize_t nsa_write(int fd, const void* buf, size_t len) 611 Arguments: 613 fd: NEAT socket descriptor. 615 buf: Data to send. 617 len: Length of data to send. 619 nsa_write() returns the number of sent bytes in case of success, or 620 -1 in case of error. The error code will be set in the errno 621 variable. 623 See the write() documentation for details. 625 6.2. nsa_send() 627 nsa_send() sends data over a given connected NEAT socket. 629 Function Prototype: 631 ssize_t nsa_send(int sockfd, const void* buf, size_t len, int flags) 633 Arguments: 635 sockfd: NEAT socket descriptor. 637 buf: Data to send. 639 len: Length of data to send. 641 flags: Optional flags (0, if there are none). 643 nsa_send() returns the number of sent bytes in case of success, or -1 644 in case of error. The error code will be set in the errno variable. 646 See the send() documentation for details. 648 6.3. nsa_sendto() 650 nsa_sendto() is a wrapper around the sendto() call, using NEAT socket 651 descriptors instead. Note: this function is provided as legacy 652 wrapper, and it is RECOMMENDED to use nsa_send() instead. On NEAT 653 sockets, a provided destination address is ignored. 655 Function Prototype: 657 ssize_t nsa_sendto(int sockfd, const void* buf, size_t len, 658 int flags, 659 const struct sockaddr* to, socklen_t tolen) 661 Arguments: 663 sockfd: NEAT socket descriptor. 665 buf: Data to send. 667 len: Length of data to send. 669 flags: Optional flags (0, if there are none). 671 to: Address to send data to (ignored for NEAT sockets). 673 tolen: Length of address to send data to (ignored for NEAT sockets). 675 nsa_sendto() returns the number of sent bytes in case of success, or 676 -1 in case of error. The error code will be set in the errno 677 variable. 679 See the send() documentation for details. 681 6.4. nsa_sendmsg() 683 nsa_sendmsg() sends data over a given connected NEAT socket. The 684 data and control information is provided by a msghdr structure. On 685 NEAT sockets, a provided destination address is ignored. 687 Function Prototype: 689 ssize_t nsa_sendmsg(int sockfd, const struct msghdr* msg, int flags) 691 Arguments: 693 sockfd: NEAT socket descriptor. 695 msg: Data to send and corresponding control information as msghdr 696 structure. 698 flags: Optional flags (0, if there are none). 700 nsa_sendmsg() returns the number of sent bytes in case of success, or 701 -1 in case of error. The error code will be set in the errno 702 variable. 704 See the sendmsg() documentation for details. 706 6.5. nsa_sendv() 708 nsa_sendv() sends data over a given connected NEAT socket. The data 709 and control information is provided by iovec and info structures. On 710 NEAT sockets, a provided destination address is ignored. 712 Function Prototype: 714 ssize_t nsa_sendv(int sockfd, struct iovec* iov, int iovcnt, 715 struct sockaddr* to, int tocnt, 716 void* info, socklen_t infolen, 717 unsigned int infotype, int flags) 719 Arguments: 721 sockfd: NEAT socket descriptor. 723 iov: Data to send provided as iovec structures. 725 iovcnt: Number of provided iovec structures. 727 to: Address(es) to send data to (ignored for NEAT sockets). 729 tocnt: Number of of addresses to send data to (ignored for NEAT 730 sockets). 732 info: Control information. 734 infolen: Length of control information. 736 infotype: Type of control information. 738 flags: Optional flags (0, if there are none). 740 nsa_sendmsg() returns the number of sent bytes in case of success, or 741 -1 in case of error. The error code will be set in the errno 742 variable. 744 See the sctp_sendv() documentation for details. 746 6.6. nsa_read() 748 nsa_read() reads data from a given connected NEAT socket. For NEAT 749 sockets, nsa_read() is equal to nsa_recv() with "flags" set to 0. 751 Function Prototype: 753 ssize_t nsa_read(int fd, void* buf, size_t len) 755 Arguments: 757 fd: NEAT socket descriptor. 759 buf: Buffer to store read data to. 761 len: Length of the storage buffer. 763 nsa_read() returns the number of read bytes in case of success, 0 in 764 case of connection shutdown, or -1 in case of error. The error code 765 will be set in the errno variable. 767 See the read() documentation for details. 769 6.7. nsa_recv() 771 nsa_recv() reads data from a given connected NEAT socket. 773 Function Prototype: 775 ssize_t nsa_recv(int sockfd, void* buf, size_t len, int flags) 777 Arguments: 779 sockfd: NEAT socket descriptor. 781 buf: Buffer to store read data to. 783 len: Length of the storage buffer. 785 flags: Optional flags (0, if there are none). 787 nsa_recv() returns the number of read bytes in case of success, 0 in 788 case of connection shutdown, or -1 in case of error. The error code 789 will be set in the errno variable. 791 See the recv() documentation for details. 793 6.8. nsa_recvfrom() 795 nsa_recvfrom() reads data from a given connected NEAT socket. The 796 peer's sending address of the data (if possible and useful for 797 underlying transport protocol) is obtained as well. Note: this 798 function is provided as legacy wrapper, and it is RECOMMENDED to use 799 nsa_recv() instead. 801 Function Prototype: 803 ssize_t nsa_recvfrom(int sockfd, void* buf, size_t len, int flags, 804 struct sockaddr* from, socklen_t* fromlen) 806 sockfd: NEAT socket descriptor. 808 buf: Buffer to store read data to. 810 len: Length of the storage buffer. 812 flags: Optional flags (0, if there are none). 814 from: Pointer to storage space to store the peer's primary address 815 to (or NULL, if address is not needed). 817 fromlen: Pointer to variable with size of the storage in "from" (or 818 NULL, if address is not needed). 820 nsa_recvfrom() returns the number of read bytes in case of success, 0 821 in case of connection shutdown, or -1 in case of error. The error 822 code will be set in the errno variable. In case of success, the 823 peer's sending address (if possible and useful for underlying 824 transport protocol) may be stored in "from", if there is sufficient 825 space. The variable pointer to by "fromlen" will then contain the 826 actual address size. 828 See the recvfrom() documentation for details. 830 6.9. nsa_recvmsg() 832 nsa_recvmsg() reads data from a given connected NEAT socket. The 833 data and control information buffers are provided by a msghdr 834 structure. 836 Function Prototype: 838 ssize_t nsa_recvmsg(int sockfd, struct msghdr* msg, int flags) 840 Arguments: 842 sockfd: NEAT socket descriptor. 844 msg: Data to send and corresponding control information as msghdr 845 structure. 847 flags: Optional flags (0, if there are none). 849 nsa_recvmsg() returns the number of read bytes in case of success, 0 850 in case of connection shutdown, or -1 in case of error. The error 851 code will be set in the errno variable. 853 See the recvmsg() documentation for details. 855 6.10. nsa_recvv() 857 nsa_recvv() reads data from a given connected NEAT socket. The data 858 and control information buffers are provided by iovec and info 859 structures. 861 Function Prototype: 863 ssize_t nsa_recvv(int sockfd, struct iovec* iov, int iovcnt, 864 struct sockaddr* from, socklen_t* fromlen, 865 void* info, socklen_t* infolen, 866 unsigned int* infotype, int* msg_flags) 868 Arguments: 870 sockfd: NEAT socket descriptor. 872 iov: Data to send provided as iovec structures. 874 iovcnt: Number of provided iovec structures. 876 from: Pointer to storage space to store the peer's primary address 877 to (or NULL, if address is not needed). 879 fromlen: Pointer to variable with size of the storage in "from" (or 880 NULL, if address is not needed). 882 info: Pointer to storage space for control information. 884 infolen: Pointer to variable with length of control information. 886 infotype: Pointer to variable for storing the control information 887 type to. 889 flags: Pointer to variable with optional flags. 891 nsa_recvv() returns the number of sent received in case of success, 892 or -1 in case of error. The error code will be set in the errno 893 variable. 895 See the sctp_recvv() documentation for details. 897 7. Poll and Select 899 7.1. nsa_poll() 901 nsa_poll() waits for activity (input/output/error/...) on a set of 902 given NEAT sockets. 904 Function Prototype: 906 int nsa_poll(struct pollfd* ufds, const nfds_t nfds, int timeout) 908 Arguments: 910 ufds: NEAT socket descriptor and requested activity for each NEAT 911 socket. 913 nfds: Number of sockets given by "ufds". 915 timeout: Timeout in milliseconds. 917 nsa_poll() returns the number of NEAT sockets with activity in case 918 of success, 0 in case of timeout, or -1 in case of error. The error 919 code will be set in the errno variable. 921 See the poll() documentation for details. 923 7.2. nsa_select() 925 nsa_select() is a wrapper around the select() call, using NEAT socket 926 descriptors instead. Note: this function is provided as legacy 927 wrapper, and it is RECOMMENDED to use nsa_poll() instead. 929 Function Prototype: 931 int nsa_select(int n, 932 fd_set* readfds, fd_set* writefds, fd_set* exceptfds, 933 struct timeval* timeout) 935 See the select() documentation for details. 937 8. Address Handling 939 8.1. nsa_getsockname() 941 nsa_getsockname() obtains the first local address of a socket. Note: 942 this function is provided as legacy wrapper, and it is RECOMMENDED to 943 use nsa_getladdrs() instead to support multi-homed transport 944 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 1145 15.1. Normative References 1147 [1] Bradner, S., "Key words for use in RFCs to Indicate 1148 Requirement Levels", BCP 14, RFC 2119, 1149 DOI 10.17487/RFC2119, March 1997, 1150 . 1152 [2] Stewart, R., Tuexen, M., Poon, K., Lei, P., and V. 1153 Yasevich, "Sockets API Extensions for the Stream Control 1154 Transmission Protocol (SCTP)", RFC 6458, 1155 DOI 10.17487/RFC6458, December 2011, 1156 . 1158 [3] Gjessing, S. and M. Welzl, "A Minimal Set of Transport 1159 Services for TAPS Systems", draft-gjessing-taps-minset-05 1160 (work in progress), June 2017. 1162 [4] Welzl, M., Tuexen, M., and N. Khademi, "On the Usage of 1163 Transport Features Provided by IETF Transport Protocols", 1164 draft-ietf-taps-transports-usage-06 (work in progress), 1165 June 2017. 1167 15.2. Informative References 1169 [5] Dreibholz, T., "NorNet - Building an Inter-Continental 1170 Internet Testbed based on Open Source Software", 1171 Proceedings of the LinuxCon Europe, October 2016, 1172 . 1175 [6] Gran, E., Dreibholz, T., and A. Kvalbein, "NorNet Core - A 1176 Multi-Homed Research Testbed", Computer Networks, Special 1177 Issue on Future Internet Testbeds Volume 61, Pages 75-87, 1178 ISSN 1389-1286, DOI 10.1016/j.bjp.2013.12.035, March 2014, 1179 . 1181 [7] Dreibholz, T., "NEAT - A New, Evolutive API and Transport- 1182 Layer Architecture for the Internet", Online: 1183 https://www.neat-project.org/, 2017, . 1186 [8] Dreibholz, T., "NorNet - A Real-World, Large-Scale Multi- 1187 Homing Testbed", Online: https://www.nntb.no/, 2017, 1188 . 1190 [9] Fairhurst, G., Jones, T., Bozakov, Z., Brunstroem, A., 1191 Damjanović, D., Eckert, K., Grinnemo, K., Hansen, A., 1192 Khademi, N., Mangiante, S., McManus, P., Papastergiou, G., 1193 Ros, D., Tuexen, M., Vyncke, E., and M. Welzl, "NEAT 1194 Architecture", Number D1.1, December 2015, 1195 . 1198 [10] Welzl, M., Brunstroem, A., Damjanović, D., Evensen, 1199 K., Eckert, T., Fairhurst, G., Khademi, N., Mangiante, S., 1200 Petlund, A., Ros, D., and M. Tuexen, "NEAT - First Version 1201 of Services and APIs", Number D1.2, March 2016, 1202 . 1205 [11] Khademi, N., Bozakov, Z., Brunstroem, A., Damjanović, 1206 D., Evensen, K., Fairhurst, G., Grinnemo, K., Jones, T., 1207 Mangiante, S., Papastergiou, G., Ros, D., Tuexen, M., and 1208 M. Welzl, "NEAT - First Version of Low-Level Core 1209 Transport System", Number D2.1, March 2016, 1210 . 1213 [12] Khademi, N., Bozakov, Z., Brunstroem, A., Dale, Oe., 1214 Damjanović, D., Evensen, K., Fairhurst, G., Grinnemo, 1215 K., Jones, T., Mangiante, S., Petlund, A., Ros, D., 1216 Stenberg, D., Tuexen, M., Weinrank, F., and M. Welzl, 1217 "NEAT - Core Transport System, with both Low-level and 1218 High-level Components", Number D2.2, March 2017, 1219 . 1222 15.3. URIs 1224 [2] https://github.com/NEAT-project/neat/tree/dreibh/neat-socketapi 1226 [3] https://github.com/NEAT-project/neat/tree/dreibh/neat- 1227 socketapi/socketapi/examples 1229 Author's Address 1230 Thomas Dreibholz 1231 Simula Research Laboratory, Network Systems Group 1232 Martin Linges vei 17 1233 1364 Fornebu, Akershus 1234 Norway 1236 Phone: +47-6782-8200 1237 Fax: +47-6782-8201 1238 Email: dreibh@simula.no 1239 URI: https://simula.no/people/dreibh