OSF™DCE Application Development Guide

Application Development Guide

OPEN S O F T W A R E F O U N D A T I O N

OSF™ DeE Application Development Guide

Revision

1.

Open Software Foundation

-I ^~T-

Published by Prentice-Hall, Inc.

A Simon & Schuster Company Englewood Cliffs, New Jersey 07632

The information contained within this document is subject to change without notice.

OSF MAKES NO WARRANTY OF ANY KIND WITH REGARD TO THIS MATERIAL, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.

OSF shall not be liable for errors contained herein, or for any direct or indirect, incidental, special or consequential damages in connection with the furnishing, performance, or use of this material.

Copyright ©1993 Open Software Foundation, Inc.

This documentation and the software to which it relates are derived in part from materials supplied by the following:

• © Copyright 1990, 1991 Digital Equipment Corporation

• © Copyright 1990, 1991 Hewlett-Packard Company

• © Copyright 1989, 1990, 1991 Transarc Corporation

• © Copyright 1990, 1991 Siemens Nixdorf Informationssysteme AG

• © Copyright 1990, 1991 International Business Machines Corporation

• © Copyright 1988, 1989 Massachusetts Institute of Technology

• © Copyright 1988, 1989 The Regents of the University of California

All rights reserved.

Printed in the U.S.A.

Printed in the United States of America 10 9 8 7 6 5 4 3 2 1

ISBN: 0-13-643826-1

Prentice-Hall International (UK) Limited, London Prentice-Hall of Australia Pty. Limited, Sydney Prentice-Hall Canada Inc., Toronto

Prentice-Hall Hispanoamericana, S.A., Mexico Prentice-Hall of India Private Limited, New Delhi Prentice-Hall of Japan, Inc., Tokyo

Simon & Schuster Asia Pte. Ltd., Singapore Editora Prentice-Hall do Brasil, Ltda., Rio de Janeiro

THIS DOCUMENT AND THE SOFTWARE DECRIBED HEREIN ARE FURNISHED UNDER A LICENSE, AND MAY BE USED AND COPIED ONLY IN ACCORDANCE WITH THE TERMS OF SUCH LICENSE AND WITH THE INCLUSION OF THE ABOVE COPYRIGHT NOTICE. TITLE TO AND OWNERSHIP OFTHE DOCUMENT AND SOFTWARE REMAIN WITH OSF OR ITS LICENSORS.

Open Software Foundation, OSF, the OSF logo, OSF/1, OSF/Motif, and Motif are trademarks of the Open Software Foundation, Inc.

UNIX is a registered trademark of UNIX System Laboratories, Inc. in the U.S. and other countries.

DEC, DIGITAL, and ULTRIX are registered trademarks of Digital Equipment Corporation.

DECstation 3100 is a trademark of Digital Equipment Corporation.

HP, Hewlett-Parkard, and LaserJet are trademarks of Hewlett-Packard Company.

Network Computing System and PasswdEtc are registered trademarks of Hewlett-Packard Company.

AFS and Transarc are registered trademarks of the Transarc Corporation.

Episode is a trademark of the Transarc Corporation.

AIX and RISC System/6000 are trademarks of International Business Machines Corporation.

IBM is a registered trademark of International Business Machines Corporation.

DIR-X is a trademark of Siemens Nixdorf Informationssysteme AG.

NFS, Network File System, SunOS and Sun Microsystems are trademarks of Sun Microsystems, Inc.

X/Open is a trademark of the X/Open Company Limited in the U.K. and other countries.

PostScript is a trademark of Adobe Systems Incorporated.

FOR U.S. GOVERNMENT CUSTOMERS REGARDING THIS DOCUMENTATION AND THE ASSOCIATED SOFTWARE.

These notices shall be marked on any reproduction of this data, in whole or in part.

NOTICE: Notwithstanding any other lease or license that may pertain to, or accompany the delivery of, this computer software, the rights of the Government regarding its use, reproduction and disclosure are as set forth in Section 52.227-19 of the FARS Computer Software-Restricted Rights clause.

RESTRICTED RIGHTS NOTICE: Use, duplication, or disclosure by the Government is subject to the restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 52.227-7013.

RESTRICTED RIGHTS LEGEND: Use, duplication or disclosure by the Government is subject to restrictions as set forth in paragraph (b)(3)(B) of the rights in Technical Data and Computer Software clause in DAR 7-104.9(a).

This computer software is submitted with "restricted rights." Use, duplication or disclosure is subject to the restrictions as set forth in NASA FAR SUP 18-52.227-79 (April 1985) "Commercial Computer Software-Restricted Rights (April 1985)." If the contract contains the Clause at 18-52.227-74 "Rights in Data General" then the

"Alternate III" clause applies.

US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract.

Unpublished - All rights reserved under the Copyright Laws of the United States.

This notice shall be marked on any reproduction of this data, in whole or in part.

Contents

Preface .

Audience Applicability Purpose.

Document Usage . Related Documents

Typographic and Keying Conventions Problem Reporting

Pathnames of Directories and Files in DCE Documentation

Part 1. Overview of DeE Application Development

Chapter 1. DCE Application Development Steps. .

1.1 Introduction to DCE Application Development .

xxxix xxxix xl xl xl xli xli xlii xlii

1-1 1-1

1.2 Content Overview of Part 1 . . . 1-2

1.2.1 Topics Covered in Part 1 . 1-2

1.2.2 Topics Not Covered in Part 1 1-3

1.3 DCE Application Development 1-4

1.4 Overview of the DCE Application Development

Steps 1-6

1.5 The DCE Application Development Steps 1-10

1.5.1 Step AI/Client and Server: Generate the Interface

UUID. . . • . 1-10

1.5.2 Step A2/Client and Server: Determine the Interface

Version Number 1-11

OSF DeE Application Development Guide

ii

1.5.3 1.5.4 1.5.5 1.5.6 1.5.7 1.5.8 1.5.9 1.5.10 1.5.11 1.5.12 1.5.13 1.5.14 1.5.15 1.5.16 1.5.17 1.5.18 1.5.19 1.5.20 1.5.21 1.5.22 1.5.23 1.5.24 1.5.25 1.5.26 1.5.27

Step A3/Client and Server: Write the .idl

File .

Step A4/Client and Server: Write the .acf File

Step A5/Client and Server: Process the Files with the

IDL Compiler . . .

Step B l/Server: Define the Manager

EPVs • • . • • . . •

Step B2/Server: Register the Objectffype UUID Associations with the RPC Runtime • • . Step B3/Server: Register the Interface, Type UUID,

and EPV with RPC Runtime .

Step B4/Server: Specify

Multithreadedness. •

Step B5/Server: Tell RPC Runtime What Protocol

Sequences to Use .

Step B6/Server: Request for Bindings from RPC

Runtime . . .

Step B7/Server: Register the Authentication Information with RPC Runtime . Step B8/Server: Establish the Server Principal

Identity • • . . • •

Step B9/Server: Plan What To Do When the Server

Terminates . .

Step B 10/Server: Register the Binding Information

with the Endpoint Mapper •

Step B II/Server: Export the Binding Information to

the N amespace (CDS) .

Step B 12/Server: Listen for Incoming Service

Requests . • . .

Step Cl/Client: Import the Binding Information from

the Namespace (CDS) • . . • •

Step C2/Client: Annotate the Binding Handle for

Security • . .

Step C3/Client: Invoke an RPC Interface

Operation •

Step Dl/Server: Wake Up in Manager Routine •

Step D2/Server: Get the Client's PAC Step D3/Server: Get the Object's ACL • Step D4/Server: Make the Authorization

Decision • • • • . •

Step D5/Server: Service the Request . Step D6/Server: Return the Results to the

Client. . • . •

Step D7/Server: Continue the Listen

L o o p . •

1-12 1-14 1-18 1-19 1-20 1-22 1-31 1-32 1-35 1-35 1-36 1-37 1-39 1-42 1-42 1-43 1-46 1-48 1-51 1-51 1-52 1-53 1-54 1-55 1-55 OSF DeE Application Development Guide

1.5.28 Step El/Client: Wake Up After the RPC Call • . . • . . . . • . 1.5.29 Step E2/Clierit: Continue . . . . • . Chapter 2. Guidelines for Server Writers

2.1 Using the Name Service Interface 2.1.1 Introduction to Using NSI 2.1.2 Binding to an Object 2.1.3 Junctions. . . . 2.1.4 Name Service Terminology 2.1.5 Binding • . . . . • . 2.1.6 Partial Binding and the Endpoint

Mapper . • . . . • . . 2.1.7 Interface Ambiguity and Partial

Bindings . . • . . . • . 2.1.8 Using Object UUIDs to Avoid Binding

Ambiguity . . . • . . 2.1.9 An Object-Oriented Namespace . 2.1.10 Setting Up an Object-Oriented

Namespace. . . • . . . . • . 2.1.11 Groups and Profiles .

2.1.12 Three Models for Accessing Binding Information . . . . • . . • .

.

2.1.13 Models Based on Non-CDS Databases • . • • 2.1.14 An Object-Oriented Model with Grouped Binding

Information . • . . . 2.1.15 Server and Client Steps 2.1.16 Global Organization of the

Namespace . . . . • . 2.2 Thread-Safe Programming . . . .

2.2.1 Introduction to Thread-Safe 2.2.2

2.2.3 2.2.4 2.2.5 2.2.6 2.2.7 2.2.8 2.2.9 2.2.10

Programming . . • . . . . What Thread-Safe Means. .

Making Code Thread-Safe

How Code Becomes Multithreaded . Memory Management in Threads Mutexes . . . . • • . . . Methods for Synchronizing Threads Thread-Specific Storage

Other Programming Consideratibns. . DCE Threads and DCE RPC . . 2.3 Managing the Server's Authentication Key •

2.3.1 Introduction to Authentication 2.3.2 Server Key Storage and Retrieval 2.3.3 Setting Up the Server Key File 2.3.4 Acquiring a Login Context OSF DeE Application Development Guide

Contents

1-56 1-56 2-1 2-1 2-2 2-6 2-6 2-9 2-13 2-15 2-17 2-19 2-23 2-24 2-27 2-29 2-32 2-34 2-35 2-42 2-43 2-43 2-44 2-47 2-49 2-49 2-50 2-55 2-57 2-58 2-60 2-61 2-61 2-63 2-64 2-65 iii

2.3.5 Using the Key . . . . 2.3.6 Typical Tasks in Managing the Key 2.3.7 Key Management Routines

2.4 Writing an ACL Manager . . . . 2.4.1 Introduction to Writing an ACL

Manager . . . .

2.4.2 Design Guidelines . . . . 2.4.3 How ACL Interfaces Work in the Registry

Server . . . . 2.4.4 IDL Definitions. . . . 2.4.5 Representation of Objects with ACLs in the

Namespace . . . . . . . . . . 2.5 Additional Guidelines . . . .

2.5.1 Initialization and Configuration . . 2.5.2 Availability and Performance of

Services . . .

2.5.3 Management . . . . Chapter 3. A Sample DCE Application. . . . . . . . .

3.1 Developing a DCE Application

3.2

3.1.1 The Purpose of Stub Files . 3.1.2 IDL Output Default Filenames

A Complete Sample Application: timop . . . . 3.2.1 What timop Does . . . . 3.2.2 The timop Program and Security

3.2.3 Source Files. .

3.2.4 Building timop . . . . . 3.2.5 Running timop . . . . . 3.2.6 Stopping timop . . . . .

3.2.7 Further Exercises . . . . 3.2.8 The timop Program: A Sample DCE

Application . . . .

Part 2. DeE Threads

Chapter 4. Introduction to Multithreaded Programming. . 4.1 Advantages of Using Threads

4.2 Software Models for Multithreaded Programming . . . . . 4.2.1 Boss/W orker Model 4.2.2 Work Crew Model . .

4.2.3 Pipelining Model . . . . 4.2.4 Combinations of Models .

2-65 2-68 2-70 2-72 2-72 2-73 2-73 2-77 2-78 2-79 2-80 2-86 2-87 3-1 3-1 3-5 3-5 3-6 3-6 3-7 3-8 3-9 3-9 3-10 3-10 3-11

4-1 4-2 4-3 4-3 4-3 4-4 4-5

iv OSF DeE Application Development Guide

4.3 Potential Disadvantages with Multithreaded Programming . .

Chapter 5. Thread Concepts and Operations 5.1 Thread Operations •

5.1.1 Starting a Thread . 5.1.2 Terminating a Thread .

5.1.3 Waiting for a Thread to Terminate 5.1.4 Deleting a Thread .

5.2 Attributes Objects . . . 5.2.1 Creating an Attributes Object 5.2.2 Deleting an Attributes Object 5.2.3 Thread Attributes

5.2.4 Mutex Attributes .

5.2.5 Condition Variable Attributes 5.3 Synchronization Objects

5.3.1 Mutexes. . . 5.3.2 Condition Variables

5.3.3 Other Synchronization Methods . 5.4 One-Time Initialization Routines . 5.5 Thread-Specific Data

5.6 Thread Cancellation . 5.7 Thread Scheduling Chapter 6. Programming with Threads .

6.1 Calling UNIX Services 6.1.1 Jacket Routines. . 6.1.2 Blocking System Calls

6.1.3 Calling fork() in a Multithreaded Environment

6.2 Using Signals .

6.2.1 Types of Signals .

6.2.2 DCE Threads Signal Handling 6.2.3 Alternatives to Using Signals 6.3 Nonthreaded Libraries . • .

6.3.1 Working with Nonthreaded Software . 6.3.2 Changing Nonthreaded Code to be Thread-

Reentrant

6.4 Avoiding Nonreentrant Software 6.4.1 Global Lock. . . 6.4.2 Thread-Specific Storage 6.5 Avoiding Priority Inversion • OSF DeE Application Development Guide

Contents

4-5 5-1 5-2 5-2 5-3 5-3 5-4 5-4 5-5 5-5 5-6 5-9 5-9 5-9 5-10 5-12 5-15 5-15 5-16 5-17 5-18 6-1 6-2 6-2 6-5 6-5 6-7 6-7 6-9 6-10 6-11 6-12 6-12 6-13 6-13 6-14 6-14 v

6.6 Using Synchronization Objects 6.6.1 Race Conditions

6.6.2 Deadlocks . . • . 6.7 Signaling a Condition Variable

Chapter 7. Using the DCE Threads Exception-Returning Interface • . . . . • . . . . • 7.1 Syntax for C

7.2 Invoking the Exception-Returning Interface 7.3 Operations on Exceptions . . . . .

7.3.1 Declaring and Initializing an Exception Object . . . . . • .

7.3.2 Raising an Exception . . • • . . • • • 7.3.3 Defining a Region of Code Over Which Exceptions

Are' Caught . . • . . . . . 7.3.4 Catching a Particular Exception or All

Exceptions . . . • • .

7.3.5 Defining Epilogue Actions for a Block . • . . 7.3.6 Importing a System-Defined Error Status into the

Program as an Exception . . . 7.4 Rules and Conventions for Modular Use of Exceptions. • . ' . . . . . 7.5 DCE Threads Exceptions and Definitions Chapter 8. DCE Threads Example . . . .

8.1 Details of Program Logic and Implementation .

Part 3. DCE Remote Procedure Call

Part 3A. Using Remote Procedure Call

Chapter 9. Introduction to Remote Procedure Calls

9.1 General Requirements for Distributing an Application

9.2 The RPC Model

9.2.1 RPC Interfaces . . 9.2.2 RPC Services 9.2.3 RPC Objects

9.3 The Parts of an RPC Application 9.3.1 RPC Application Code

6-15 6-15 6-16 6-16 7-1 7-2 7-4 7-5 7-5 7-6 7-6 7-7 7-7 7-8 7-8 7-11 8-1 8-2

9-1 9-2 9-4 9-4 9-6 9-7 9-8 9-9

vi OSF DeE Application Development Guide

9.3.2 Stubs. . 9.3.3 The RPC Runtime .

9.4 DCE RPC and the Distributed Computing Environment

9.5 Overview of DCE RPC Development Tasks . Chapter 10. Basic DCE RPC Components

10.1 DCE UUID Generator

10.2 DCE RPC Interface Definition Language . 10.3 DCE IDL Compiler

10.4 DCE RPC Daemon

10.5 Network Data Representation Transfer Syntax . 10.6 DCE RPC Runtime . .

10.6.1 Communications Operations 10.6.2 Directory Service Interface

Operations . . 10.6.3 Endpoint Operations

10.6.4 Authentication Operations . . 10.6.5 Miscellaneous Runtime Operations . 10.7 DCE RPC Control Program .

Chapter 11. Building an Application .

11.1 Writing an Interface Definition . 11.1.1 Generating an Interface UUID 11.1.2 Naming the Interface . . . . 11.1.3 Specifying Interface Attributes 11.1.4 Import Declarations

11.1.5 Constant Declarations . 11.1.6 Type Declarations . 11.1.7 Operation Declarations 11.1.8 The binop Interface Definition 11.2 Running the IDL Compiler .

11.3 Writing the Client Code. .

11.3.1 Overview of the binop Client Program 11.3.2 The client.c Source Code .

11.4 Writing the Server Code. •

11.4.1 Overview of the binop Server Program . 11.4.2 The server.c Source Code .

11.4.3 The manager.c Source Code 11.5 A Sample binop Application . .

11.5.1 Building the binop Programs . OSF DeE Application Development Guide

Contents

9-9 9-10 9-12 9-13 10-1 10-2 10-3 10-6 10-8 10-9 10-9 10-10 10-11 10-11 10-11 10-12 10-13 11-1 11-1 11-2 11-4 11-4 11-5 11-5 11-6 11-7 11-8 11-9 11-10 11-10 11-11 11-13 11-13 11-14 11-17 11-18 11-18 vii

11.5.2 Running the binop Programs . Chapter 12. Effects of Remoteness

12.1 Direct Implications of Remoteness 12.2 Communications Protocols . 12.3 Universal Unique Identifiers

12.4 Binding Information • . . . 12.4.1 Server Binding Information

12.4.2 Defining a Compatible Server . • • 12.4.3 Obtaining Binding Information of a Compatible

Server . . . . • 12.4.4 Client Binding Information

12.5 Endpoints . .

12.5.1 Well-Known Endpoints 12.5.2 Dynamic Endpoints 12.6 Context Handles

12.7 Execution Semantics. . 12.8 Communications Failures 12.9 Scaling .

Chapter 13. Basic DCE RPC Runtime Operations • 13.1 Overview of Basic Operations .

13.2 Basic Tasks of an Unauthenticated Remote Procedure Call •

13.3 Basic Runtime Routines . 13.4 Server Initialization Tasks .

13.4.1 Assigning Types to Objects 13.4.2 Registering Interfaces • •

13.4.3 Selecting RPC Protocol Sequences . 13.4.4 Obtaining a List of Server Binding

Handles . .

13.4.5 Registering Endpoints. . . .

13.4.6 Making Binding Information Accessible to Clients

13.4.7 Listening for Calls . 13.5 Methods for Managing Bindings

13.6 Obtaining Server Binding Handles . . . . 13.6.1 Using String Bindings to Obtain Binding

Information .

13.6.2 Searching a Namespace

11-19 12-1 12-2 12-3 12-4 12-5 12-6 12-8 12-10 12-14 12-16 12-16 12-17 12-18 12-19 12-21 12-21 13-1 13-2 13-4 13-6 13-7 13-8 13-10 13-13 13-13 13-14 13-15 13-18 13-19 13-23 13-23 13-24

viii OSF DeE Application Development Guide

13. 7 Using Authenticated RPC 13.7.1 Authentication . 13.7.2 Authorization . .

13.7.3 Authenticated RPC Routines . Chapter 14. Advanced DCE RPC Topics

14.1 Advanced Name Service Interface Topics

14.1.1 Structure ofNSI Name Service Entries: NSI Attributes • . .

14.1.2 Searching the Namespace for Binding Information . .

14.2 Threads of Execution in RPC Applications 14.2.1 Remote Procedure Call Threads . 14.2.2 Cancels . .

14.2.3 Multithreaded RPC Applications 14.3 Nested Remote Procedure Calls

14.4 Routing Remote Procedure Calls 14.4.1 Obtaining an Endpoint 14.4.2 Buffering Call Requests 14.4.3 Queuing Incoming Calls 14.4.4 Selecting a Manager Chapter 15. Name Service Interface Usage .

15.1 NSI Directory Service Entries . 15.1.1 Structure of Entry Names . 15.1.2 Server Entries

15.1.3 Groups

15.1.4 Profiles • •

15.1.5 Guidelines for Constructing Names of Directory Service Entries .

15.1.6 Selecting the Starting Entry 15.1.7 Environment Variables

15.2 Strategies for Using Directory Service Entries 15.2.1 Using Server Entries

15.2.2 Using Groups 15 .2.3 Using Profiles

15.3 Models for Defining RPC Servers . 15.3.1 Service Model

15.3.2 Resource Model Chapter 16. Guidelines for Error Handling .

16.1 Exceptions •

16.2 The fault_status Attribute 16.3 The comm_status Attribute OSF DeE Application Development Guide

Contents

13-27 13-28 13-30 13-32 14-1 14-1 14-2 14-4 14-14 14-15 14-18 14-20 14-22 14-25 14-27 14-32 14-33 14-36 15-1 15-2 15-2 15-4 15-6 15-8 15-11 15-16 15-16 15-17 15-17 15-18 15-20 15-21 15-22 15-29 16-1 16-2 16-3 16-3 ix

1604 Determining Which Method to Use for Handling Exceptions . . . • . . . . 16.5 Examples of Error Handling . • . .

16.5.1 The Matrix Math Server Example 16.5.2 The Stock Quote Application

Example . . . .

Part 3B. Language Syntax and Usage

Chapter 17. Interface Definition Language . .

17.1 The Interface Definition Language File 17.2 Syntax Notation Conventions

17.2.1 Typography . . . 17.3

1704

17.2.2 Special Symbols . . . . IDL Lexical Elements

17.3.1 Identifiers . . . . 17.3.2 Keywords . • . • . 17.3.3 Punctuation Characters

17.304 White Space . . • . 17.3.5 Case Sensitivity

IDL Versus C . . . 1704.1 Declarations 1704.2 Data Types 1704.3 Attributes

17.5 Interface Definition Structure 17.5.1 Interface Definition Header 17.5.2 Interface Definition Body . 17.6 Overview of IDL Attributes

17.7 Interface Definition Header Attributes 17.7.1 The uuid Attribute . . • . . 17.7.2 The version Attribute . . . . 17.7.3 The endpoint Attribute

17.704 The pointer_default Attribute

17.7.5 The local Attribute. . . • • • . 17.7.6 Rules for Using Interface Definition Header

Attributes • . . • • . . 17.7.7 Examples of Interface Definition Header

Attributes • . • • • . 17.8 Import Declarations

17.9 Constant Declarations . . • . • . 17.9.1 Integer Constants

16-4 16-5 16-5 16-6

17-1 17-1 17-2 17-2 17-2 17-3 17-3 17-4 17-4 17-4 17-5 17-5 17-6 17-6 17-6 17-7 17-7 17-7 17-8 17-9 17-10 17-10 17-12 17-13 17-13 17-14 17-14 17-14 17-15 17-16

x OSF DeE Application Development Guide

17.9.2 Boolean Constants . . . .

17.9.3 Character Constants . . . • • . . • . 17.9.4 String Constants . • • . . • . • . . 17.9.5 NULL Constants . • . • • • . • . . 17.10 Type Declarations . • . . • . • • . • 17.10.1 Type Attributes . . . . . 17.10.2 Base Type Specifiers . . . . 17.1 0.3 Construct~d Type Specifiers . • . . • 17.10.4 Predefined Type Specifiers . . • • • • • 17.10.5 Type Declarator . . • . • . . 17.11 Operation Declarations . . . . . . .

17.11.1 Operation Attributes . • . • 17.11.2 Operation Attributes: idempotent, broadcast, and

maybe . . . .

17.12 Parameter Declarations .

17.13 Basic Data Types . • . . . • . . • . • . • 17.13.1 Integer Types . . . . 17.13.2 Floating-Point Types . . • . . . . 17.13.3 The char Type . . . . • . . . . 17.13.4 The boolean Type . • . . • . . . . . 17.13.5 The byte Type . . • . • . . . 17.13.6 The void Type. . . • • . . . . 17.13.7 The handle_t Type •

17.13.8 The error_status_t Type

17.13.9 International Characters • • • • . • . • 17.14 Constructed Data Types .

17.14.1 Structures 17.14.2 Unions

17.14.3 Enumerations . . . • . . . 17.14.4 Pipes .

17.14.5 Arrays 17.14.6 Strings

17.14.7 Pointers . . • . • • . • • . . 17.14.8 Customized Handles . . . • 17.14.9 Context Handles

17.15 Associating a Data Type with a Transmitted

Type . . . •

17.16 Migration Attributes . . . . 17.16.1 The v I_array Attribute 17.16.2 The vI enum Attribute 17.16.3 The v1=string Attribute 17.16.4 The v l_struct Attribute Chapter 18. Attribute Configuration Language OSF DeE Application Development Guide

Contents

17-16 17-17 17-17 17-17 17-18 17-18 17-19 17-20 17-20 17-21 17-21 17-22 17-22 17-23 17-25 17-25

17~26

17-26 17-26 17-27 17-27 17-28 17-28 17-29 17-30 17-30 17--,.32 17-34 17-34 17-41 17-47 17-48 17-64 17-66 17-72 17-75 17-75 17-76 17-76 17-76 18-1 xi

18.1 Syntax Notation Conventions 18.2 Attribute Configuration File

18.2.1 Naming the ACF

· ^.

18.2.2 Compiling the ACF

18.2.3 ACF Features

. ·

18.3 Structure

. . .

18.3.1 ACF Interface Header

. . ·

18.3.2 ACF Interface Body 18.3.3 The include Statement 18.3.4 The auto_handle Attribute 18.3.5 The explicit_handle Attribute 18.3.6 The implicit_handle Attribute 18.3.7 The comm_status and fault_status

Attributes

. . · ·

18.3.8 The code and nocode Attributes 18.3.9 The in_line and oueof_line Attributes 18.3.10 The represent_as Attribute

.

18.3.11 The enable_allocate Attribute 18.3.12 The heap Attribute

18.4 Summary of Attributes

· .

Part 3C. Supplemental Information

Chapter 19. Summary of Runtime Routines. . . . . 19.1 Summary ofRPC Stub-Support Routines . 19.2 Summary ofRPC Runtime Routines Chapter 20. Language Grammar Synopsis

20.1 Interface Definition Language . .

· .

18-1 18-2 18-2 18-2 18-3 18-3 18-4 18-5 18-6 18-6 18-8 18-10 18-11 18-14 18-15 18-17 18-20 18-21 18-23

19-1 19-1 19-2 20-1 20-1

20.2 Attribute Configuration Language 20-9

Chapter 21. Using NCS in a DCE RPC Environment • . • . . 21-1

21.1 Using Compatibility Features . • • . 21-1

21.2 Migrating an Application to DCE RPC . • . • • • 21-3 21.2.1 Translating an Interface Definition from NIDL to

IDL . . • • . • . • . • • 21-3 21.2.2 Updating Runtime Calls • • . • . . • . 21-4

Part 4. DCE Directory Service

Chapter 22. DCE Directory Service Overview 22-1

xii OSF DeE Application Development Guide

22.1 Introduction to Part 4

22.1.1 Part 4 Document Usage

· ·

22.1.2 Directory Service Tools 22.2 U sing the DCE Directory Service

·

22.3 DCE Directory Service Concepts 22.4 Structure of DCE Names

22.4.1 DCE Name Prefixes

22.4.2 Names of Cells

· ·

22.4.3 CDS Names

· . . ·

22.4.4 GDSNames

· · ·

22.4.5 Junctions in DCE Names

· ·

22.4.6 Application Names

· ·

22.5 The Federated DCE N amespace

22.5.1 The GDS Namespace

· ·

22.5.2 The CDS N amespace

·

22.5.3 Other N amespaces

· · · ·

22.6 Programming Interfaces to the DCE Directory

Service

. . · · .

22.6.1 The X/Open Directory Service

Interface

· · ·

22.6.2 The RPC Name Service Interface 22.6.3 Namespace Junction Interfaces

Part 4A. CDS Application Programming

Chapter 23. Programming in the CDS Namespace . . 23.1 Initial Cell Namespace Organization .

23.1.1 The Cell Profile. . • . 23.1.2 The LAN Profile . . • • 23.1.3 The CDS Clearinghouse 23.1.4 The Hosts Directory 23.1.5 The Subsystems Directory 23.1.6 The /: DFS Alias

23.1. 7 The DFS and Security Service Junctions. . . • . • .

·

·

·

23.2 Recommended Use of the CDS Namespace . 23.2.1 Storing Data in CDS Entries • . • 23.2.2 Access Control for CDS Entries . . 23.3 Valid Characters and Naming Rules for CDS

23.3.1 Metacharacters . . . • 23.3.2 Additional Rules

23.3.3 Maximum Name Sizes OSF DeE Application Development Guide

. . .

·

·

·

· . .

Contents

22-1 22-2 22-3 22-3 22-4 22-8 22-9 22-10 22-12 22-12 22-13 22-13 22-14 22-15 22-17 22-18 22-19 22-19 22-19 22-20

23-1 23-2 23-4 23-4 23-4 23-5 23-5 23-6 23-6 23-7 23-7 23-12 23-16 23-18 23-20 23-22 xiii

23.4 Use of Object Identifiers . • • • . Chapter 24. XDS and the DCE Cell Namespace . . . . • .

24.1 Introduction to Accessing CDS with XDS 24.1.1 Using the Reference Material in this

Chapter . • . . • . . 24.1.2 What You Cannot Do with XDS . 24.1.3 What Must Be Set Up • . . • . .

24.2 XDS Objects • . . . • • . • . . 24.2.1 Object Attributes . . • .

24.2.2 Interface Objects and Directory Objects • . . . • 24.2.3 Directory Objects and Namespace Entries . . . . • . • . 24.2.4 Values That an Object Can Contain. .

24.2.5 Building a Name Object . . • . . . . . 24.2.6 A Complete Object • • . • .

24.2.7 Class Hierarchy . . • . • • 24.2.8 Class Hi~rarchy and Object Structure

24.2.9 Public and Private Objects and XOM . . • • 24.2.10 XOM Objects and XDS Library

Functions . • • . • . • • . 24.3 Accessing CDS Using the XDS Step-by,..Step

23-25 24-1 24-1 24-2 24-3 24-3 24-4 24-6 24-7 24-9 24-10 24-11 24-14 24-15 24-15 24-16 24-17 Procedure . . . . • . . • . . ' . . • • . 24-17 24.3.1 Reading and Writing Existing CDS Entry Attributes

Using XDS . • . . . 24-17 24.3.2 Creating New CDS Entry Attributes . . • • 24-36 24.4 Object-Handling Techniques

24.4.1 Using XOM to Access CDS . 24.4.2 Dynamic Creation of Objects 24.5 XDS/CDS Object Recipes . • . •

24.5.1 Input XDS/CDS Object Recipes. • 24.5.2 Input Object Classes for XDS/CDS

Operations . . . • . . 24.6 Attribute and Data Type Translation

Part 4B. GDS Application Programming

Chapter 25. GDS API: Concepts and Overview 25.1 Directory Service Interfaces

25.2 The X.500 Directory Information Model . 25.2.1 Directory Objects • . . • .

24-40 24-41 24-44 24-45 24-45 24-46 24-61

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

xiv OSF DeE Application Development Guide

25.3

25.2.2 Attribute Types. . . 25.2.3 Object. Identifiers 25.2.4 Object Entries X.500 Naming Concepts

25.3.1 Distinguished Names .

25.3.2 Relative Distinguished Names and Attribute Value

Assertions . . . . .

25.3.3 Multiple AVAs . . . . 25.3.4 Aliases

25.3.5 Name Verification 25.4 Schemas . . . .

25.5

25.4.1 The ODS Standard Schema 25.4.2 The Structure Rule Table 25.4.3 The Object Class Table 25.4.4 The Attribute Table 25.4.5 Defining Subclasses Abstract Syntax Notation 1 . . 25.5.1 ASN.1 Types

25.5.2 Basic Encoding Rules . 25.6 ODS as a Distributed Service . . .

25.6.1 The Directory Access Protocol 25.6.2 The Directory System Protocol 25.6.3 Referral . . . . 25.6.4 Chaining. . . . 25.6.5 The Directory User Agent Cache 25.6.6 ODS Configurations . . . . . 25.6.7 ODS Security

Chapter 26. XOM Programming

26.1 OM Objects . . . .

26.2

26.1.1 OM Object Attributes . 26.1.2 Object Identifiers . 26.1.3 C Naming Conventions 26.1.4 Public Objects

26.1.5 Private Objects . . . 26.1.6 Object Classes . . . Packages . . . .

26.2.1 The Directory Service Package . . . . 26.2.2 The Basic Directory Contents

Package . . . .

26.2.3 The Global Directory Service Package .

26.2.4 Package Closure . . . . 26.3 Workspaces

26.4 Storage Management OSF DeE Application Development Guide

Contents

25-5 25-5 25-7 25-9 25-9 25-10 25-11 25-12 25-14 25-15 25-15 25-16 25-19 25-23 25-25 25-26 25-27 25-28 25-28 25-30 25-30 25-30 25-31 25-33 25-37 25-38 26-1 26-2 26-2 26-6 26-7 26-10 26-20 26-22 26-29 26-29 26-30 26-31 26-32 26-32 26-33

xv

26.5 OM Syntaxes for Attribute Values • 26.5.1 Enumerated Types . 26.5.2 Object Types

26.5.3 Strings • . • . 26.5.4 Other Syntaxes . 26.6 Service Interface Data Types

26.6.1 The OM_descriptor Data Type . . . • . . 26.6.2 Data Types for XOM API Calls .

26.7 OM Function Calls . . . . 26.7.1 Summary of OM Function Calls . 26.7.2 Using the OM Function Calls

26.8 XOM API Header Files • . . . . 26.8.1 XOM Type Definitions and Symbolic Constant

Definitions

26.8.2 XOM API Macros . . . . . Chapter 27. XDS Programming . . . .

27.1 XDS Interface Management Functions . . • .

27.2

27.3

27.4 27.5

27.6 27.7

27.1.1 The ds_initialize( ) Function Call 27.1.2 The ds_ version( ) Function Call . . 27.1.3 The ds_shutdown( ) Function Call

Directory Connection Management Functions . • . . 27.2.1 A Directory Session • . . . . • . 27.2.2 The ds_bind() Function Call . . . • . 27.2.3 The ds_unbind( ) Function Call . • • . 27.2.4 Automatic Connection Management XDS Interface Class Definitions • . . . • . 27.3.1 Example: The DS_C_FILTER Class

27.3.2 The DS_C_CONTEXT Parameter Directory Class Definitions . • . . .

The Global Directory Service Package . . • . 27.5.1 Authentication .

27.5.2 Access Control . . . 27.5.3 DUA Cache . . . Directory Operation Functions .

Directory Read Operations . . . . • . 27.7.1 Reading an Entry from the Directory • . • . 27.7.2 Step 1: Export Object Identifiers for Required

Directory Classes and Attributes • . . . . 27.7.3 Step 2: Declare Local Variables . • . . . . 27.7.4 Step 3: Build Public Objects . • . • . • . 27.7.5 Step 4: Create an Entry-Information-Selection

Parameter . • . . . • . . . .

26-36 26-36 26-38 26-38 26-39 26-40 26-40 26-44 26-45 26-45 26-46 26-52 26-53 26-53 27-1 27-2 27-2 27-4 27-5 27-6 27-6 27-6 27-8 27-9 27-9 27-9 27-10 27-11 27-13 27-13 27-14 27-15 27-16 27-16 27-17 27-18 27-19 27-20 27-20

xvi OSF DeE Application Development Guide

27.8

27.7.6 Step 5: Perform the Read Operation

Directory Search Operations . . . • . . . . . 27.8.1 Searching the Directory . . . .

27.8.2 Step 1: Export Object Identifiers . . . 27.8.3 Step 2: Declare Local Variables . . .

27.8.4 Step 3: Build Public Objects for the name Parameter to ds_searchO . . • . . . .

27.8.5 Step 4: Specify the Portion of the DIT To Be Searched. . . . 27.8.6 Step 5: Create a Filter . . . . 27.8.7 Step 6: Create an Entry-Information-Selection

Parameter . . . • . . . . . 27.8.8 Step 7: Perform the Search Operation . . . . 27.9 Directory Modify Operations . . . .

27.9.1 Modifying Directory Entries . . . . . 27.9.2 Step 1: Export Object Identifiers for Required

Directory Classes and Attributes 27.9.3 Step 2: Declare Local Variables . .

27.9.4 Step 3: Build Public Objects . . . . 27.9.5 Step 4: Create Descriptor Lists for

Attributes . . . . 27.9.6 Step 5: Perform the Operations

Chapter 28. Sample Application Programs . . . . 28.1 General Programming Guidelines .

28.2 The example.c Program . . . .

28.2.1 The example.c Code . . • . . . . 28.2.2 Error Handling .

28.3 The acl.c Program . . . . 28.3.1 The acl.c Code • . . 28.3.2 The acl.h Header File . 28.3.3 The acl.h Code . .

28.4 The teldir.c Program . • . . . . 28.4.1 Predefined Static Public Objects . 28.4.2 Partially Defined Static Public

Objects . . . • . . . . . 28.4.3 Dynamically Defined Public Objects

28.4.4 Main Program Procedural Steps . . . . 28.4.5 The teldir.c Code . . . .

Part 4C. XDS/XOM Supplementary Information

Chapter 29. XDS Interface Description . . OSF DeE Application Development Guide

Contents

27-22 27-26 27-26 27-29 27-30 27-31 27-31 27-32 27-34 27-34 27-37 27-38 27-39 27-39 27-40 27-42 27-44 28-1 28-2 28-2 28-6 28-12 28-14 28-18 28-36 28-37 28-46 28-46 28-48 28-49 28-50 28-52

29-1 xvii

29.1 XDS Conformance to Standards 29.2 The XDS Functions

29.3 The XDS Negotiation Sequence 29.4 The session Parameter

29.5 The context Parameter

29.6 The XDS Function Arguments . . . . 29.6.1 Attribute and Attribute Value

Assertion • . . . 29.6.2 The Entry-Information-Selection

Parameter . . . . 29.6.3 The name Parameter 29.7 XDS Function Call Results . • .

29.7.1 The invoke_id Parameter . . . • . 29.7.2 The result Parameter . . . . 29.7.3 The DS_status Return Value . 29.8 Synchronous Operations. • . . 29.9 Security and XDS . . . 29.10 Other Features of the XDS Interface . •

29.10.1 Automatic Connection Management 29.10.2 Automatic Continuation and Referral

Handling. . . • . Chapter 30. XDS Class Definitions . . . .

30.1 Introduction to OM Classes 30.2 OM Class Hierarchy . . . . 30.3 DS_C_ACCESS_POINT

30.4 DS_C_ADDRESS

30.5 DS_C_ATTRIBUTE. . . 30.6 DS_C_ATTRIBUTE_LIST. . 30.7 DS_C_AVA . . . • . 30.8 DS_C_COMMON_RESULTS • . 30.9 DS_C_COMPARE_RESULT .

29-2 29-3 29-5 29-6 29-6 29-7 29-8 29-9 29-10 29-10 29-11 29-11 29-12 29-12 29-13 29-13 29-13 29-14 30-1 30-1 30-2 30-4 30-5 30-5 30-6 30-7 30-7 30-8 30-9 30-15 30-16

xviii OSF DeE Application Development Guide

30.15 DS_C_ENTRY_INFO_SELECTION . 30.16 DS_C_ENTRY_MOD . . . . 30.17 DS_C_ENTRY_MOD_LIST 30.18 DS_C_EXT

30.19 DS_C_FILTER 30.20 DS_C_FILTER_ITEM 30.21 DS_C_LIST_INFO .

30.22 DS_C_LIST_INFO_ITEM . . . 30.23 DS_C_LIST_RESULT . .

30.24 DS_C_NAME. • . . . . • . . 30.25 DS_ C_ OPERATION_PROGRESS

30.26 DS_C_PARTIAL_OUTCOME_QUAL 30.27 DS_C_PRESENTATION_ADDRESS 30.28 DS_C_READ_RESULT. . . 30.29 DS_C_RELATIVE_NAME. . 30.30 DS_C_SEARCH_INFO . . 30.31 DS_C_SEARCH_RESULT . 30.32 DS_C_SESSION . . Chapter 31. XDS Errors . . . . •

31.1 OM Class Hierarchy . 31.2 DS_C_ERROR

31.3 DS_C_ABANDON_FAILED 31.4 DS_C_ATTRIBUTE_ERROR . 31.5 DS_C_ATTRIBUTE_PROBLEM . 31.6 DS_C_COMMUNICATIONS_ERROR . 31.7 DS_C_LIBRARY_ERROR .

31.8 DS_C_NAME_ERROR . . . 31.9 DS_C_REFERRAL . • . 31.10 DS_C_SECURITY_ERROR 31.11 DS_C_SERVICE_ERROR . . 31.12 DS_C_SYSTEM_ERROR . . OSF DeE Application Development Guide

Contents

30-17 30-18 30-20 30-21 30-21 30-22 30-24 30-26 30-28 30-29 30-30 30-30 30-32 30-33 30-34 30-35 30-36 30-37 30-38 31-1 31-2 31-3 31-6 31-7 31-8 31-9 31-10 31-12 31-13 31-13 31-14 31-16 xix

31.13 DS_C_UPDATE_ERROR Chapter 32. Basic Directory Contents Package .

32.1 Selected Attribute Types 32.2 Selected Object Classes •

.

32.3 OM Class Hierarchy

.

32.4 DS_C_FACSIMILE_PHONE_NBR 32.5 DS_C_POSTAL_ADDRESS 32.6 DS_C_SEARCH_CRITERION 32.7 DS_C_SEARCH_GUIDE

32.8 DS_C_TELETEX_TERM_IDENT 32.9 DS_C_TELEX_NBR

Chapter 33. MHS Directory User Package 33.1 MDUP Attribute Types . 33.2 MDUP Object Classes 33.3 MDUP OM Class Hierarchy 33.4 MH_C_OR_ADDRESS . . . 33.5 MC_C_OR_NAME • . • . . 33.6 DS_C_DL_SUBMIT_PERMS . Chapter 34. Global Directory Service Package

34.1 GDSP Attribute Types 34.2 GDSP Object Classes 34.3 GDSP OM Class Hierarchy 34.4 DSX_C_GDS_ACL . . • . 34.5 DSX_C_GDS_ACL_ITEM . 34.6 DSX_C_GDS_CONTEXT . . 34.7 DSX_C_GDS_SESSION

Chapter 35. Information Syntaxes 35.1 Syntax Templates 35.2 Syntaxes

35.3 Strings • • . .

35.4 Representation of String Values 35.5 Relationship to ASN.l Simple Types

31-17 32-1 32-2 32-15 32-16 32-17 32-18 32-18 32-20 32-21 32-22 33-1 33-2 33-6 33-7 33-7 33-28 33-28 34-1 34-2 34-6 34-7 34-8 34-9 34-10 34-15 35-1 35-1 35-2 35-3 35-5 35-6

xx

35.6 Relationship to ASN.1 Useful Types . . . . 35.7 Relationship to ASN.1 Character String Types . 35.8 Relationship to ASN.1 Type Constructors

Chapter 36. XOM Service Interface . . . . 36.1 Standards Conformance .

36.2 XOM Data Types. . . 36.2.1 OM_boolean 36.2.2 OM_descriptor . 36.2.3 OM_enumeration 36.2.4 OM_exclusions . 36.2.5 OM_integer . . 36.2.6 OM_modification

36.2.7 OM_object . . . . 36.2.8 OM_object_identifier . . . . . 36.2.9 OM_private_object

36.2.10 OM_public_object. . 36.2.11 OM_return_code 36.2.12 OM_string .

36.2.13 OM_syntax . . . . . . 36.2.14 OM_type . . . .

36.2.15 OM_type_list 36.2.16 OM_value . . . 36.2.17 OM_value_length . 36.2.18 OM_value_position 36.2.19 OM_workspace . 36.3 XOM Functions

36.4 XOM Return Codes . . Chapter 37. Object Management Package

37.1 Class Hierarchy

37.2 Class Definitions . . . . .

37.2.1 OM_C_ENCODING . . . . 37.2.2 OM_C_EXTERNAL

37.2.3 OM_C_OBJECT

Part 5. DCE Distributed Time Service

Chapter 38. Introduction to the Distributed Time Service API 38.1 DTS Time Representation . . . . .

38.1.1 Absolute Time Representation 38.1.2 Relative Time Representation OSF DeE Application Development Guide

Contents

35-6 35-7 35-8 36-1 36-2 36-2 36-5 36-5 36-7 36-8 36-8 36-9 36-9 36-10 36-12 36-13 36-13 36-14 36-15 36-16 36-17 36-17 36-19 36-19 36-19 36-20 36-22 37-1 37-1 37-2 37-2 37-3 37-5

38-1 38-2 38-2 38-5 xxi

38.2 Time Structures . 38.2.1 The utc Structure 38.2.2 The tm Structure . 38.2.3 The timespec Structure 38.2.4 The reltimespec Structure 38.3 DTS API Header Files

38.4 DTS API Routine Functions Chapter 39. Time-Provider Interface .

39.1 General TPI Control Flow . . 39.1.1 ContactProvider Procedure 39.1.2 ServerRequestProviderTime

Procedure

39.2 Time-Provider Process IDL File 39.3 Initializing the Time-Provider Process 39.4 Time-Provider Algorithm

39.5 DTS Synchronization Algorithm 39.6 Running the Time-Provider Process 39.7 Sources of Additional Information • Chapter 40. DTS API Routines Programming Example

Part 6. DeE Security Service

Chapter 41. Overview of Security

41.1 Purpose and Organization of This Part of the Guide

41.2 About Authenticated RPC

41.3 UNIX System Security and DCE Security 41.4 What Authentication and Authorization Mean

41.5 Authentication, Authorization, and Data Protection in Brief

41.6 Summary of DCE Security Services and

Facilities .

41.6.1 Interfaces to the Security Server • 41.6.2 Interfaces to the Login Facility 41.6.3 Interfaces to the Key Management

Facility . • • . . • . 41.6.4 Interfaces to the ID Map Facility

38-8 38-8 38-9 38-10 38-10 38-11 38-11 39-1 39-2 39-5 39-6 39-7 39-11 39-14 39-15 39-16 39-16 40-1

41-1 41-1 41-2 41-2 41-3 41-4 41-6 41-7 41-9 41-10 41-10

xxii OSF DeE Application Development Guide

41.6.5 Interfaces to the Access Control List

Facility . . . . .

41.6.6 DCE Implementations of UNIX System Program Interfaces

41.7 Relationships Between the Security Service and DCE Applications

41.8 DTS, the Cell Namespace, and Security 41.8.1 DTS and Security

41.8.2 The Cell Namespace and the Security Namespace •

Chapter 42. Authentication

42.1 Background Concepts 42.1.1 Principals

42.1.2 Cells and Realms . . 42.1.3 The Shared-Secret Authentication

Protocol . •

42.1.4 Protection Levels . • 42.1.5 Data Encryption Mechanisms

42.2 A Walk-Through of the Shared-Secret Authentication

Protocol. • .

42.2.1 A Walk-Through of User Authentication .

42.2.2 A Walk-Through ofDCE Application Authentication .

42.3 Intercell Authentication. . . . 42.3.1 Authentication Service Surrogates 42.3.2 Intercell Authentication by Trust

Peers . Chapter 43. Authorization .

43.1 DCE Authorization. . 43.1.1 Object Types and ACL Types 43.1.2 ACL Manager Types

43.1.3 Access Control Lists 43.1.4 ACL Entries . 43.1.5 Access Checking

43.1.6 Examples of ACL Checking . 43.2 Name-Based Authorization .

Chapter 44. The Registry Application Program Interface . 44.1 Binding to a Registry Site

44.2 The Registry Database. . • . . 44.2.1 Creating and Maintaining PGO Items OSF DeE Application Development Guide

Contents

41-10 41-11 41-11 41-12 41-12 41-12 42-1 42-2 42-2 42-3 42-4 42-4 42-5 42-5 42-6 42-11 42-18 42-18 42-19 43-1 43-1 43-2 43-4 43-4 43-5 43-9 43-15 43-19 44-1 44-1 44-3 44-4 xxiii

44.2.2 Creating and Maintaining Accounts 44.2.3 Registry Properties and Policies . 44.2.4 Miscellaneous Registry Routines Chapter 45. The Login Application Program Interface

45.1 Establishing Login Contexts

45.1.1 Validating the Login Context and Certifying the Security Server . • . . . . 45.1.2 Validating the Login Context Without Certifying the

Security Server . . . 45.1.3 Example of a System Login Program 45.2 Context Inheritance .

45.2.1 The Initial Context . 45.2.2 Private Contexts

45.3 Handling Expired Certificates of Identity 45.4 Importing and Exporting Contexts . 45.5 Changing a Groupset .

45.6 Miscellaneous Login API Functions 45.6.1 Getting the Current Context . 45.6.2 Getting Information from a Login

C o n t e x t . . .

45.6.3 Getting Password and Group Information for Local Process Identities

45.6.4 Releasing and Purging a Context

Chapter 46. The Key Management Application Program Interface . 46.1 Retrieving a Key .

46.2 Changing a Key

46.3 Automatic Key Management 46.4 Deleting Expired Keys

46.5 Deleting a Compromised Key . Chapter 47. The Access Control List Application Program

Interfaces

47.1 The Client-Side API . . 47.1.1 Binding to an ACL . 47.1.2 ACL Editors and Browsers 47.1.3 Testing Access • . 47.1.4 Errors.

47.2 The Server-Side API. . . . • 47.2.1 The ACL Manager Interface . 47.2.2 The ACL Network Interface .

44-6 44-7 44-9 45-1 45-2 45-3 45-4 45-4 45-5 45-5 45-6 45-6 45-7 45-8 45-9 45-9 45-9 45-9 45-10 46-1 46-2 46-3 46-4 46-4 46-5 47-1 47-2 47-3 47-3 47-4 47-5 47-5 47-5 47-8

xxiv OSF DeE Application Development Guide

Chapter 48. The ID Map Application Program Interface

Part 7. DeE Distributed File Service

Chapter 49. DCE Distributed File Service Overview • 49.1 Writing DFS Applications . • • .

49.1.1 Related DCE Components . . • . 49.1.2 The DFS Application Programming

Interface . . • . . . . 49.2 Overview of the DCE Distributed File Service

Architecture . . . . 49.3 Component Overview 49.3.1 The DCE Local File System 49.3.2 The Virtual File System Interface

· . · ·

(VFS+)

. .

49.3.3 The Cache Manager

·

49.3.4 The File Exporter

·

49.3.5 The Fileset Server

· .

49.3.6 The Fileset Location Database and

Server

. · ^.

49.3.7 The Replication Server 49.3.8 The BOS Server 49.4 An Example ofDFS File Access

Synchronization . . . . Chapter 50. General Cache Manager Operations

·

50.1 Extensions to the ioct1() System Call .

· ·

·

50.2 Using the pioct1() System Call. . . 50.2.1 System, Cell, and Fileset Operations 50.2.2 The Cache . . . • .

·

· ·

·

50.2.3 Other Operations . . . . 50.3 Using the afs_syscall() System Call

.

50.3.1 Retrieving ACLs . . • . . . . . 50.3.2 Setting ACLs . . • . . . . .

50.3.3 Copying ACLs . . . .

50.4 Syntax Summary . . . 50.4.1 The ioct1( ) Call . 50.4.2 The pioct1( ) Call 50.4.3 The afs_syscall( ) Call Chapter 51. Manipulating Filesets . . • .

51.1 DCE and DFS API Terminology Differences OSF DeE Application Development Guide

Contents

48-1

49-1 49-2 49-2 49-5 49-6 49-8 49-8 49-15 49-16 49-18 49-23 49-25 49-26 49-27 49-28 50-1 50-2 50-2 50-4 50-9 50-11 50-12 50-13 50-13 50-14 50-14 50-14 50-15 50-17 51-1 51-2

xxv

51.2 Parameters, Types, and Return Values 51.3 Data Types

51.4 Authorization Requirements

51.5 The VC Functions: General Fileset Operations . 51.5.1 Parameters . . .

51.5.2 Creating and Deleting Filesets 51.5.3 Moving, Renaming, and Backing Up

Filesets. . • .

51.5.4 Saving and Restoring Changes to Filesets .

51.5.5 Setting Fileset Quotas . . . 51.5.6 Synchronizing the Database and File

Server. .

51.5.7 Getting Information About Filesets . 51.5.8 Syntax Summary

51.6 The VL Functions: Interacting with the Fileset Location Database . .

51.6.1 The Fileset Location Database Entry 51.6.2 Fileset Location .

51.6.3 Fileset Entry Maintenance . . 51.6.4 Obtaining Configuration Information 51.6.5 Syntax Summary

51.7 The FTSERVER Functions: Interacting with the Fileset Server • . . . . .

51.7.1 Basic Transaction Functions . 51.7.2 Creating, Deleting, and Cloning

Filesets . . . . . . 51.7.3 Getting and Modifying Fileset Status 51.7.4 Dumping, Restoring, and Moving

Filesets . . . . • . • 51.7.5 Enumerating Filesets, Aggregates, and

Transactions 51.7.6 Syntax Summary

Chapter 52. The BOS Server: Monitoring File Server Processes 52.1 Common Arguments .

52.2 Configuration Files 52.3 Process Monitoring

52.3.1 Bnodes. .

52.3.2 Creating and Deleting Bnodes 52.3.3 Changing and Examining Bnode

Instances. . . • 52.3.4 Stopping and Starting Bnode

Instances .

51-3 51-3 51-4 51-4 51-5 51-5 51-6 51-7 51-9 51-9 51-10 51-11 51-15 51-16 51-19 51-22 51-32 51-32 51-39 51-40 51-43 51-46 51-52 51-54 51-56 52-1 52-2 52-3 52-3 52-3 52-5 52-6 52-8

xxvi OSF DeE Application Development Guide

Index

52.4 Server Key Maintenance 52.5 Installing Binaries

52.6 Authorization Issues . • . 52.7 Miscellaneous Functions 52.8 Syntax Summary .

OSF DeE Application Development Guide

Contents

52-10 52-11 52-12 52-13 .52-14 Index-l

xxvii

List of Figures

Figure 1-1. The Combined Effect of IDL and the RPC Runtime Figure 1-2. The DCE Steps: The Five Basic Phases Illustrated . Figure 1-3. Objectffype and Interface{fype/EPV Registration • Figure 1-4. RPC Server Runtime Dispatching on the Basis of Object

Type

Figure 2-1. How a Name Turns into an Object Figure 2-2. A Namespace Junction .

Figure 2-3. Client and Server Use of the Name Service • Figure 2-4. The Endpoint Mapper Completes a Binding. • Figure 2-5. Print Server Entries in Namespace

Figure 2-6. Print Server Name Entries with Object UUIDs • Figure 2-7. Separate Printer Name Entries •

Figure 2-8. Object-Oriented Namespace Organization Figure 2-9. The Export Operation in a Model with Grouped

Bindings • • • •

Figure 2-10. Importing from a Model That Uses Grouped Bindings . Figure 2-11. Authenticated RPC and the Server Key

Figure 2-12. ACL Interfaces in the Registry Server

Figure 3-1. How an Executable DCE Application is Produced • Figure 4-1. Work Crew Model

Figure 4-2. Pipelining Model . Figure 5-1. Thread State Transitions

Figure 5-2. Only One Thread Can Lock a Mutex •

Figure 5-3. Thread A Waits on Condition Ready, Then Wakes Up and Proceeds

1-5 1-7 1-29 1-30 2-5 2-8 2-14 2-16 2-18 2-20 2-22 2-26 2-38 2-41 2-62 2-74 3-3 4-4

4-5

xxviii OSF DeE Application Development Guide

Contents

Figure 5-4. Thread B Signals Condition Ready Figure 5-5. Flow with SCHED_FIFO Scheduling . Figure 5-6. Flow with SCHED _RR Scheduling

Figure 5-7. Flow with SCHED _OTHER Scheduling • Figure 9-1. Tasks for Distributing an Application Figure 9-2. Role of the RPC Interface

Figure 9-3. The Parts of an RPC Application

Figure 9-4. Marshalling and Unmarshalling Between ASCII and EBCDIC Data

Figure 9-5. Interrelationships During a Remote Procedure Call Figure 9-6. Generating Stubs . .

Figure 9-7. Building a Simple Client and Server .

Figure 10-1. Relationship of RPC Application and Stub Code to Runtime Operations •

Figure 12-1. A Binding .

Figure 12-2. Server Binding Information and Binding Handles on a Server .

Figure 12-3. Server Binding Information and a Binding Handle on a Client

Figure 12-4. Information Used to Identify a Compatible Server . .

Figure 12-5. Client Binding Information Resulting from a Remote Procedure Call .

Figure 13-1. Basic Tasks of a Remote Procedure Call . Figure 13-2. Typical Initialization Calls of an RPC Server Figure 13-3. How Objects Correspond to Types

Figure 13-4. Manager Types

Figure 13-5. Exporting Server Binding Information Figure 13-6. Methods of Binding Management .

Figure 13-7. Basic String Binding Calls of an RPC Client Figure 13-8. Calls for NSI Search Operations by RPC Clients Figure 13-9. Importing Server Binding Information

Figure 14-1. NSI Attributes

Figure 14-2. The import_next and lookup_next Search Algorithm Within a Single Entry

OSF DeE Application Development Guide

5-14 5-19 5-20 5-20 9-3 9-6 9-8 9-10 9-11 9-14 9-15 10-10 12-2 12-7 12-8 12-10 12-15 13-5 13-8 13-10 13-12 13-17 13-21 13-24 13-25 13-26 14-3 14-7 xxix

Figure 14-3. Local Application Thread During a Procedure Call Figure 14-4. Server Application Thread and Multiple Call Threads . Figure 14-5. Execution Phases of an RPC Thread .

Figure 14-6. Concurrent Call Threads Executing in Shared Address Space

Figure 14-7. Phases of a Cancel in an RPC Thread .

Figure 14-8. A Multithreaded RPC Application Acting as Both Server and Client

Figure 14-9. Phases of a Nested RPC Call

Figure 14-10; Phases of a Nested RPC Call to Client Address Space • Figure 14-11. Steps in Routing Remote Procedure Calls

Figure 14-12. Mapping Information and Corresponding Endpoint Map Elements

Figure 14-13. Decisions for Looking Up an Endpoint Figure 14-14. A Request Buffer at Full Capacity

Figure 14-15. Stages of Call Routing by a Server Process . Figure 14-16. Decisions for Selecting a Manager

Figure 15-1. Parts of a Global Name .

Figure 15-2. Possible Information in a Server Entry Figure 15-3. Possible Mappings of a Group . Figure 15-4. Possible Mappings of a Profile .

Figure 15-5. Priorities Assigned on Proximity of Members Figure 15-6. Service Model: Interchangeable Instances on Two

Hosts

Figure 15-7. Service Model: Interchangeable Instances on One Host Figure 15-8. Service Model: Distinct Instances on One Host Figure 15-9. Resource Model: A System-Specific Application • Figure 15-10. Resource Model: A Single Server Entry for Each

Server .

Figure 15-11. Resource Model: A Separate Server Entry for Each Object .

Figure 22-1. A Federated DCE Namespace .

Figure 22-2. GDS Namespace Entries arid Directory Objects Figure 23-1. The Cell N amespace After Configuration

14-14 14-15 14-16 14-17 14-19 14-21 14-22 14-24 14-26 14-28 14-30 14-33 14-35 14-38 15-4 15-6 15-7 15-10 15-21 15-24 15-25 15-28 15-33 15-35 15-37 22-14 22-16 23-3

xxx

Figure 23-2. A Possible Namespace Structure . . . . . Figure 23-3. Valid Characters in CDS, GDS, and DNS Names Figure 24-1. One Object Descriptor

Figure 24-2. A Complete Object Represented Figure 24-3. A Three-Layer Compound Object .

Figure 24-4. Directory Objects and XDS Interface Objects

Figure 24-5. Directory Objects and Namespace Entries . . . . Figure 24-6. The DS_C_READ_RESULT Object Structure . Figure 24-7. The DS_ENTRY_INFO Object Structure

Figure 24-8. The DS_C_ATTRIBUTE Object Structure Figure 24-9. The DS_C_ATTRIBUTE_LIST Object Figure 24-10. DS_C_DS_DN Object Attributes . . . Figure 24-11. The DS_C_ENTRY _MOD_LIST Object

Figure 24-12. The DS_C_ENTRY _INFO_SELECTION Object Figure 25-1. XDS: Interface to GDS and CDS .

Figure 25-2. The Structure of the DIB

Figure 25-3. Object Identifiers. . . . .

Figure 25-4. A Directory Entry Describing Organizational Person . Figure 25-5. A Distinguished Name in a Directory Information Tree Figure 25-6. An Alias in the Directory Information Tree . • Figure 25-7. A Subtree Populated by Aliases . . • . • . . Figure 25-8. SRT DIT Structure for the GDS Standard Schema Figure 25-9. A Partial Representation of the Object Class Table Figure 25-10. The Relationship Between Schemas and the DIT Figure 25-11. The Relationship Between the DSA and the DUA Figure 25-12. An Example of a Referral

Figure 25-13. An Example of Chaining Figure 25-14. GDS Components

Figure 26-1. The Internal Structure of an OM Object . Figure 26-2. Mapping the Class Definition of

DS_C_ENTRY_INFO_SELECTION .

OSF DeE Application Development Guide

Contents

23-10 23-17 24-5 24-6 24-7 24-9 24-10 24-28 24-31 24-34 24-49 24-51 24-56 24-59 25-3 25-4 25-6 25-8 25-10 25-13 25-14 25-18 25-21 25-25 25-29 25-31 25-32 25-34 26-3 26-5

xxxi

Figure 26-3. A Representation of a Public Object Using a Descriptor List . . . . • . . . • . . • . . . • figure 26-4. A Descriptor List for the Public Object: country

Figure 26-5. The Distinguished Name of "Peter Piper" in the DIT Figure 26-6. Building a Distinguished Name

Figure 26-7. A Simplified View of the Structure of a Distinguished Name . . . • . . . . Figure 26-8. Client-Generated and Service-Generated Objects Figure 26-9. The OM Class DS_C_ENTRY_INFO_SELECTION Figure 26-10. A Comparison of Two Classes With and Without an Figure 26-11. A Complete Description of Concrete OM Class

DS_C_ATTRIBUTE. • . . • Figure 26-12. Data Type OM_descriptor_struct . Figure 26-13. Initializing Descriptors . . . . Figure 26-14. An Object and a Subordinate Object . Figure 26-15. The Read Result . . . • • . Figure 26-16. Extracting Information Using om_get( )

Figure 27-1. Output from ds_readO: DS_C_READ_RESULT Figure 27-2. Subtree for the acl.h Sample Program . . . . Figure 27-3. OM Class DS_C_FILTER . • • . •

Figure 27-4. OM Class DS_C_SEARCH_RESULT . . . . Figure 27-5. A Sample Directory Tree . . . • . . Figure 27-6. OM Class DS_C_LIST_RESULT • . •

Figure 28-1. Entries with User Credentials Added to the Directory

Tree . . . . . . . • •

Figure 36-1. OM_String Elements

Figure 38-1. ISO Format for Time Displays . . Figure 38-2. Variations to the ISO Time Format Figure 38-3. Full Syntax for a Relative Time

Figure 38-4. Syntax for Representing a Duration . . . . Figure 38-5. DTS API Routines Shown by Functional Grouping • • . . Figure 39-1. DTS/Time-Provider RPC Calling Sequence . . .

26-11 26-13 26-14 26-17 26-18 26-19 26-23 26-24 26-27 26-41 26-42 26-43 26-50 26-51 27-24 27-28 27-33 27-36 27-38 27-46 28-16 36-15 38-3 38-4 38-5 38-6 38-12 39-4

xxxii OSF DeE Application Development Guide

Figure 41-1. Shared-Secret Authentication and DCE Authorization in Brief

Figure 41-2. DCE Security and the DCE Application Environment .

Contents

41-5 41-11 Figure 42-1. Representational Conventions Used in Authentication Walk-Through

Illustrations 42-6

Figure 42-2. Client Acquires Ticket-Granting Ticket .

Figure 42-3. Client Acquires Privilege-Ticket-Granting Ticket . Figure 42-4. Client Sets Authentication and Authorization

Information

Figure 42-5. Client Principal Makes Application Request Figure 42-6. Application Server Challenges Client

Figure 42-7. Application Server Responds to Client's Request Figure 43-1. Derivation of ACL Defaults

Figure 47-1. ACL Program Interfaces

Figure 49-1. The Organization of the DFS Cache Manager

OSF DeE Application Development Guide

42-8 42-10 42-13 42-14 42-16 42-17 43-3 47-2 49-17

xxxiii

List of Tables

Table 2-1. Some Examples of Objects Table 7-1. DCE Threads Exceptions

Table 12-1. Assessment of Mechanisms for Obtaining Binding

Information . • . . . • . .

Table 12-2. Execution Semantics for DCE RPC Calls. . • Table 13-1. Runtime Routines Associated with Basic Runtime

Operations . . . • . •

Table 15-1. NSI next Operations • . . . • . • Table 17-1. IDL Attributes . . • . . • . • Table 17-2. Base Data Type Specifiers

Table IS-I. Summary of the ACF Attributes

Table 23-1. Metacharacters and Their Meaning • • • . Table 23-2. Summary of CDS, ODS, and DNS Characteristics Table 23-3. Maximum Sizes of Directory Service Names Table 23-4. T61 Syntax . . • . • . . . • • . • Table 23-5. Combinations of Diacritical Characters and Basic

Letters . . . • . • . . . • . . • • Table 24-1. Directory Service Functions with their Required Input

Objects . . . • . • • . . • • . • • . . Table 24-2. CDS Attributes to OM Syntax Translation

Table 24-3. OM Syntax to CDS Data Types Translation . Table 25-1. Object Identifiers for Selected Attribute Types Table 25-2. Structure Rule Table Entries

Table 25-3. Object Class Table Entries

Table 25-4. Object Identifiers for Selected Directory Classes

2-23 7-11 12-13 12-20 13-6 15-15 17-S 17-19 IS-23 23-19 23-21 23-22 23-23 23-24 24-46 24-61 24-62 25-7 25-16 25-19 25-22

xxxiv OSI': DeE Application Development Guide

Table 25-5. Attribute Table Entries

Table 25-6. Syntax for the Simple ASN.1 Types

Table 25-7. Cache Attributes: Read Cache First . . . • . • . • . Table 25-8. Cache Attributes: Read DSA First • . • . • . .

Table 25-9. Cache Attributes: Read DSA Only. .

Table 25-10. Cache Attributes: DSX_ USEDSA is OM_FALSE Table 25-11. Cache Attributes: DSX_DUA_CACHE is OM_FALSE Table 25-12. Cache Attributes: Error . . • • .

Table 26-1. C Naming Conventions for XDS Table 26-2. C Naming Conventions for XOM

Table 26-3. Comparison of Private and Public Objects

Table 26-4. Description of an OM Attribute Using Syntax Enum(*) Table 26-5. Description of an OM Attribute Using Syntax Object(*) Table 27-1. Representation of Values for Selected Attribute Types . Table 27-2. Mapping of XDS API Functions to the Abstract

. ^{. .}

Services. • . • . . . • . . . • . . Table 29-1. The XDS Interface Functions

Table 30-1. OM Attributes of DS_C_ACCESS_POINT Table 30..;..2. OM Attributes ofDS_C..;..ATTRIBUTE

Table 30-3. OM Attribute of DS_C_ATTRIBUTE_LIST . Table 30-4. OM Attributes ofDS_C_COMMON_RESULTS Table 30-5. OM Attributes ofDS_C_COMPARE..;..RESULT. • Table 30-6. OM Attributes ofDS_C_CONTEXT . • . • Table 30-7. OM Attributes ofDS_C_CONTINUATION_REF Table 30-8. OM Attribute of DS_C_DS_DN

Table 30-9. OM Attribute of DS_C_DS_RDN • . • . • Table 30-10. OM Attributes of DS_C_ENTRY_INFO . • • Table 30-11. OM Attributes of DS_C_ENTRY _INFO_SELECTION Table 30-12. OM Attribute ofDS_C_ENTRY_MOD

Table 30-13. OM Attribute ofDS_C_ENTRY_MOD_LIST Table 30-14. OM Attributes of DS_C_EXT

Table 30-15. OM Attributes ofDS_C_FILTER OSF DeE Application Development Guide

Contents

25-24 25-27 25-36 25-36 25-36 25-37 25-37 25-37 26-9 26-9 26-21 26-37 26-38 27-12 27-16 29-4 30-4 30-6 30-7 30-8 30-9 30-10 30-15 30-16 30-17 30-18 30-19 30-20 30-21 30-22 30-23

xxxv

Table 30-16. OM Attributes of DS_C_FILTER_ITEM . . Table 30-17. OM Attributes of DS_C_LIST_INFO . . • Table 30-18. OM Attributes of DS_C_LIST_INFO_ITEM . Table 30-19. OM Attributes of DS_C_LIST_RESULT . . Table 30-20. OM Attributes of DS_C_OPERATION_PROGRESS Table 30-21. OM Attributes of a

DS_C_PARTIAL_OUTCOME_QUAL

Tuble 30-22. OM Attributes of DS_C_PRESENTATION_ADDRESS Table 30-23. OM Attribute of DS_C_READ_RESULT . .

Table 30-24. OM Attributes of DS_C_SEARCH_INFO Table 30-25. OM Attributes of DS_C_SEARCH_RESULT Table 30-26. OM Attributes of DS_C_SESSION

Table 31-1. OM Attribute of DS_C_ERROR . . . . Table 31-2. OM Attributes of DS_C_ATTRIBUTE_ERROR Table 31-3. OM Attributes of DS_C_ATTRIBUTE_PROBLEM

Table 31-4. OM Attribute of DS_C_NAME_ERROR . . . . Table 32-1. Object Identifiers for Selected Attribute Types . . . Table 32-2. Representation of Values for Selected Attribute Types . Table 32-3. Object Identifiers for Selected Object Classes

Table 32-4. OM Attributes of DS_C_FACSIMILE_PHONE_NBR .

Table 32-5. OM Attribute of DS_C_POSTAL_ADDRESS . . . . Table 32-6. OM Attributes of DS_C_SEARCH_CRITERION

Table 32-7. OM Attributes of DS_C_SEARCH_GUIDE . • . Table 32-8. OM Attributes of DS_C_TELETEX_TERM_IDENT Table 32-9. OM Attributes of DS_C_TELEX_NBR

Table 33-1. Object Identifiers for MDUP Attribute Types

Table 33-2. Representation of Values for MDUP Attribute Types Table 33-3. Object Identifiers for MDUP Object Classes . Table 33-4. Attributes Specific to MH_C_OR_ADDRESS Table 33-5. Forms of Originator/Recipient Address

Table 33-6. Attribute Specific to MH_C_OR_NAME. . Table 33-7. OM Attributes of DS_C_DL_SUBMIT_PERMS

30-24 30-27 30-28 30-29 30-31 30-32 30-34 30-35 30-36 30-37 30-38 31-3 31-7 31-8 31-12 32-4 32-6 32-16 32-17 32-18 32-19 32-21 32-22 32-23 33-3 33-4 33-6 33-8 33-23 33-28 33-29

xxxvi OSF DeE Application Development Guide