Transport Interfaces Programming Guide Sun Microsystems, Inc. 901 San Antonio Road Palo Alto, CA 94043-1100 U.S.A. Part No: 805–4041–10 October 1998 Copyright 1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California 94303-4900 U.S.A. All rights reserved. This product or document is protected by copyright and distributed under licenses restricting its use, copying, distribution, and decompilation. No part of this product or document may be reproduced in any form by any means without prior written authorization of Sun and its licensors, if any. Third-party software, including font technology, is copyrighted and licensed from Sun suppliers. Parts of the product may be derived from Berkeley BSD systems, licensed from the University of California. UNIX is a registered trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. Sun, Sun Microsystems, the Sun logo, SunDocs, Java, the Java Coffee Cup logo, and Solaris are trademarks, registered trademarks, or service marks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries. Products bearing SPARC trademarks are based upon an architecture developed by Sun Microsystems, Inc. The OPEN LOOK and SunTM Graphical User Interface was developed by Sun Microsystems, Inc. for its users and licensees. Sun acknowledges the pioneering efforts of Xerox in researching and developing the concept of visual or graphical user interfaces for the computer industry. Sun holds a non-exclusive license from Xerox to the Xerox Graphical User Interface, which license also covers Sun’s licensees who implement OPEN LOOK GUIs and otherwise comply with Sun’s written license agreements. RESTRICTED RIGHTS: Use, duplication, or disclosure by the U.S. Government is subject to restrictions of FAR 52.227–14(g)(2)(6/87) and FAR 52.227–19(6/87), or DFAR 252.227–7015(b)(6/95) and DFAR 227.7202–3(a). DOCUMENTATION IS PROVIDED “AS IS” AND ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT, ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT SUCH DISCLAIMERS ARE HELD TO BE LEGALLY INVALID. Copyright 1998 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, Californie 94303-4900 Etats-Unis. Tous droits réservés. Ce produit ou document est protégé par un copyright et distribué avec des licences qui en restreignent l’utilisation, la copie, la distribution, et la décompilation. Aucune partie de ce produit ou document ne peut être reproduite sous aucune forme, par quelque moyen que ce soit, sans l’autorisation préalable et écrite de Sun et de ses bailleurs de licence, s’il y en a. Le logiciel détenu par des tiers, et qui comprend la technologie relative aux polices de caractères, est protégé par un copyright et licencié par des fournisseurs de Sun. Des parties de ce produit pourront être dérivées du système Berkeley BSD licenciés par l’Université de Californie. UNIX est une marque déposée aux Etats-Unis et dans d’autres pays et licenciée exclusivement par X/Open Company, Ltd. Sun, Sun Microsystems, le logo Sun, SunDocs, Java, le logo Java Coffee Cup, et Solaris sont des marques de fabrique ou des marques déposées, ou marques de service, de Sun Microsystems, Inc. aux Etats-Unis et dans d’autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées de SPARC International, Inc. aux Etats-Unis et dans d’autres pays. Les produits portant les marques SPARC sont basés sur une architecture développée par Sun Microsystems, Inc. L’interface d’utilisation graphique OPEN LOOK et SunTM a été développée par Sun Microsystems, Inc. pour ses utilisateurs et licenciés. Sun reconnaît les efforts de pionniers de Xerox pour la recherche et le développement du concept des interfaces d’utilisation visuelle ou graphique pour l’industrie de l’informatique. Sun détient une licence non exclusive de Xerox sur l’interface d’utilisation graphique Xerox, cette licence couvrant également les licenciés de Sun qui mettent en place l’interface d’utilisation graphique OPEN LOOK et qui en outre se conforment aux licences écrites de Sun. CETTE PUBLICATION EST FOURNIE “EN L’ETAT” ET AUCUNE GARANTIE, EXPRESSE OU IMPLICITE, N’EST ACCORDEE, Y COMPRIS DES GARANTIES CONCERNANT LA VALEUR MARCHANDE, L’APTITUDE DE LA PUBLICATION A REPONDRE A UNE UTILISATION PARTICULIERE, OU LE FAIT QU’ELLE NE SOIT PAS CONTREFAISANTE DE PRODUIT DE TIERS. CE DENI DE GARANTIE NE S’APPLIQUERAIT PAS, DANS LA MESURE OU IL SERAIT TENU JURIDIQUEMENT NUL ET NON AVENU. Please Recycle Contents Preface vii 1. Introduction to Network Programming Interfaces 1 The Client-Server Model 1 Network Services in the Solaris Environment 3 Layered Protocols 4 Open Systems Interconnection (OSI) Reference Model 5 TCP/IP Internet Protocol Suite 7 TCP/IP Protocol Stack 7 Connection-Oriented and Connectionless Protocols 9 Connection-Oriented Protocols 9 Connectionless Protocols 10 Choosing Between COTS and CLTS 10 2. Programming With Sockets 11 Sockets are Multithread Safe 11 SunOS 4 Binary Compatibility 11 What Are Sockets? 12 Socket Libraries 13 Socket Types 13 Socket Tutorial 14 Contents iii Socket Creation 14 Binding Local Names 15 Connection Establishment 16 Connection Errors 18 Data Transfer 18 Closing Sockets 19 Connecting Stream Sockets 20 Datagram Sockets 23 Input/Output Multiplexing 27 Standard Routines 30 Host Names 30 Network Names 31 Protocol Names 31 Service Names 31 Other Routines 32 Client-Server Programs 33 Servers 33 Clients 36 Connectionless Servers 37 Advanced Topics 39 Out-of-Band Data 40 Nonblocking Sockets 41 Asynchronous Socket I/O 42 Interrupt-Driven Socket I/O 43 Signals and Process Group ID 44 Selecting Specific Protocols 45 Address Binding 46 Broadcasting and Determining Network Configuration 48 iv Transport Interfaces Programming Guide ♦ October 1998 Zero Copy and Checksum Offload 50 Socket Options 51 inetd Daemon 52 3. Programming with XTI and TLI 55 XTI/TLI Is Multithread Safe 55 XTI/TLI Are Not Asynchronous Safe 56 What Are XTI and TLI? 56 Connectionless Mode 58 Connectionless Mode Routines 58 Connectionless Mode Service 59 Endpoint Initiation 59 Data Transfer 61 Datagram Errors 63 Connection Mode 63 Connection Mode Routines 64 Connection Mode Service 67 Endpoint Initiation 68 Connection Establishment 73 Data Transfer 78 Connection Release 82 Read/Write Interface 84 Write 85 Read 85 Close 86 Advanced Topics 86 Asynchronous Execution Mode 87 Advanced Programming Example 87 State Transitions 93 Contents v XTI/TLI States 93 Outgoing Events 94 Incoming Events 95 Transport User Actions 96 State Tables 97 Guidelines to Protocol Independence 100 XTI/TLI Versus Socket Interfaces 101 Socket-to-XTI/TLI Equivalents 102 Additions to XTI Interface 104 Scatter/Gather Data Transfer Interfaces 104 XTI Utility Functions 105 Additional Connection Release Interfaces 105 4. Transport Selection and Name-to-Address Mapping 107 Transport Selection Is Multithread Safe 107 Transport Selection 108 How Transport Selection Works 108 /etc/netconfig File 109 NETPATH Environment Variable 111 NETPATH Access to netconfig Data 112 Accessing netconfig 113 Loop Through all Visible netconfig Entries 115 Looping Through User-Defined netconfig Entries 115 Name-to-Address Mapping 116 straddr.so Library 117 Using the Name-to-Address Mapping Routines 118 Glossary 123 Index 125 vi Transport Interfaces Programming Guide ♦ October 1998 Preface This manual describes the programmatic interfaces to transport services in the Solaris operating environment. In this guide, the terms SunOSTM and SolarisTM are used interchangeably because the interfaces described in this manual are common to both. Solaris 7, the distributed computing operating environment for SunSoftTM , is a superset of SunOS. It consists of SunOS release 5.7 with ONC+TM , OpenWindowsTM , ToolTalkTM , DeskSetTM , OPEN LOOK, and other utilities. This release of Solaris is fully compatible with System V, Release 4 (SVR4) of UNIX® and conforms to the third edition of the System V Interface Description (SVID). It supports all System V network services. Who Should Use This Book The guide assists you in developing a networked, distributed application in the Solaris operating environment. Use of this guide assumes basic competence in programming, a working familiarity with the C programming language, and a working familiarity with the UNIX operating system. Previous experience in network programming is helpful, but is not required to use this manual. How This Book Is Organized Chapter 1 gives a high-level introduction to networking concepts and the topics covered in this book. Preface vii Chapter 2 describes the socket interface at the transport layer. Chapter 3 describes the X/Open Transport Interface (XTI) and UNIX System V Transport Layer Interface (TLI). Chapter 4 describes the network selection mechanisms used by applications in selecting a network transport and its configuration. Ordering Sun Documents The SunDocsSM program provides more than 250 manuals from Sun Microsystems, Inc. If you live in the United States, Canada, Europe, or Japan, you can purchase documentation sets or individual manuals using this program. For a list of documents and how to order them, see the catalog section of SunExpressTM Internet site at http://www.sun.com/sunexpress. Related Books The following online System AnswerBookTM products cover related network programming topics: Solaris 7 Reference Manual Collection Solaris 7 Software Developer Collection The following third-party books are excellent sources on network programming topics: Stevens, Richard W.UNIX Network Programming. Prentice Hall Software Series, 1990. Rago, Stephen A. System V Network Programming. Addison-Wesley, 1993. Stevens, Richar W. TCP/IP Illustrated, Volume I. Addison-Wesley, 1994. Padovano, Michael. Networking Applications on UNIX System V Release 4. Prentice Hall, Inc., 1993 Comer, Douglas E.