Digital PDFs

AA-EA88D-TE

May 1990

123 pages

Original

4.4MB

Document:	DECnet—ULTRIX Programming
Order Number:	AA-EA88D-TE
Revision:	000
Pages:	123
Original Filename:

OCR Text

DECnet-ULTRIX

Programming

C'
/

May 1990
This manual offers guidelines for application programming in the
DECnet-ULTRIX environment, describes DECnet-ULTRIX
system calls and subroutines, and shows DECnet-ULTRIX data
structures and programming examples.

Supersession/Update Information:

This is a revised
manual.

Operating System and Version:

ULTRIX V4.0

Software Version:

DECnet-ULTRIX V4.0

o
Order Number: AA-EA88D-TE

AA-EA88D-TE
May 1990

The information in this document is subjectto change without notice and should not be construed as
a commitment by Digital Equipment Corporation. Digital Equipment assumes no responsibility for
any errors that may appear in this document.
The software described in this document is furnished under a license and may only be used or
copied in accordance with the terms of such license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied
by Digital or its affiliated companies.
Restricted Rights: Use, duplication, or disclosure by the U.S. Government is subject to restrictions
as set forth in subparagraph (c) (1) (ii) of the Rights in Technical Data and Computer Software
clause at DFARS 252.227-7013.

The following are trademarks of Digital Equipment Corporation:
DEC
DECnet
DECUS

PDP
ULTRIX
UNIBUS

VAX
VMS

~DmBDmDTM

UNIX is a registered trademark of AT&T in the USA and other countries.

This manual was produced by Networks and Communications Publications.

c
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Overview

Part I

Chapter 1

'',
C

Introduction to the DECnet-ULTRIX Programming Environment

1.1

DECnet-ULTRIX Programming Interface ........................... .

1-1

1.2

Network Objects ............................................ .

1-2

1.3

Communication Domains ..................................... .

1-2

1.4

Sockets .................................................. .

1-2

1.5

Blocking and Nonblocking Input/Output Modes ..................... .

1-2

1.6

Accept-Immediate and Accept-Deferred Modes ...................... .

1-3

1.7

Access-Control Information .................................... .

1-3

1.8

Proxy Access .............................................. .

1-3

1.9

Optional Data .............................................. .

1-4

1.10

Out-of-Band Messages ....................................... .

1-4

Chapter 2

vii

DECnet-ULTRIX Programming Tools

2.1

How the dnet_conn Subroutine Works ............................ .

2-1

2.2

How the dnet_eof Subroutine Works ............................. .

2-2

2.3

How the DECnet Object Spawner Works .......................... .

2-2

2.4

How DECnet-ULTRIX System Calls Work .......................... .
2.4.1
Using System Calls for Client Programs . . . . . . . . . . . . . . . . . . . . .
2.4.2
Using System Calls for Server Programs . . . . . . . . . . . . . . . . . . . . .

2-3
2-3
2-4

2.5

Three Ways to Use DECnet-ULTRIX Programming Tools ............... .
2.5.1
Using dneCconn with the DECnet Object Spawner ............. .
2.5.2
Using DECnet-ULTRIX System Calls . . . . . . . . . . . . . . . . . . . . . . .
Combining DECnet-ULTRIX Tools . . . . . . . . . . . . . . . . . . . . . . . . .
2.5.3

2-6
2-6

2-7
2-7
iii

Chapter 3

Programming in the DECnet Domain
How to Program a Client-Initiated Connection
3.1.1
Choosing a Socket Type for the Client ..................... .
3.1.1.1
Using dnet_conn ............................ .
3.1 .1 .2
Using System Calls ...... . . . . . . . . . . . . . . . . . . . . .
3.1.2
Specifying a Node and Server ........................... .
3.1.2.1
Using dnet_conn ............................ .
3.1.2.2
Using System Calls .......................... .
3.1.3
Specifying Access-Control Information ...................... .
3.1.3.1
Using dnet_conn ............................ .
3.1.3.2
Using System Calls .......................... .
3.1.4
Requesting Proxy .................................... .
3.1.4.1
Using dnet_conn ............................ .
3.1 .4.2
Using System Calls .......................... .
3.1 .5
Setting Up Optional Data for the Client . . . . . . . . . . . . . . . . . . . . . .
3.1.5.1
Using dneCconn ............................ .
3.1 .5.2
Using System Calls .......................... .

3-5
3-5

3.2

How to Establish a Connection for the Server ...................... .
3.2.1
Choosing a Socket Type for the Server ..................... .
3.2.1 .1
Using the Network Control Program (NCP) . . . . . . . . . . . .
3.2.1.2
Using System Calls .......................... .
3.2.2
Assigning a Name to Your Server ......................... .
3.2.2.1
Using the Object Spawner ...................... .
3.2.2.2
Using System Calls .......................... .
3.2.3
Selecting Accept-Immediate or Accept-Deferred Modes .......... .
3.2.3.1
Using the Object Spawner ...................... .
3.2.3.2
Using System Calls .......................... .
3.2.4
Verifying Remote User Access to the Server ................. .
3.2.4.1
Using the Object Spawner ...................... .
3.2.4.2
Using System Calls .......................... .
3.2.5
Exchanging Optional Data .............................. .

3-10
3-11
3-11
3-11
3-12
3-12
3-12
3-13
3-13
3-13
3-13
3-14
3-14
3-14

3.3

Transferring Data After Establishing a Connection ................... .
3.3.1
Using Blocking or Nonblocking 1/0 . . . . . . . . . . . . . . . . . . . . . . . . .
3.3.2
Using Out-of-Band Messages ............................ .
3.3.3
Detecting Zero-Length Messages ......................... .

3-15
3-15
3-16
3-16

3.4

How to Disconnect a DECnet Connection .......................... .

3-17

3.1

Part II

3-1
3-1
3-2
3-2
3--3
3--3
3--3

3-6

3-7
3-7
3-7
3-8
3-8
3-9
,/

."..

Reference

Chapter 4

DECnet-ULTRIX System Calls

4.1

System Call Summary

4-1

4.2

On-Line Manual Pages

4-2

4.3

Format and Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-2

c
iv

4.4

Chapter 5

System Call Descriptions ..................................... .
accept (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bind (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
close (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
connect (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getpeername (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getsockname (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getsockopt (2dn) and setsockopt (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
listen (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
read (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
recv (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
select (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
send (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setsockopt (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
shutdown (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
socket (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
write (2dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-3
4-4
4-6

4-8
4-9
4-11
4-13
4-15
4-19
4-20
4-22
4-24
4-26
4-28
4-29
4-30
4-32

DECnet-ULTRIX Subroutines

5.1

Subroutine Summary ........................................ .

5-1

5.2

On-Line Manual Pages ....................................... .

5-2

S.3

Format and Conventions ...................................... .

5-2

5.4

Subroutine Descriptions ...................................... .
dnet_addr (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_conn (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_eof (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_getalias (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_htoa (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_ntoa (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dnet_otoa (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getnodeadd (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getnodeent (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getnodename (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
nerror (3dn) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-3
5-4
5-5
5-9
5-10
5-11
5-12
5-13
5-14
5-15
5-17
5-18

c
Appendix A

DECnet-ULTRIX Data Structures

A.1

Access-Control Information Data Structure ......................... .

A-1

A.2

DECnet Node Address Data Structure ............................ .

A-1

A.3

Logical Link Information Data Structure ........................... .

A-1

A.4

Optional User Data Structure .................................. .

A-2

A.S

Socket Address Data Structure ................................. .

A-2

o
v

Appendix B

DECnet-ULTRIX Programming Examples

B.1

Sample Client Program Using dnet_conn .......................... .

B-2

B.2

Sample Server Program Using the dnet_spawner .......... , ......... .

B-4

B.3

Sample Client Program Using System Calls ........................ .

B-6

B.4

Sample Server Program Using System Calls ....................... .

B-8

B.5

Sample Application Gateway Program ............................ .

B-1 0

2-1
2-2
2-3
3-1
3-2

Client Program Calling Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

2-4
2-5
2-7

,r~
r

~Jl

Glossary

Index

Tables
Server Program Calling Sequences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Methods for Establishing a Client-Server Session . . . . . . . . . . . . . . . . . . . . . . .
Socket Types Compared . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-1

Object Number Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

3-12

4-1

DECnet-ULTRIX System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

4-1

5-1

DECnet-ULTRIX Subroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

5-1

c
vi

Preface
The DECnet-ULTRIX product is layered software that runs on an ULTRIX
system. With this software, an ULTRIX system functions as an end node in a
DECnet network. The DECnet-ULTRIX product is an end-node implementation
of Digital Network Architecture (DNA) Phase Iv.

Manual Objectives
Using both tutorial and reference material, this manual show programmers how
to write programs for client and server applications in the DECnet-ULTRIX
environment.

Intended Audience
This manual is for programmers using DECnet-ULTRIX software to write network applications. The manual assumes the following:

•

You are familiar with an editor, such as vi or ed.

•

You have a working knowledge of the C programming language and experience writing system or network programs.

•

You are familiar with the ULTRIX system, including its naming conventions,
system commands, system calls, and subroutines.

Structure of This Manual
The DECnet-ULTRIX. Programming manual is divided into two parts, five chapters, and two appendixes.
Part I introduces DECnet-ULTRIX programming concepts and guidelines for
application programming in the DECnet-ULTRIX programming environment:
Chapter 1

Describes DECnet-ULTRIX programming concepts.

Chapter 2

Describes DECnet-ULTRIX programming tools and how they work in
the DECnet-ULTRIX programming environment.

Chapter 3

Explains how to write programs for clients and server applications in
the DECnet-ULTRIX programming environment.

o
vii

Part II contains descriptions and other reference information about the
DECnet-ULTRIX system calls and subroutines:
Chapter 4

Describes the DECnet-ULTRIX system calls.

Chapter 5

Describes the DECnet-ULTRIX subroutines.

The appendixes show DECnet data structures and programming examples.
Appendix A

Contains the DECnet-ULTRIX data structures.

Appendix B

Contains DECnet-ULTRIX programming examples.

Related Documents
To supplement the DECnet-ULTRIX Programming manual, refer to the following
manuals:

•

DECnet-ULTRIX Release Notes
This document contains miscellaneous information and updates not included
in other books in the DECnet-ULTRIX documentation set.

•

DECnet-ULTRIX DECnet-Internet Gateway Use and Management
This manual describes the DECnet-Internet Gateway and contains directions
for installing, using, and managing, it.

•

DECnet-ULTRIX Network Management
This manual defines the DECnet-ULTRIX network databases and components. It describes the Network Control Program (ncp) and how it is used
to configure, monitor, and test your network. Other topics include loopback
testing, event logging, and instructions for displaying network information.

•

DECnet-ULTRIX NCP Command Reference
This reference manual describes the ncp commands used for defining, monitoring, and testing your network.

•

DECnet-ULTRIX Installation Guide
This manual describes procedures for installing a DECnet-ULTRIX node and
testing it for proper operation. This manual also lists the
DECnet-ULTRIX distribution files and the path names to which they are
installed.

•

ULTRIX Guide to the Data Link Interface (DLI)
This manual describes procedures for using DLI to write application programs
a t the data link layer.

•

ULTRIX Introduction to Network Programming
This manual describes network programming concepts for programming in
the ULTRIX environment.

To obtain a detailed description of DNA, refer to the DECnet Digital Network
Architecture (Phase N), General Description.

c
viii

Graphic Conventions
This manual uses the following graphic conventions:
Convention

Meaning

special

Command options, system calls, subroutines, and data structures appear in special type.

command()

Cross-references to specific command documentation include
the section number in the reference manual where the commands are documented. For example: See the socket(2dn)
system call. This indicates that you can find the material on
the socket system call in Section 2dn of the reference pages.

literal

Indicates terms that are constant and must be typed just as
they are presented.

[ ]

Square brackets indicate optional arguments. Do not type the
brackets.
Horizontal ellipsis points indicate that the preceding item can
be repeated one or more times.

NOTE

In examples, vertical ellipsis
points represent either user
input or system input that has
been omitted to emphasize
specific information.
lowercase!
UPPERCASE

Because DECnet-ULTRIX software is case-sensitive, you
must type all literal input in the case shown. UPPERCASE
is also used for the names of all DECnet nodes, including
DECnet-ULTRIX. nodes. This convention follows DEC net protocol, which names and recognizes all nodes in UPPERCASE.
However, node names are not case-sensitive and need not be
typed in the case shown.

example

Indicates an example of system output. System output is in
black type; user input is in red type.

italics

Indicate a variable, for which either you or the system must
specify a value.

The default user prompt in multiuser mode.

The default superuser prompt.

Ikeyl

Indicates a key on your keyboard. I cTRukey I represents a
CONTROL key sequence, where you press the CONTROL key
at the same time as the specified key.

Other conventions are as follows:
•

All numbers are decimal unless otherwise noted.

•

All Ethernet addresses are hexadecimal.

c
ix

Part I

Overview

r ""\
~"=/
I

Chapter 1

Introduction to the DECnet-ULTRIX Programming
Environment
This chapter introduces some of the DECnet programming concepts on which
the DECnet-ULTRIX programming interface is based. All terms and concepts in
this chapter are presented in the context of the DECnet-ULTRIX programming
environment.
For more infonnation about programming in the ULTRIX environment, see the
ULTRIX Network Programming Guide and the article itA 4.2 BSD Interprocess
Communication Primer," in the ULTRIX Supplementary Documentation, Volume
III.

1.1 DECnet-ULTRIX Programming Interface
The DECnet-ULTRIX programming interface lets you write cooperating programs
that exchange data over a DECnet network. The interface provides the following
support:

Client-server communication. This is sometimes called task-to-task
communication. The client application initiates a connection and requests
services from the server application. The server application either accepts or
rejects the request. Client-server communication lets DECnet-ULTRIX Phase
IV applications communicate with remote Phase III and Phase IV DECnet
applications through a socket-level programming interface.
DEC net and TCPIIP coexistence. DECnet protocols and Transmission
Control ProtocollInternet Protocol (TCPIIP) coexist and can share system
resources, including Ethernet and Digital Data Communications Message
Protocol (DDCMP) hardware. You can modify most TCPIIP programs to use
DECnet protocols, or DECnet programs to use TCPIIP protocols. You can use
DECnet and TCPIIP simultaneously on an Ethernet and alternate between
the two protocols on DDCMP point-to-point lines.
File access. Programs on any other DECnet Phase IIIIIV system can access
DECnet-ULTRIX files for sequential reading, writing, directories, or deletion.
Access Control. DECnet-ULTRIX supports two ways for your client
application to gain access to the server: access-control information and proxy.

See Sections 3.1.3 and 3.1.4 for instructions on how to use proxy and
access-control infonnation in a connection request.

Introduction to the DECnet-ULTRIX Programming Environment 1-1

1.2 Network Objects
;//~\

In the DECnet-ULTRIX programming environment, a network object is a server
application that can be accessed by name or number from other DECnet nodes.
A client application identifies the server application it wants to connect to by
specifying the server's object name or number as part of a connection request.

I,..-f

See the DECnet-ULTRIX NCP Command Reference manual for examples of
network objects.

1.3 Communication Domains
A communication domain is a set of protocols that have common communication properties. DECnet-ULTRIX. introduces the DECnet domain into the
ULTRIX Interprocess Communication (IPC) environment for applications that
communicate through the DECnet standard protocols.

1.4 Sockets
A socket is an addressable endpoint for communication. The client and server
applications each create a socket that acts as a handle for sending and receiving
data.

Each communication domain supports a different set of socket types. The DECnet
communication domain supports the following socket types for DECnet-ULTRIX
applications:

Sequenced-packet sockets. A sequenced-packet socket supplies a bidirectional, reliable, ordered, first~in,first~out (FIFO), unduplicated flow of
data.
The socket preserves the record boundaries. A write operation transmits
one message across the connection; a read operation-if it completes
successfully-returns a single, logical message.

Stream sockets. A stream socket also supplies a bidirectional, reliable,
ordered, FIFO, unduplicated flow of data.
Stream sockets provide a byte stream without using message boundaries.
Data supplied as part of a write operation mayor may not transmit a message
across the connection, and a read operation may return data from one or more
data packets. These possibilities depend on system variables unknown to the
program.

1.5 Blocking and Nonblocking Input/Output Modes
Blocking and nonblocking are input/output (1/0) modes that cause a calling
process to either wait (blocked) or not wait (nonblocked) for an 1/0 operation.
Blocking prevents an I/O system call from returning control to a calling procedure
until the operation completes. The nonblocking I/O mode returns control to the
calling procedure immediately with an error message if there are not enough
resources available to complete the operation.

1-2 Introduction to the DECnet-UlTRIX Programming Environment

1.6 Accept-Immediate and Accept-Deferred Modes
DECnet supports two modes for accepting incoming connections: immediate and
deferred.

Accept-Immediate mode makes it possible for the server program to send
and receive data as soon as the accept caII operation completes. However,
in this mode, the server does not have access to any optional data or
access-control infonnation that may have been supplied with'the connection
request.
Accept-Deferred mode lets the server program store, examine, and process
any access-control infonnation or optional data that is supplied as part of a
connection request. The server must then accept or reject the connection.
As long as the socket is in accept-deferred mode, a server program can
retrieve access-control infonnation or retrieve and return optional data when
a connect is pending; that is, after an accept call has successfully completed,
but before the server accepts or rejects the connection.

1.7 Access-Control Information
The DECnet architecture lets the client requesting the connection pass accesscontrol information to a server application. The server application then uses this
infonnation to determine if access should be granted. This information consists of
three strings: username, password, and account. These are defined as follows:
username

A name of up to 39 characters assigned to the user on the
server system.

password

A string of up to 39 characters that you use to gain access to
the user account on the server system.

account

A string of up to 39 characters that some DECnet systems use
to identify the remote users and their privileges upon logging
in. The server ignores this string if it is not required.

Different servers interpret and use these strings according to their own requirements. In many cases, servers compare received access-control information
against the system password file. UsuaIIy, the results of this comparison determine whether a connection request is accepted and, if it is, what privileges and
quotas are aIIowed.

1.8 Proxy Access
In the DECnet domain, proxy access is a method of screening client application
access to the server application without supplying a password.
When the client requests a connection, the node on which the client resides
passes the identity of the client application to the target node on which the server
resides. The supplied name (a log-in name or user ID) of the user initiating the
request for the client must correspond with an entry listed in the target node's
proxy access file.

This procedure is more secure than sending a password over the network.

Introduction to the DECnet'-ULTRIX Programming Environment 1-3

1.9 Optional Data
In the DECnet domain, optional data is a string of up to 16 bytes that clients and
servers can exchange on either a connect or disconnect sequence. This data is
interpreted differently according to the application.
Some application protocols exchange additional identifying information (such as a
protocol version number) at the time of the connection. This information is used
to determine whether a connection request should be accepted. For example,
DECnet Network Management uses optional data to exchange protocol version
numbers before a connection is established. Also, when a socket is disconnected
or a connection request is rejected, the application may use optional data to send
an error message.

1.10 Out-of-Band Messages
An out-of-band message is an unsolicited, high-priority message that one
application sends to another outside of the normal data channel. In most cases, it
informs the receiving application of an unusual or abnormal event in the sending
application.

c
1-4 Introduction to the DECnet-ULTRIX Programming Environment

c
Chapter 2

DECnet-ULTRIX Programming Tools
This chapter describes some of the tools for writing DECnet--ULTRIX client and
server applications. It explains how the tools work and recommends methods of
using them in the DECnet--ULTRIX programming environment.
Tools for programming client and server tasks in the DECnet domain include:

•

The DECnet library (libdnet.a), which contains subroutines that simplify
many basic programming operations. Two important subroutines included in
this library are:
The dnet_conn subroutine, a routine that establishes a connection to a
specified network object on a remote node.
The dnet_eof subroutine, a routine that tests the state of an established
connection to a remote DECnet application.

NOTE

When you build programs that use these routines, you must specify
-Idnet in the command line or makefile. Versions of the libraries
suitable for use by lint are contained in the unsupported subset.
See the DECnet-ULTRIX Installation manual for the subset name
and location.

c
2.1

•

The object spawner, a server program that listens for connection requests on
behalf of all servers that are not actively listening for connection requests.

•

System calls used within the DECnet domain to perform network connection
and data transfer functions. Examples of these calls are accept, bind, write,
and close.

How the dnet conn Subroutine Works
When you use dnet_conn to establish a connection for a client application, the
subroutine performs connection tasks in the following order:
1. Creates a socket in the DECnet domain.

2. Formats access-control information and optional connection data.
3. Issues a connection request to a server application.

4. Returns optional data received from the server if the connection is established.
The dnet_conn subroutine accepts the following as input:
•

The name of the node to which you connect.
DECnet-ULTRIX Programming Tools

2-1

•

The name or number of the server on the node.

•

The socket type.

•

A buffer for outgoing optional data, and a buffer for incoming optional data.

The dnet_conn subroutine also lets you pass access-control infonnation to the
server by appending it to the node name.
NOTE

The name of the node supplied to dnet_conn may be a node alias as
defined in the .nodes file. Programs that use dnet_conn will prompt
you for a password if you choose to omit the password field in an
access-control string. To provide account security, the password that
you type after the prompt does not echo.
If a connection is established successfully, dnet_conn returns a socket descriptor
that can be used for subsequent read and write operations. If an error is
encountered, dnet_conn returns a -1 value with additional error detail available
in the external variable errno. Use the nerror system call to print out relevant
DECnet error messages.
NOTE

The dnet_conn subroutine no longer returns the ULTRIX diagnostic
message [ECONNABORTED] or [ECONNRESET]. If DECnet is not
installed on the system, the socket request that dnet_conn makes will
fail with the ULTRIX error message [EPROTONOSUPPORT], which is
equivalent to the DECnet error message, "Protocol not supported."

2.2 How the dnet eof Subroutine Works
When you use dnet_eof to test the state of an established connection, the
subroutine performs the following steps:
1. Tests a DECnet socket to determine if an end-of-file (EOF) condition exists.

2. Returns a value of 0 if it determines a connection is in an active state.
3. Returns a nonzero value if it determines that a connection is in an inactive
state.
This subroutine is useful for determining if any data exists for a read operation
and if the socket is connected.
See dnet_eof(3dn) for more information about how to use the dnet_eof subroutine.

2.3 How the OECnet Object Spawner Works
The logic sequence for using the object spawner follows:
1. The object spawner creates a socket in the DECnet domain and listens for

incoming connection requests on behalf of multiple DECnet objects (named
and numbered).
2. When the object spawner receives a request to connect to an object, the
spawner checks the object database to verify that either the server program
or the default object is defined. If neither is found, it rejects the connection.

2-2

DECnet-ULTRIX Programming Tools

(--./"-

3. If access-control information is specified with the connection request, the
object spawner verifies the information with the system password file. If the
information is invalid, the connection is rejected. If it is valid, go to step 7.

4. If proxy is requested with the connection request, the object spawner verifies
the proxy request with the system proxy file. If no entry is found, the object
spawner uses the default user associated with the object entry for the server.
5. If access-control information is not specified or proxy is not requested, the
object spawner uses the default user associated with the object entry for the
server.
6. If the default user is specified for the object entry and defined in the system
password file, the connection is accepted. Otherwise, the connection is
rejected.
7. The object spawner redirects standard input and standard output to the
network connection.
8. The object spawner executes the server program after setting up the
environment. The environment is based on information in the password file
entry of the user through which access was granted to the object. In addition,
the setting for the process group is set equal to the process ID, and the group
access list is initialized. Standard error is then redirected to /dev/null.
The logic sequence for server programs using the object spawner depends on the
specified mode of acceptance, as follows:
1. If the accept mode is immediate, the object spawner completes the server
connection. The server program can then exchange data by reading standard
input and writing standard output.
2. If deferred mode was chosen, the connection request must be completed by
the server using either standard input or standard output as the socket
handle. The server program uses the getsockopt and setsockopt calls to
complete the connection, as shown in steps 6 through 8 of the system call
logic sequence described in Section 2.4.1.

2.4 How DECnet-ULTRIX System Calls Work
The following sections describe how client and server applications use system
calls to establish a connection, exchange data, and terminate a connection.

2.4.1

Using System Calls for Client Programs
The following list shows how a client application can use system calls to establish
a network connection:
1. To initiate a connection, a client program creates a socket for the connection
by issuing a socket call. This call creates a socket of the specified type in the
DECnet domain. The socket call returns a descriptor for the socket, which is
used for subsequent program requests.
2. To set up access control, use one or both of the following methods:

a. To pass access-control information, issue the setsockopt call on the
descriptor returned from the socket call with the option
DSO_CONACCESS. The structure accessdata_dn, which contains the
data you have specified, is passed as a parameter to the call.

DECnet-ULTRIX Programming Tools

2-3

b. To use proxy access, set the SDF_PROXY bit in the sdnJlags field of the
sockaddr_dn structure before issuing the connect call. If the program is
to be executed with superuser privileges, you may want to bind a name
to be used as the proxy source name to the socket, before issuing the
connect call.
3. To pass optional data, issue setsockopt again with the option
DSO_CONDATA. The structure optdata_dn, which contains the data you
have specified, is passed as. a parameter.
4. A client program issues a connect call to request a connection to a specified
object. If the preceding setsockopt calls were successful, DECnet will use the
data you have supplied when the connect call is issued.
5. The client program can issue a getsockopt call to retrieve incoming optional
data.
6. If the connect call is successful, the program can use the socket to send and
receive data by means of the read and write or recv and send calls.
7. The program can use the getsockopt or setsockopt call to send or receive
optional data with the close call.
8. The close call terminates the connection.
Table 2-1 summarizes the logic sequences for a typical DECnet-ULTRIX client
application using system calls. See Appendix B for programming examples.
Table 2-1:

Client Program Calling Sequences

Function

System Calls

Create a socket for the connection.

socket
setsockopt*

Send optional data and/or access-control
information with the connection request.
Define a name for the socket.
Request a connection to a server program.
Retrieve optional data from the server.
Transfer normal data.

Transfer out-of-band data.
Send or receive optional data with the close call
Terminate the connection.

bind*
connect
getsockopt *
send
recv
read
write
send ..
recv *
setsockopt*
getsockopt ..
close

* Optional.

2.4.2

Using System Calls for Server Programs
The following list describes the logic sequence for a typical DECnet-ULTRIX
server program using system calls to establish a con.nection.
1. The server program creates a socket in the DECnet domain by issuing a
socket call.

2-4

DECnet-ULTRIX Programming Tools

C·

2. The object name or nwnber is stored in the sockaddr_dn structure. The
server issues a bind call to assign the object name or number. (See the
description of the bind call in bind(2dn».
.

3. A server can issue a setsockopt call to set the mode of acceptance to deferred.
4. A server issues a listen call, which declares that the socket is available for
receiving connection requests directed to the bound name.

5. An accept call completes when the system receives a connection request.
(Note that an accept call in deferred mode must be issued to receive a
request, but does not actually accept the connection.) If the accept is
successful, a new server socket is created.
NOTE

If you specified accept-immediate mode, you can use the socket
to send and receive data. If you specified accept-deferred mode,
however, you must complete the following steps before attempting
to transfer data.
6. A server issues a getsockopt call to retrieve any access-control information or
optional data that was supplied with the connect call.
7. A server issues a setsockopt call to supply any optional data that it wants to
return to the client program.
S. The server issues a setsockopt call to accept or reject the connection.

9. If the server accepts the connection, the program can use the socket to send
and receive data by means of the read and write or recv and send calls.

10. The program can use the getsockopt or setsockopt call to send or receive
optional data with the close call.
11. The close call terminates the connection.
Table 2-2 summarizes the calling sequences for a typical DECnet-ULTRIX server
application using system calls. See Appendix B for programming examples.
Table 2-2: Server Program Calling Sequences

Function

System Calls

Create a socket to listen for connection requests.

socket
bind
setsockopt ..

Define a name for the socket.
Set the mode of acceptance. The default mode
is IMMEDIATE, and the other possible mode is
DEFERRED.

Declare the socket available for connection
requests.

listen

Block the server program until it receives a
connection request.

When in accept-deferred mode, receive optional
data or access-control information.

getsockopt ..

When in accept-deferred mode, supply optional
data, such as the server software version number.

setsockopt ..

"Optional

(continued on next page)
DECnet-ULTRIX Programming Tools 2-5

Table 2-2 (Cont.):

Server Program Calling Sequences

Function

System Calls

When in accept-deferred mode, accept or reject
the connection.

setsockopt •

Transfer normal data.

send
recv
read
write
send"
recv"
setsockopt·
getsockopt •
close

Transfer out-of-band data.
Send or receive optional data with the close call.
Terminate the connection.
"Optional

2.5 Three Ways to Use DECnet-ULTRIX Programming Tools
You can use DECnet-ULTRIX tools to establish a connection between client and
server applications in three ways:
•

Let DECnet-ULTRIX. subroutines and the DECnet object spawner handle
programming tasks for you.

•

Use system calls to perform the same tasks yourself.

•

Combine DECnet-ULTRIX subroutines and DECnet object spawner functions
wi th system call functions.

Mter you have established a connection between the client and server, you can
use system calls and subroutines to perform data transfer tasks and disconnect
the network connection.

2.5.1

Using dnet_conn with the DECnet Object Spawner
You can let the dnet_conn subroutine and the object spawner establish the
connection between the client and server. dnet_conn initiates the connection and
performs connection tasks for the client application. The object spawner performs
connection tasks on behalf of the server.
The object spawner is the recommended tool for server programs because it
provides the following services:
•

Eliminates the need for coding connection request processing, including
access-control information and proxy handling, in the server program.

•

Reduces the number of idle processes because it listens on behalf of multiple
servers.

See Appendix B for a programming example that shows how you can use dnet_
conn and the object spawner to establish a connection between client and server
applications.

2-6

DECnet-ULTRIX Programming Tools

2.5.2

Using DECnet-ULTRIX System Calls
You can use DECnet-ULTRIX system calls to establish a session and accept
connection requests. The system calls can perform all the tasks that dnet_conn
performs for you. They can also give you more programming flexibility by letting
you control each task during the connection process.
See Appendix B for programming examples.

2.5.3

Combining DECnet-ULTRIX Tools
You can combine tools to establish a session. For example, you can use dnet_conn
to initiate a connection request for the client and use the system calls to accept
the request for the server. Also, you can use system calls to initiate a connection
request for the client and let the object spawner accept the request for the server.
Table 2-3 shows four ways to establish a session with DECnet-ULTRIX tools.
Table 2-3:

Methods for Establishing a Client-Server Session

Client Application Task

Server Application Task

dnet_conn requests a session.

DECnet object spawner establishes the connection.

dnet_conn requests a session.

System calls accept or reject the request.

System calls request a session.

DECnet object spawner accepts the request.

System calls request a session.

System calls accept or reject the request.

o
DECnet-ULTRIX Programming Tools

2-7

Chapter 3

Programming in the DECnet Domain
This chapter explains procedures for writing DECnet-ULTRIX applications by
using either subroutines or system calls. The following sections explain how to
perform four basic network application programming tasks:

•
•
•
•

Program a client application to initiate a network connection.
Program a server application to respond to a network connection request.
Perform data transfer tasks after establishing a connection.
Disconnect a session between a client and server application.

3.1 How to Program a Client-Initiated Connection
'lb initiate a network connection between your client application and a remote
DECnet application, you can use dnet_conn or system calls to:

1. Choose the socket type for the client.

2. Identify the node and server to which the client is attempting to connect.
3. Set up either access-control or proxy for client access to servers.
4. Send and receive optional data.

3.1.1

Choosing a Socket Type for the Client
DECnet supports two socket types: sequenced-packet sockets and stream sockets.
Table 3-1 compares these sockets.
Table 3-1:

Socket Types Compared

Sequenced-Packet Socket

Stream Socket

Preserves message boundaries

Does not preserve message boundaries

DECnet-VAX. default socket

Commonly used for ULTR1X applications

Not available on TCPIIP

Available on TCP/IP

When writing applications, use the same socket type as the program you connect
to uses. If a connection uses both types of sockets, the program using the stream
socket:

•

Has no control over how much data the sequenced-packet socket will get
when it performs its next read operation.

Programming in the DECnet Domain 3-1

•

Does not receive any indication of the record boundary on a read opera tioneven though the program using the sequenced-packet socket creates a record
boundary with each write operation.

Applications that use message boundaries to interpret data cannot be used in
connections using both stream and sequenced-packet sockets. If you cannot
guarantee that both ends of a connection will use the same socket type, design an
application protocol that does not use record boundaries.

3.1.1.1

Using dnet_conn

To specify the socket type as an argument in dnet_conn, use this format:
s=dnet_conn(node,object, type,)
where
type

is either SOCK_STREAM, if you want to specify a stream socket, or
SOCK_SEQPACKET, if you want to specify a sequenced-packet socket.
If the socket type is set to 0, use the default, SOCK_SEQPACKET.

EXAMPLE:
This example shows a sequenced-packet socket being selected for node NAVAHO
with object 17.
s=dnet_conn(NAVAHO,17,SOCK_SEQPACKET,)

For more information about socket types, see the description in dnet~conn(2dn).
3.1.1.2

Using System Calls

To specify a socket type during a socket call operation, use this format:
s=socket(node, object,type, )
where
type

is either SOCK_STREAM, if you want to indicate a stream socket, or
SOCK_SEQPACKET, if you want to indicate a sequenced-packet socket.

EXAMPLE:
This example shows a sequenced-packet socket being selected for a DECnet node.
s=socket(AF_DECnet,SOCK_SEQPACKET,)

For more information about socket types, see the description in socket{2dn).

c
3-2

Programming in the DECnet Domain

3.1.2 Specifying a Node and Server
Before your client application can request a connection, you must:
1. Identify the node on which the server resides.

You can use a node name (an alphanumeric string of one to six characters) or
node address (an area number from 1 to 63, followed by a period and a node
number from 1 to 1,023).
2. Identify the server you want to connect to.
The client application can specify the server application in one of two ways:
•

By a network object name of up to 16 characters.

•

By a network object number from 1 to 255.

If the remote object is defined (that is, an object number has been assigned to
the server process-either by Digital or by the user), the object number is the
recommended method for requesting the network service to avoid any conflicts in
naming conventions.

See the DECnet-ULTRIX NCP Command Reference manual for detailed
information on preassigned network object numbers and procedures for defining
network objects in the object database.

3.1.2.1

Using dnet_conn

To specify a node and server while requesting a connection, use the following
format:
d net_con n(node,object,)

where
node

is either the node name or address used to specify the node.

object

is either the object name or the object number used to specify the
server.

The following examples show you how to use dnet_conn to specify a node and a
server by name and number while establishing a connection.
EXAMPLE 1:
In this example, the client program uses dnet_conn to connect to object number
17 on node NAVAHO.
s=dnet_conn("navaho","#17",)

EXAMPLE 2:
In this example, the client program uses dnet_conn to connect to object xyz on
the node with a DECnet address 55.342.
s=dnet_conn("55.342","xyz",)

3.1.2.2

Using System Calls

To specify the node and server, you must use the sockaddr_dn data structure.

o
Programming in the DECnet Domain

3-3

EXAMPLE 1:
In this example, the client program connects to server xyz on node 55.342:
tdefine SERVERNAME "xyzu 0
tdefine NODE
"55.342"

struct sockaddr_dn sockaddr; ~
struct dn_naddr*node_addr;
int sock;

bzero(&sockaddr, sizeof(sockaddr»;
sockaddr.sdn_family = AF_DECnet; E)
sockaddr.sdn objnamel = strlen(SERVERNAME);
strncpy(;ockaddr.sdn_objname,SERVERNAME,
sizeof(sockaddr.sdn_objname»;
node_addr = dnet_addr(NODE);

sockaddr.sdn_add = *node_addr;
if (connect (sock, &sockaddr, sizeof(sockaddr»

< 0)

{

perror("connect");
exit(l);

COMMENTS:

o Defines the server using a network object name. This name can be up to
16 characters long.
~

The sockaddr_dn data structure is defined in the file Isys/netdnet/dn.h
(see Appendix A).

6) You must specify the AF_DECnet address family.

o These three lines show how the server name is put into the sockaddr_dn
structure.

o If you are using the dnet_addr subroutine to specify a node in the
sockaddr_dn data structure, you must use a node address.

EXAMPLE 2:
This example shows you how to connect to server 17 on node NAVAHO by number.

c
3-4

Programming in the DECnet Domain

# def ine SERVERNUMBER 1 7 0
# define NODENAME

"navaho"

struct sockaddr_dn sockaddri
struct nodeent *nodepi
int sock;

bzero(&sockaddr, sizeof(sockaddr}}i
sockaddr. sdn family = AF DECnet; 6)
sockaddr.sdn=objnum = SERVERNUMBERi
nodep = getnodebyname(NODENAME}; C)
bcopy(nodep->n_addr, sockaddr.sdn_nodeaddr, nodep->n_length};
sockaddr.sdn_nodeaddrl = nodep->n_lengthi

if (connect (sock, &sockaddr, sizeof(sockaddr)} < O}
{

perror("connect");
exit(l};

COMMENTS:

o Defines the server using a network object number. This can be any
number from 1 to 255.

8 The sockaddr_dn data structure is defined in the file Isys/netdnet/dn.h
(see Appendix A).

o You must specify the AF_DECnet address family.
e If you are using the getnodebyname subroutine to specify a node in the
sockaddr_dn structure, you must specify a node name.
~

These three lines show how to fill in the node address fields of the
sockaddr_dn data structure.

See Appendix B for more detailed programming examples.

3.1.3 Specifying Access-Control Information
You can use either the dnet_conn subroutine or system calls to specify
access-control information for the client application.

3.1.3.1

Using dnet_conn
To specify access-control information, use the following format:
dnet_conn("node / username[/ password][/ account]")
where

o
Programming in the DECnet Domain

3-5

3.1.3.2

node

is a string that specifies the node name or address~ followed by the
username ~ password~ and account strings separated by slashes (/).

username

is a name of up to 39 characters assigned to the user on the server
system.

password

is a string of up to 39 characters that you use to gain access to the user
account on the server system.

account

is a string of up to 39 characters used by some DECnet systems. The
server ignores this string if it is not required.

Using System Calls
1b specify access-control infonnation~ issue a setsockopt call with the
DSO_CONACCESS option. The access-control data is passed in the
accessdata_dn data structure (described in Appendix A). The access-control
information is used when the client issues the connect call.

EXAMPLE:
This example shows a setsockopt call being issued with a DSO_CONACCESS
option in the accessdata_dn structure.
set access control(socket, user, password)
int-socket;
char *user, *password;

struct accessdata_dn acc_data;
bzero(&acc_data, sizeof(acc_data»;
acc data.acc userl = strlen(user);
strncpy(acc_data.acc_user, user, acc_data.acc_userl);
acc_data.acc-passl = strlen(password);
strncpy(acc_data.acc-pass, password, acc_data.acc-passl);

return (setsockopt (sock, DNPROTO NSP, DSO CONACCESS,
&acc_data, sizeof(acc_data»);
-

COMMENTS:

o The lengths of the user name and password are defined in
Isys/netdnet/dn.h.

8 The account string is not used in this example.

NOTE

The setsockopt call must precede the connect call to supply access
information for the connection request.

Mter the client issues a connect call, DECnet flushes any access-control
infonnation previously set with the setsockopt call and the DSO_CONACCESS
option. Therefore, you must specify new access-control data for any subsequent
connection requests that the client issues on the same socket.

3-6

Programming in the DECnet Domain

3.1.4

Requesting Proxy
You can use either the dnet_conn subroutine or system calls to request proxy for
a client application.

3.1.4.1

Using dnet_conn

The dnet_conn subroutine requests proxy by default. If the default (proxy)
setting is not changed, dnet_conn binds the user's log-in name (converted to
uppercase) to the socket. This bound name is used as the source name for the
outgoing connection only when a program's user ID is set to root or invoked by
the superuser. Otherwise, the ASCII form of the user's ID is used as the source
name for proxy access.
If you do not want dnet_conn to request proxy access at the remote system, set
the external variable, proxy_requested, equal to zero.
EXAMPLE:
In this example, the proxy yequested variable is set to zero.
extern char proxy_requested;
proxy requested=O;

3.1.4.2

Using System Calls
To request proxy, set the SDF_PROXY bit in the sdnJlags field of the
sockaddr_dn structure before issuing the connect call.

EXAMPLE:
In this example, the client program issues a request for proxy access.
-# define SERVERNAME "xyz"
-# define NODE
"55.342"

struct sockaddr dn sockaddr;
struct sockaddr=dn bindaddr;
struct dn naddr *node addr;
char *user_name, *getlogin();
int sock, len, status;

bzero(&sockaddr, sizeof(sockaddr»;
bzero(&bindaddr, sizeof(bindaddr»;
if «(user_name = getlogin(»
user_name = "anonymous";

== NULL)

I I (*user_name

NULL) )

bindaddr.sdn family = AF DECnet;
len = strlen(user name);if (len> sizeof(bindaddr.sdn_objname»
len = sizeof(bindaddr.sdn objname); . .
bindaddr.sdn objnamel = len; strncpy(bindiddr.sdn_objname, user_name, len);

c
Programming in the DECnet Domain 3-7

if (bind (sock, &bindaddr, sizeof(bindaddr»)
{

perror ("bind") ;
exit(l);
sockaddr.sdn flags 1= SDF_PROXY; ~
sockaddr.sdn-family = AF_DECnet;
sockaddr.sdn=objnamel = strlen(SERVERNAME);
strcpy(sockaddr.sdn_objname, SERVERNAME);
node_addr = dnet_addr(NODE);
sockaddr.sdn add

status

*node_addr;

connect (sock, &sockaddr, sizeof(sockaddr»;

COMMENTS:

o Bind a name to the socket before issuing the connect call.
@ If your program is running with superuser privileges, the name you bind
to the socket is used as the source name for proxy access.
NOTE

If you do not bind a name to the socket, or if you issue a connect call
without root privileges, DECnet-ULTRIX uses the user's ID in ASCII
as the source name for proxy access.

3.1.5

Setting Up Optional Data for the Client
Use dnet_conn or system calls to exchange up to 16 bytes of optional data while
a connection is being established.

3.1.5.1

Using dnet_conn
The dnet_conn subroutine lets you specify a buffer containing optional data to
be sent to the server. It also lets you specify a buffer containing any optional
data returned by the server. Mter a client program sends optional data with a
connection request, DECnet flushes the data.
To specify optional data, use the following format:
dnet_conn (node,object,type,opt_out,opt_outl,opt_in,opt_inl)
where
opCout

specifies the address of the outgoing data.

opCoutl

specifies the length of the outgoing data.

opCin

specifies the address of the buffer that will store the optional data
returned by the server.

opCinl

is the address of an integer that specifies the size of that buffer before
the call and will contain the actual number of bytes of optional data
returned by the server on successful completion of dnet_conn.

EXAMPLE 1:

3-8

Programming in the DECnet Domain

You can specify no outgoing optional data to be supplied and no incoming optional
data to be expected. For example, when using a sequenced-packet socket to
connect to object SOAPBOX on node ALEXUS, issue the following call:
s=dnet_conn("alexus", "soapbox", SOCK_SEQPACKET,O,O,O,O);

EXAMPLE 2:
In this example, the client program connects to the network management object
nml (object number 19).
char in data[16], out data[] = {4,0,0}; t)
int in_length, out_length = sizeof(out_data);
int sock;

sock

dnet conn("alexus/root", 8
"#19", 0, 8
out_data, out_length, ()
in_data, &in_length); ~

COMMENTS:
t) This example shows the current version of the NICE protocol used by nml.

8 This call would be issued if you wanted to connect to node ALEXUS as
user ROOT.
6) In this example, a socket type of 0 defaults to SOCK..,SEQPACKET.

o The protocol version number is sent as optional data and a version
number is expected in return.

eD A buffer is provided in which the nml object can return its protocol version
number.
3.1.5.2

Using System Calls
To specify that optional data is to be sent to the server, use the optdata_dn
structure. To set up the connection data to send to the server, use the setsockopt
call.
NOTE

You must set the optional data each time you reissue the connection
request.

EXAMPLE 1:
. In this example, the client program sends three bytes of optional data to the
server.
char version[] = {4, 0, O};

struct optdata_dn out_opt;
int sock;

bzero(&out_opt, sizeof(out_opt»;

Programming in the DECnet Domain

3-9

out opt.opt optl = sizeof(version);
bcopy(versi;n, out_opt.opt_data, out_opt.opt_optl);

if (setsockopt(sock, DNPROTO NSP, DSO CONDATA,
&out_opt , size;f(out_opt»
< 0)
perror("setsockopt");
exit(l);

COMMENTS:

o Defined in the Isys/netdnet/dn.h file.
8 Optional data is copied into the optdata_dn structure. The data length is
also put into this structure.
After the connection has been established, use the getsockopt call to retrieve the
data returned by the server program.

EXAMPLE 2:
In this example, up to 16 bytes of data are placed in in_opt and the data count is
placed in in_opt_len.
struct optdata dn in opt;
int sock, in_opt_len:

bzero(&in_opt, sizeof(in_opt»;
in_opt_len = sizeof(in_opt);
if (getsockopt(sock, DNPROTO_NSP, DSO CONDATA,
&in_opt, &in_opt_len) < 0)
perror("getsockopt");
exit(l);

3.2 How to Establish a Connection for the Server
The DECnet domain supports two methods for programming the server:
•

Use the DECnet object spawner to listen for connection requests on behalf of
your server. When the spawner receives a request for your server, it executes
a copy of your server and redirects standard input and standard output to the
network connection.

•

Use system calls to set up a server that can run independently as a daemon.

You can use either method to perform the following tasks:
•

Specify the socket type: stream or sequenced-packet.

•

Assign a name to the server.

•

Select an accept mode: immediate or deferred.

•

Verify remote user access to the server.

(~
.

3-10

Programming in the DECnet Domain

•

3.2.1

Exchange optional data with client applications.

Choosing a Socket Type for the Server
When writing a server application, you must choose either of the two available
socket types: sequenced-packet or stream. (Table 3-1 compares the characteristics
of each socket type.)
NOTE

Be sure to use the same socket type as for the client application.
3.2.1.1

Using the Network Control Program (NCP)

The DECnet object spawner uses the object database, which consists of entries
defined by the network manager. One of the characteristics defined for the object
entry is the socket type. Use ncp commands to choose between a stream socket
and sequenced-packet socket. For example, to define a stream socket as the
socket type for an object entry, you can use the ncp command set object:
set object object-name type
where

object object-name

Specifies that parameters are to be created or modified for the
named object only (a maximum of 16 alphanumeric characters).

type

is either SOCK_STREAM, if you are specifying a stream
socket, or SOCK_SEQPACKET, if you are specifying a
sequenced-packet socket.

EXAMPLE:

This example shows how to use the set object command to choose a socket type
for object entry myserver.
> ncp ~
ncp> set object myserver type stream

See the DECnet-ULTRIX NCP Command Reference manual for more infonnation
about using ncp commands.
3.2.1.2

Using System Calls

To specify a socket type, use the following fonnat:
s=socket (node, object, type, )
where
type

is either SOCK_STREAM, if you are specifying a stream
socket, or SOCK_SEQPACKET, if you are specifying a
sequenced-packet socket.

EXAMPLE:
This example shows how to use the socket call to specify a socket type.
s=socket (AF_DECnet,SOCK_STREAM,O,);

c
Programming in the DECnet Domain

3-11

3.2.2

Assigning a Name to Your Server
All server applications must have an object name or number associated with
them. Object names contain 1 to 16 alphanumeric characters. Object numbers
range from 0 to 255; however, some numbers are reserved for certain types of
applications. Table 3-2 shows these assignments:
Table 3-2:

Object Number Assig nments

Object
Number

Type of Application

1-127

Reserved for DEC net-supplied programs, such as fal and dlogin.

128-255

Should be used if you are writing a server application that performs a
known network service.

Using the Object Spawner

3.2.2.1

If you have chosen an object number from 1 to 255, you must define your object
name and number in the object database.
EXAMPLE:
In the following example, the ncp set object command defines the Network
Management Listener (nml) as object number 19.
% ncp ~
ncp> set object nml number 19

(For more details, see the DECnet-ULTRIX Network Management manual.)
If your object number is 0, you can define it in the database or the spawner will
use the entry for the default object.
NOTE

The default DECnet object is no longer shipped with a default user
defined for it. Therefore, incoming connections to this object without
valid access-control information or proxy will not be accepted. If you
want to allow unrestricted access to your system through this object,
issue the following ncp command:
%

ncp define object default user guest

In previous DECnet-ULTRIX releases, the process group ID for
processes created by the DECnet spawner was set to O. Starting
with Version 2.2, the process group ID setting is equal to the process
ID setting.
3.2.2.2

Using System Calls

You must specify your object name, object number, or both in a sockaddr_dn
structure. If you are using object number 0, you must also specify an object
name. You can then issue a bind call on the same socket you use to listen for
calls.
EXAMPLE:

3-12

Programming in the DECnet Domain

In this example, 128 is specified as an object number.
int s;
struct sockaddr_dn server;
server.sdn family = AF DECnet;
server.sdn-objnum = 128;
if (bind (s;&server, sizeof(struct sockaddr_dn)}<O}
exit () ;

3.2.3 Selecting Accept-Immediate or Accept-Deferred Modes
The server uses accept-immediate or accept-deferred mode to accept incoming
connections. (See accept(2dn) for details on how to use the accept call to
establish a network connection.)
NOTE

Accept-immediate mode is the default setting for both the DECnet
object spawner and system calls.

(~\
3.2.3.1

Using the Object Spawner

Use the set object command to choose between accept-immediate and
accept-deferred modes for an object entry.
EXAMPLE:
This example shows you how to use the set object command to select
accept-deferred mode for the server, myserver.
% ncp ~
ncp> set object myserver accept deferred

For more information about ncp commands, see the DECnet-ULTRIX NCP
Command Reference manual.

3.2.3.2

Using System Calls

Use the setsockopt call to select accept-immediate or accept-deferred mode.
Specify the ACC_IMMED option to select accept-immediate mode; specify the
ACC_DEFER option to select accept-deferred mode.
EXAMPLE:
In this example, the socket accept mode is set to deferred.
char val = ACC_DEFER;
setsockopt(s,DNPROTO_NSP,DSO_ACCEPTMODE,&val,sizeof(vaI)};

3.2.4 Verifying Remote User Access to the Server

A server can screen incoming connection requests from the client based on the
access-control or proxy information the client supplies;

Programming in the DECnet Domain

3-13

3.2.4.1

Using the Object Spawner
Regardless of the accept mode chosen for the server, the spawner verifies
access-control information or proxy information that the client supplies. The
spawner also rejects or processes connection requests based on the following
conditions:
•

If the information is invalid, the spawner rejects the connection request.

•

If the information is valid, the spawner processes the connect request
according to the accept mode specified for the server in the object database.

•

If immediate mode was specified, the spawner accepts the request and
initiates the server.

•

If deferred mode was specified, the spawner initiates the server. The server
must then use the setsockopt call with either the DSO_CONACCEPT or
DSO_CONREJECT option to either accept or reject the request.

See Section 2.3 for more information about how the object spawner uses
access-control or proxy information.

3.2.4.2

Using System Calls
If you are not using the spawner to process requests for the server, you can use
the getsockopt system call to screen requests. If the server is bound and it is
listening on a specific address for its own connection requests, it can verify access
to the service based on incoming access-control information or proxy.
EXAMPLE:

In this example, the getsockopt call retrieves incoming access-control
information.

struct accessdata_dn acc_data;
getsockopt(s,DNPROTO_NSP,DSO_CONACCESS,&acc_data,sizeof(acc_data»;

NOTE

A process has access to data in the password field of the accessdata_dn
structure only if it is running with superuser privileges. If not, the
password field of the accessdata_dn structure will be null.

3.2.5

Exchanging Optional Data
In the DECnet domain, client and server can exchange up to 16 bytes of optional
data during the connection and disconnection processes. Both server and client
interpret this data according to an application-specific design. The following steps
describe how the client and server applications exchange optional data:
1. Before the server can read optional connection data, you must ensure that the
socket is in accept-deferred mode.

2. If the server is going to accept the connection, use the setsockopt call with
the DSO_CONDATA option to specify the outgoing optional data.
3. To accept the connection, issue the setsockopt call with the
DSO_CONACCEPT option.
4. If the server is going to reject the connection, specify outgoing optional data
using the setsockopt call with the DSO_DISDATA option.

3-14

Programming in the DEC net Domain

5. 1b reject the connection, issue the setsockopt call with the
DSO_CONREJECT option.

EXAMPLE 1:
This example shows how the optdata_dn structure specifies optional data before
accepting or rejecting a connection.
struct optdata_dn optional;
char message[] = { 1, 2, 3, 4, 5 };
bzero(&optional, sizeof(optional»;
bcopy(message, optional.opt_data, sizeof(message»;
optional.opt_optl = sizeof(message);

EXAMPLE 2:
In this example, the server program sends optional data and accepts a connection.
setsockopt(sock, DNPROTO NSP, DSO_CONDATA, &optional,
sizeof(optional»;
setsockopt(sock, DNPROTO_NSP, DSO_CONACCEPT, 0, 0);

EXAMPLE 3:
In this example, the server program sends optional data and rejects a connection.
setsockopt(sock, DNPROTO NSP, DSO_DISDATA, &optional,
sizeof(optional»;
setsockopt(sock, DNPROTO_NSP, DSO_CONREJECT, 0, 0);

3.3 Transferring Data After Establishing a Connection
Mter establishing a connection, the client and server applications use their
sockets to send and receive data via the send, recv, write, and read system calls.
NOTE

If you are using the DECnet object spawner, standard input and
standard output are redirected to the network connection.

DECnet-ULTRIX software supports the following services during data transfer
between client and server applications:

3.3.1

•

Blocking or nonblocking input/output modes

•

Out-of-band messages

•

Zero-length message detection on sequenced packet sockets

Using Blocking or Nonblocking I/O
Blocking mode is the default mode for ULTRIX software. Unless otherwise
specified, an ULTRIX read call blocks a calling process until data is available
for the read operation, and an ULTRIX write call blocks a calling process until
enough resources are available to buffer data for the write operation.

If no data is available when a read call is issued, or if there are not enough
resources to buffer data for a write operation, a nonblocking 1/0 call returns
control to the calling process immediately with an EWOULDBLOCK message.
Otherwise, the calling procedure regains control as soon as the read or write
operation completes.
Programming in the DECnet Domain

3-15

EXAMPLE:

To set up the nonblocking I/O mode, include the ULTRIX. fcntl(2) system call in
the beginning of your application, as follows:
fcntl(sock,F_SETFL,FNDELAY);

3.3.2

Using Out-of-Band Messages
An application can send an out-of-band message from 1 to 16 bytes long ahead of
normal data messages. However, it can send only one out-of-band message over a
socket at a time.

The receiving application must read any pending out-of-band message before the
sending program can send another. The signal SIGURG indicates the arrival of
out-of-band data.

To send or receive an out-of-band message, an application must specify the
MSG_OOB flag with the send or recv call, depending on the following conditions:
•

The send call specifies the socket used to send an out-of-band message and
the buffer used to contain the message.

•

The recv call specifies the socket used to receive an out-of-band message and
the buffer used to contain the message.

EXAMPLE 1:

In this example, the application sends "buffer" as an out-of-band message:
char buffer[] = { 1, 2, 3, 4, 5 };
send(sock, buffer, sizeof(buffer), MSG_OOB);

You can also use the select call to wait for out-of-band data. When the select call
returns and indicates that an out-of-band message is present, you can use a recv
call to read the message.

EXAMPLE 2:
In this example, the application uses the select call to determine if out-of-band
data has arrived.

int EMask;
EMask = l«sock;
select (sock+1, (int *)0,

(int *)0, &EMask,

(struct timeval *)0);

if( EMask & l«sock
msgsize = recv(sock, buffer, sizeof(buffer) , MSG_OOB);

3.3.3

Detecting Zero-Length Messages
On a sequenced-packet socket, a returned value of zero on a read operation
indicates that either the end of the file has been reached or a zero-length message
has been received. An end-of-file status on a socket indicates that the logical link
was disconnected and communication over the socket is not possible.

To distinguish between an end-of-file message and a zero-length packet, use
the dnet_eof subroutine. If the return value from the dnet_eof call is zero,
a zero-length packet has been received. Otherwise, the logical link has been
disconnected.
EXAMPLE:
3-16

Programming in the DECnet Domain

This example shows how to use dnet_eof to distinguish zero-length messages
from end-of-file messages.

(

"'"

I,~

/* Read the next packet on a DECnet sequenced packet socket */
length = read(sock, buff, buffsize);
if( length == -1 )
/* read failed, refer to read(2dn) for more information */
else if( length == 0 && dnet eof(sock) )
/* End Of File has been reached */
/* If here, then we have successfully read a packet */

3.4 How to Disconnect a DECnet Connection
Either the client or the server application can initiate the disconnection of a
DECnet connection. The application that initiates the disconnection can also
specify the optional disconnect data to send to the other application.
'1b disconnect a DECnet connection:

1. Before initiating the disconnection, the application can specify between 1 and
16 bytes of optional disconnection data by issuing a setsockopt call with a
DSO_DISDATA option.

2. The application either closes all references to the DECnet socket or issues
a single shutdown call to request disabling of the send or send and recv
operations. The shutdown call is used when the application is set to reference
the DECnet socket after the connection is terminated.
3. If an application does not initiate the disconnection, it can retrieve the
optional disconnection data sent by the application that initiated the
disconnection. The application can issue a getsockopt call with the
DSO_DISDATA option.
EXAMPLE 1:
In this example, the application terminates the DECnet connection while sending
optional disconnection data.
struct optdata_dn disdata;
char message[] = {I, 2, 3, 4, 5};

/* Prepare optional disconnect data */
bzero(&disdata, sizeof(disdata»;
bcopy(message, disdata.opt data, sizeof(message»;
disdata.opt_optl = sizeof(;essage);
setsockopt (sock, DNPROTO_NSP, DSO_DISDATA, &disdata,sizeo f(disdata»S ();
close(sock);

EXAMPLE 2:
In this example, the application determines that the DECnet connection has
been terminated, and retrieves any optional data that may have been sent by the
application that terminated the connection.
struct optdata dn disdata;
int length;
length = read(sock, buff, buffsize);

/* Check to see if the connection has been disconnected */
if(length == 0 && dnet_eof(sock»
{

int structsize;

Programming in the DECnet Domain

3-17

/* Retrieve any optional disconnect data that was sent */
structsize = sizeof(disdata);
getsockopt(sock,DNPROTO_NSP,DSO_DISDATA,&disdata,&structsize);
/* No longer need the socket descriptor. Closing it will free
up local network resources that were associated with it */
close(sock);

NOTE

The successful completion of a write call does not necessarily indicate
that the data has already been sent to the remote node. A successful
write operation means that the local system has accepted the data and
will transmit it as soon as possible.
The effect of issuing a close call while data that has not been sent is
queued for a remote application depends on the value of the LINGER
option, which is set through the setsockopt call. If the SO_LINGER
option is set, the close operation will be delayed while an attempt
is made to send or acknowledge all data. Otherwise, the data in the
queue is eliminated and the system processes the close operation with
an abort condition.

3-18

Programming in the DECnet Domain

/-~

("-;

c
Part II

Reference

c
Chapter 4

DECnet-ULTRIX System Calls
This reference chapter describes DECnet-ULTRIX system calls in detail. The
format for this information corresponds to that in the ULTRIX reference pages.
See the ULTRlX Reference manuals for more information about format.
Each system call begins a separate page in alphabetical order. The name of
the system call appears in a running head followed by the appropriate section
nwnber and a suffix. For example, accept(2dn) appears on the reference pages
describing the accept call. The 2 indicates that the section describes system calls.
The dn indicates that the system call is used in the DECnet domain.

c'
4.1

System Call Summary
Table 4-1 swnmarizes the function of each DECnet-ULTRIX system call.
Table 4-1: DECnet-ULTRIX System Calls

System Call

Function

accept
bind
close
connect
getpeername
getsockname
getsockopt
listen
read
recv
select
send
setsockopt
shutdown
socket
write

Accepts a connection request.
Binds a name to a socket.
Terminates a logical link and deactivates a socket descriptor.
Initiates a connection request.
Returns the name of the peer connected to a socket.
Returns the current name of a socket.
Returns the options associated with a socket.
Listens for pending connection requests.
Reads (receives) data.
Receives normal data and out-of-band messages.
Performs synchronous I/O multiplexing.
Sends data and out-of-band messages.
Sets socket options.
Shuts down a DEC net connection.
Creates a new socket.
Writes (sends) data.

C
DECnet-ULTRIX System Calls

4-1

4.2 On-Line Manual Pages
The system call descriptions also appear as on-line documentation in accept(2dn),
bind(2dn), close(2dn), and so on.

4.3 Format and Conventions
The descriptions of the DECnet-ULTRIX. system calls have the following format:
SYNTAX

Gives the complete syntax for the system call. The following conventions
apply to syntax lines:
command

Indicates terms that are constant and must be typed
exactly as presented.
Indicates that the preceding item can be repeated one or
more times.

italics

Indicate a variable, for which either you or the system
must specify a value.

The default user prompt in multiuser mode.

The default superuser prompt.

DESCRIPTION
Supplies function and background information.
RETURN VALUE
Explains the meaning of a value returned by a utility when it completes or
does not complete an operation.
DIAGNOSTICS
Lists diagnostic messages that can be returned.
RESTRICTIONS
Describes restrictions that apply to the use of the system call or subroutine.

c
4-2

OECnet-ULTRIX System Calls