Digital PDFs

MISC-0003-PW-01

August 1992

136 pages

Original

5.3MB

Document:	PATHWORKS File System 0.1
Order Number:	MISC-0003-PW-01
Revision:	0
Pages:	136
Original Filename:

OCR Text

P ATHWORKS File System
Personal Computer Systems Group

Abstract

Written by:
Issued by:
Reviewed by:

Michael Evans
~--------------------------~

Michael Evans

~--------------------------~

----------------------------~

Issue date:

August 28, 1992

Revision/Update
Information:

Version #0 .1

Copyright © 1992, by
Digital Equipment Corporation, Maynard Massachusetts.
All rights reserved
This document is confidential and proprietary, and is the property of Digital Equipment Corporation. It
is an unpublished work protected under Federal copyright laws.

PATHWORKS File System

Table of Contents
1

PREFACE •••••••••••••••••••••••••.••••••••••••••••••••••••••••••••••••••••••••••••••••••• 8

2 REVISION HISTORY •••••••••••••••••••••••••••••••••••.••••••••••••••••.•••••••••••••• 9
3 INTRODUCTION ••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••••• 1 0
4

TERMS AND SPECIFICATION SYNTAX ••••••••••••••••••••••••••••.•••••••••••••• 1 1

5 REFERENCES ••.•••••.•••.•••••••••••••••••••••••••••••••••.••••••••..•••.•.••••••••••••• 1 3
6

DESIGN

OVERVIEW ••.•••••.•••••••.•.••••••••••••••••••••.••.••••••.•••••••••••••.•.••••••.•••••• 1 6

7. 1
7. 2
7. 3

7.4

7. 5

Functional overview ........................................................ 1 6
Summary of functions ..................................................... 1 6
File service components .................................................. 1 8
7 .3.1
Namespace .........................•........•.............................................. 1 8
7 .3.2
Attributes ................................................................................... 1 9
7. 3 . 3
Security............................•........................................................2 0
7 .3.4
Data Paths....................•............................................................. 21
Structural overview ....................................................... 22
7.4.1
Top level interface .................................................................... 22
7.4.2
File System Library Interface (FSLIB) ................................... 22
7.4.2.1 FSLIB Path Claim ........................................................ 23
7.4.2.2 FSLIB Initialization ................................................... 23
7.4.3
Data cache interface .................................................................. 24
7.4.5
Open file cache ........................................................................... 24
Data structures .............................................................. 2 5
7.5.1
PFS_PATHID .............................................................................. 25
7 .5.2
PFS_FID ....................................................................................2 6
7.5.3
PFS_ATTR..................................................................................2 7
7.5.4
PFS_STAT ..................................................................................28
7.5.5
PFS_NAMEID .............................................................................29
7.5.6
PFS_CWD ..................................................................................30
7.5.7
PFS_USER ................................................................................. 30
7.5.6
PFS_LIB_ENT............................................................................30
7.5.9
PFS_IDENT ................................................................................ 31
7 .5.10 Stat structure............................................................................31
7 .5.11 Dirent structure .......................................................................3 2

ROUTINE

8. 1

REQUIREMENTS •••.•••••••••••••..••••••..••••••.•••••..••••••••••••••••••• 1 4

DESCRIPTIONS .•.••••.••.•••••••••.••••••.•.••.••.•.•.•••••.••.•.••...•.•. 3 4

PFS interface ................................................................. 3 4
8.1.1
PFS_access *.............................................................................34
8.1 .2
PFS_faccess * ...........................................................................3 4
8.1.3
PFS_chdir .............................•...................................................3 5
8.1.4
PFS_fchdir ..................................................•.............................3 5
8.1.5
PFS_chmod ................................................................................36
8. 1 . 6

8.1. 7
8.1.8
8.1.9
April 20, 1992

PFS_fchmod ...............................................................................3 6
PFS_chown .....................•..........................................................3 6
PFS_fchown ...........................................................•...................3 6
PFS_close ..................................................................................3 7
Digital Confidential

PATHWORKS File System

8.1.10
8.1.11
8.1.12
8.1.13
8.1.14
8.1.15
8.1.16
8.1.17
8.1.18
8.1.19
8.1.20
8.1.21
8.1.22
8.1.23
8.1.24
8.1.25
8.1.26
8.1.27
8.1.28
8.1.29
8.1.30
8.1.31
8.1.32
8.1.33
8.1.34
8.1.35
8.1.36
8.1.37
8.1.38
8.1.39
8.1.40
8.1.41
8.1.42
8.1.43
8.1.44
8.1.45
8.1.46
8.1.47
8.1.48
8.1.49
8.1.50
8.1.51
8.1.52
8.1.53
8.1.54
8.1.55
8.1.56
8.1.57
8.1.58
8.1.59
8.1.60
8.1.61
8.1.62
8.1.63
8.1.64
April 20, 1992

PFS_closeandpurge *................................................................3 7
PFS_copyfile .•..•.•.•.•.....•...•................................•...•............•.....•3 8
PFS_create .........................................................................•......3 9
PFS_delete •..•.•....•.••....................•.••........•..••...•..••..•.••.•.............•4 0
PFS_dentpathid *......................................................................40
PFS_didpathid * ........................................................................40
PFS_diridfunc ...........................................................................41
PFS_di ri din it ............................................................................4 2
PFS_filesize .........•.•.....•.•.•...•..•..................................•..............42
PFS_ffilesize ••...•..••.•....••••...•.•....•..............•...•...........................4 2
PFS_fsync .........••...•..••.•.....•.•......•......•...••.......•..•.............•......•.43
PFS_fullpath ...................................................•..•..•........•...•...•.•43
PFS_getattr ............................•.......•.........•.....•...•...........•.•.......•44
PFS_fgetattr...............•..................•...........................................44
PFS_getcomment ....•...........•..•....•.•...........................................•4 4
PFS_getcwd ............•....................•..............•...•...•...........•...••.....4 5
PFS_getdents ........•.......•..•..................................•......................4 5
PFS_getextattr ..........................•......•...•...•.........•......................4 6
PFS_fgetextattr.........................................................................4 6
PFS_getpathid ................•.....•.............................•......................4 7
PFS_getprintident * .................................................................4 7
PFS_getsecurity * ....................................................................48
PFS_fgetsecurity * ...................................................................4 8
PFS_getuser *...........................................................................4 9
PFS_init ....................................................................................50
PFS_lock .................................•..•................•......•...................... 50
PFS_lseek..................................................................................5 1
PFS_mapname ........................ .-.................................................. 5 2
PFS_fmapname .......................................................................... 5 2
PFS_mkdir ........................•................................•...................... 5 2
PFS_m pxclose ........................................................................... 5 3
PFS_needfds .............................................................................. 5 3
PFS_needinodes ......................................................................... 5 4
PFS_open ................................................................................... 5 4
PFS_parse *..............................................................................5 5
PFS_purge ................................................................................. 5 5
PFS_read ................................................................................... 56
PFS_readdesc * ............... ········'······ ............................................ 5 6
PFS_releasedesc * .................................................................... 5 7
PFS_rename .............................................................................. 5 7
PFS_rmdir ................................................................................ 58
PFS_setattr ............................................................................... 5 8
PFS_fsetattr.............................................................................. 5 8
PFS_setcomment .......................................................................5 9
PFS_setextattr ........................•...•....•........................................ 5 9
PFS_fsetextattr..............................•.......................................... 5 9
PFS_setlognores ..............................................••........................ 6 0
PFS_setnotifym px.....................................................................6 0
PFS_setsecurity * ....................................................................6 0
PFS_fsetsecurity * ...................................................................60
PFS_shortpath ....•.....................................................................61
PFS_stat .............................................•...........•.•........................6 2
PFS_fstat...................................................................................6 2
PFS_statvfs ..........................................•.............•......................6 2
PFS_fstatvfs..............................................................................6 2
Digital Confidential
2

PATHWORKS File System

8. 2

8. 1. 6 5 PFS_sync...................................................................................6 3
8.1.66 PFS_treetop ...........•..................................................................63
8.1.67 PFS_ftruncate ........•.....................................................•....•.......63
8.1.68 PFS_unlock ...............................................................................64
8.1.69 PFS_unmap ............•..............................................................•...65
8. 1. 70 PFS_utime.............................................................................•...6 5
8. 1. 71 PFS_futime ............•..................................................................6 5
8.1.72 PFS_write ..............•................................................ ~ ................. 65
8.1.73 PFS_writedesc * .......................................................................66
File System Library (FSLIB) interface ••••••••••••••••••••••••.••• 6 6
8.2.1
FSLIB_access * .........................................................................66
8.2.2
FSLIB_faccess * ........................................................................66
8.2.3
FSLIB_chdir ..............................................................................6 7
8.2.4
FSLIB_fchdir.............................................................................6 7
8.2.5
FSLIB_chmod..........•..................................................................67
8.2.6
FSLIB_fchmod ........•..............,....................................................67
8.2.7
FSLIB_chown.............................................................................68
8.2.8
FSLIB_fchown ...........................................................................68
8.2.9
FSLIB_claim ..............................................................................68
8.2.10 FSLIB_close ...............................................................................69
8.2.11 FSLIB_convert * .......................................................................69
8.2.12 FSLIB_create * .........................................................................70
8.2.13 FSLIB_dentpathid *...................................................................70
8.2.14 FSLIB_didpathid *.....................................................................70
8.2.15 FSLIB_diridfunc ........................................................................71
8.2.16 FSLIB_diridinit .........................................................................71
8.2.17 FSLIB_filesize ...........................................................................71
8.2.18 FSLIB_ffilesize .........................................................................71
8.2.19 FSLIB_fsync ..............................................................................72
8.2.20 FSLIB_getattr............................................................................7 2
8.2.21 FSLIB_fgetattr ..........................................................................72
8.2.22 FSLIB_getcomment....................................................................73
8.2.23 FSLIB_getdents ..........................................................................7 3
8.2.24 FSLIB_getextattr * ...................................................................73
8.2.25 FSLIB_fgetextattr * ..................................................................73
8.2.26 FSLIB_getprintident * ..............................................................7 4
8.2.27 FSLIB_getsecurity * .................................................................7 4
8.2.28 FSLIB_fgetsecurity *................................................................7 4
8.2.29 FSLIB_init.................................................................................7 5
8.2.30 FSLIB_lock ................................................................................7 5
8.2.31 FSLIB_lookup *.........................................................................7 6
8.2.32 FSLIB_lseek ..............................................................................7 6
8.2.33 FSLIB_mapname ........................................................................76
8.2.34 FSLIB_fmapname ......................................................................7 6
8.2.35 FSLIB_mkdir.............................................................................77
8.2.36 FSLIB_mpxclose ........................................................................77
8.2.37 FSLIB_mpxopen ........................................................................78
8.2.38 FSLIB_open ...............................................................................7 8
8.2.39 FSLIB_purge .............................................................................7 8
8.2.40 FSLIB_fpurge ..................................................•.........................7 8
8.2.41 FSLIB_read ................................................................................79
8.2.42 FSLIB_readdesc *......................................................................79
8.2.43 FSLIB_rename ...........................................................................80
8.2.44 FSLIB_rmdir.............................................................................80
8.2.45 FSLIB_setattr............................................................................80

April 20, 1992

Digital Confidential

PATHWORKS File System

8.2.46
8.2.47
8.2.48
8.2.49
8.2.50
8.2.51
8.2.52
8.2.53
8.2.54
8.2.55
8.2.56
8.2.57
8.2.58
8.2.59
8.2.60
8.2.61
8.2.62
8.2.63
9

FSLIB_fsetattr ..........................................................................80
FSLIB_setcomment....................................................................81
FSLIB_setextattr * ...................................................................81
FSLIB_fsetextattr * ..................................................................81
FSLIB_setsecurity * .................................................................8 2
FSLIB_fsetsecurity *................................................................82
FSLIB_stat.................................................................................8 2
FSLIB_fstat .........•.....................................................................8 2
FSLIB_statvfs............................................................................8 2
FSLIB_fstatvfs ..........................................................................8 2
FSLIB_sync ...............................................................................83
FSLIB_ftruncate........................................................................8 3
FSLIB_unlock ............................................................................84
FSLIB_unmap .............................~ .............................................. 84
FSLIB_utime .............................................................................84
FSLIB_futime ............................................................................84
FSLIB_write ....................•.........................................................8 5
FSLIB_writedesc *....................................................................8 5

STANDARD LIBRARIES ••••••.••.•...•••..••••••••••••••.•••• .••••.••••.•••.•••••••••• 8 6
9.1
ODS2 DOS library ........................................................... 8 6
9.1.1
Namespace .................................................................................8 6
9.1.2
Attributes ..................................................................................8 6
9.1.3
Security.•...................................................................................8 7
9.1.4
Datapaths ...................................................................................8 7
FID cache ...................................................................................8 7
9.1.5
9.1.6
Directory cache .........................................................................8 8
9.1.7
Path cache ..................................................................................88
9.2
ODS2 MAC library ••••••••.•..•••••••....••...•...•..••.•..•..•..•..••••.••.. 8 8
9.2.1
Namespace .................................................................................8 8
9.2.2
Attributes ..................................................................................8 9
9.2.3
Security.....................................................................................9 0
9.2.4
Data paths ...................................................................................9 0
9.2.S
Name cache ................................................................................9 1

Appendix A - VMS ODS level 2 file system ...••....•...•...•......•...•...•...•. 9 2
A.1
Directory structure ••••••••••.•••••••.•.•••••••••.•.•..•••.•..•.•.••..•..•. 9 2
A.2
File structure •.•••.••.••••••••••.••..•.•.••.•.••.••••.•••.•..•...••.•..••..•• 9 2
A.2.1
Access Control Lists (ACL) ....................................................... 92
A.3
File attributes ..••••••.•....••.•••••.•..••.•.•.••.••••.••••••.•.•..•••..•.•.•• 9 3
A.3.1
File creation time ......................................................................9 3
A.3.2
File revision time .....................................................................9 3
A.3.3
File backup time ........................................................................9 3
A.3.4
File expiration time .................................................................. 93
A.3.5
File organization .......................................................................9 3
A.3.6
Record structure .......................................................................93
A.3.7
Record attributes ......................................................................94
A.4
File allocation •••••.•••••••••..•.•.•..••••••.•.•••••••.•••.•.••...••.••••••.•• 9 4
A.4.1
File header.................................................................................94
A.4.2
Index file ...................................................................................94
A.4.3
Bitmap file ................................................................................94
A.4.4
Quota file ...................................................................................9 5
A. 5
Security model •••.•.•..•••••••••••..••••.••••..••..••••.••••.••••••.•..•••••. 9 5
Appendix B - MSDOS FAT file system ..•..••••••..•.••••..•..•.••••..•••••..••.••. 9 6
April 20, 1992

Digital Confidential

PATHWORKS File System

B. 1
B. 2
B. 3
B. 4
B. 5

Directory structure •••••••••••••••••••••••••••••••••••••••••••••••••••••••• 9 6
File . structure ................................................................ 9 6
File attributes ................................................................9 6
B.3.1
Modification time ............................................•.........................9 6
File Allocation ................................................................9 6
Security model ...............................................................9 6

Appendix C - Macintosh HFS file system ••••••••••••••••••••••••••••••••••••.•••• 9 7
C. 1 Directory structure •••••••••..•••••••••••••••••••••••..••••••.•••••••••.••• 9 7
C.2 File structure ................................................................9 7
C.2.1
Data fork ....................................................................................9 7
C.2.2
Resource fork ............................................................................9 7
C.3
File attributes ................................................................9 7
C.3.1
File creation time ......................................................................9 7
C.3.2
File modification time ...............................................................9 7
C.3.3
File backup time ........................................................................9 8
C.4 File allocation ................................................................9 8
C. 5
Security model ..•••••••••.•••••......••••...•..••.••.•...•••••...•.••••••..•• 9 8
Appendix D - FSI interface •••.•..•••••••••••...•••.•...•.•••••..•..••••••••••••••.••.• 9 9
D. 1
General Architecture •.••••.•••••.••.•.•.•.•••••.•.••...•••.•.••••••••••...• 9 9
D.1. 1
File Descriptor Multiplexing ....................................................9 9
D.1.2
Volume Services ........................................................................ 100
D.1.3
Directory IDs ............................................................................ 100
D.1.4
Namespace ................................................................................. 100
D.1.5
Streams .....................................................................................100
D. 1. 6
Extended Attributes ................................................................... 100
D. 1.7
FSI Routine Classification ......................................................... 101
0.2
PATH ID (FSl_PATHID) ..•.•••......••.....•...•.••...•...••.•..••..•..... 102
0.2.1
File ID (FSl_FID) ..................................................................... 103
D. 3
ROUTINE SUM MARY ..••..•..•..••..•...•..•...•..•.••••.....•••.•.••..••..•. 1 0 5
D.3.1
FSl_access ................................................................................. 105
D.3.2
FSl_chdir .................................................................................. 105
D.3.3
FSl_fchdir ................................................................................. 106
D.3.4
FSl_chmod ................................................................................. 106
D.3.5
FSl_fchmod................................................................................106
D.3.6
FSl_chown .................................................................................107
D.3. 7
FSl_fchown ................................................................................ 107
D.3.8
FSl_close ...................................................................................107
D.3.9
FSl_copyfile ..............................................................................108
0.3.10 FSl_create ................................................................................. 109
D.3.11 FSl_delete .................................................................................. 110
D.3.12 FSl_diridinit ............................................................................. 110
D.3.13 FSl_diridfunc ............................................................................ 111
D.3 .1 4 FSl_ffilesize.............................................................................. 111
D.3. 1 5 FSl_fsync .................................................................................. 111
D.3.16 FSl_fullpath ..............................................................................112
D.3.17 FSl_getattr ................................................................................ 112
0.3 .1 8 FSl_fgetattr............................................................................... 11 3
D.3 .1 9 FSl_getcomment ........................................................................ 11 3
D.3.20 FSl_getcmd ................................................................................ 113
0.3 .21 FSl_getdents .............................................................................. 11 3
0.3.22 FSl_getextattr ........................................................................... 114
0.3 .23 FSl_getpathid ............................................................................ 11 5
D.3.24 FSl_lock .................................................................................... 116
April 20, 1992
Digital Confidential
5

PATHWORKS File System

D. 3 .2 5
D.3.26
D.3.27
D.3.28
D.3.29
D.3.30
D.3.31
D.3.32
D. 3. 3 3
D.3 .34
D.3 .3 5
D.3.36
D..3. 3 7
D.3.38
D.3.39
D.3 .40
D. 3 .41
D.3 .42
D.3 .43
D.3.44
D.3 .45
D.3.46
D.3.47
D.3 .48
D.3.49
D.3.50
D.3".51
D.3.52
D.3.53
D.3.54
D.3.55

FSl_lseek................................................................................... 11 7
FSl_mapname ............................................................................118
FSl_fmapname ........................................................................... 118
FSl_mkdir .................................................................................118
FSl_mpxclose ............................................................................ 119
FSl_needfds ...............................................................................119
FSl_needinodes .......................................................................... 119
FSl_open .................................................................................... 1 20
FSl_purge .................................................................................. 1 21
FSl_read .................................................................................... 1 21
FSl_rename ...............................................................................1 21
FSl_rmdir ................................................................................. 122
FSl_setattr ................................................................................1 2 2
FSl_fsetattr............................................................................... 122
FSl_setcomment ........................................................................ 1 23
FSl_setextattr ........................................................................... 1 2 3
FSl_setlognores ......................................................................... 1 2 4
FSl_setnotifympx...................................................................... 1 2 4
FSl_shortpath ........................................................................... 1 2 5
FSl_stat ..................................................................................... 125
FSl_fstat.................................................................................... 1 2 5
FSl_statvfs ...............................•................................................ 1 2 6
FSl_fstatvfs ............................................................................... 126
FSl_sync.................................................................................... 1 2 6
FSl_ftruncate ............................................................................ 126
FSl_tretop ................................................................................. 127
FSl_unlock ................................................................................ 127
FSl_unmap ................................................................................ 128
FSl_utime .................................................................................. 1 28
FSl_futime ................................................................................ 128
FSl_write .................................................................................. 129

Appendix E - RMS Extent for Macintosh file format ...•..•••..•••...••...•. 1 3 0
E.1
File Format ••••••••••.•••••..•..••..•••••..•..••..•..•...•.••••....•..•...••.•• 130
E.1.1
File Semantics ........................................................................... 130
E.1 .2
Header........................................................................................ 1 31
E.1.2.1 Allocation .................................................................... 131
E.1.2.2 Stream Descriptors .................................................... 131
E.1.2.3 Mapping Pointers ...................................................... 131
E. 1. 3
Data Stream Format .................................................................. 1 3 1
E.1.4
Resource Stream Format........................................................... 1 31
E. 2
Extension Structure .•..••.••••.•..••.•.•.••.•••.••.••..••..••.••..••..••.•. 1 3 1
E.2.1
Initialization ............................................................................. 1 3 2
E.2.2
RMS support routines ............................................................... 1 3 2
E.2.3
Data Structures ......................................................................... 132
E.2.3.1 CXT - Context Block..................................................... 132
E.2.4
Global Routines .......................................................................... 1 3 3
E.2.4.1 EXT_CONNECT- RMS $CONNECT callout .................... 133
E.2.4.2 EXT_GET - RMS $GET callout ...................................... 133
E.2.4.3 EXT_PUT - RMS $PUT callout..................................... 134
E.2.4.4 EXT_FIND - RMS $FIND callout ................................. 134
E.2.4.S EXT_DISCONNECT- RMS $DISCONNECT callout ........ 134
E.2.4.6 EXT_DISPLAY - RMS $DISPLAY callout ................... 134
E.2.4.7 EXT_MUCK_XABFHC - callback for scan XAB ......... 134
E.3
Restrictions ••••.•.•.••••.•.••.••...•..•.•.•..••..••.•.•••..•..••..•••••.•••••. 134
April 20, 1992

Digital Confidential

PAnIWORKS File System

E.4

E.3. 1
File writes ...........................................•.....................................1 34
E.3.2
Buffer usage ..............................................................................1 34
E.3.3
File updates ............................................•...................•..............1 34
E.3.4
Printing Files ..........................................•.................................135
lssues ........................................................................... ~135

April 20, 1992

Digital Confidential

PATHWORKS File System

PREFACE
This document contains proprietary information of Digital Equipment Corporation. This document and
the information it contains may only be used in the design, production, or manufacture of products for
Digital Equipment Corporation.
The information in this document is subject to change without notice and should not be construed as a
commitment by Digital Equipment Corporation. Digital Equipment Corporation assumes no
responsibility for errors that may occur in this document.
The specifications and drawings, herein, are the property of Digital Equipment Corporation and shall
not be reproduced or copied or used in whole or in part as the basis for the manufacture or sale of items
without written permission.
MSDOS, LanManager and LMU are registered trademarks of Microsoft Corporation.
Macintosh is a registered trademark of Apple Computer, Inc.

April 20, 1992

Digital Confidential

PATHWORKS File System

REVISION HISTORY
Michael Evans

21-Apr-1992

Initial creation

Michael Evans

3-Aug-1992

Revise structure of document and add design
details

April 20, 1992

Digital Confidential

PATHWORKS File System

INTRODUCTION
This specification describes the PATHWORKS File System for Hydra Servers. The specification
describes the functional and structural components of the file system. External data structures and
prominent internal data structures are defined. The specification provides a functional definition of
library interfaces such that additional libraries may be developed and added to the file system.
The specification does not describe the packaging issues or functional delivery issues. Where
appropriate, considerations for these issues are noted.

April 20, 1992

Digital Confidential

PATHWORKS File System

TERMS AND SPECIFICATION SYNTAX
Throughout this document certain terms are assumed to be familiar to the reader. Knowledge of the
structural components of a file system are assumed. Structural components of the VMS ODS level 2
file system, MSDOS FAT file system and Macintosh HFS file system are provided as a reference to
provide context for the functions described in this specification. Readers with detailed knowledge of
these file systems will fmd this information somewhat tedious.
The following terms are used throughout the document and are presented here to eliminate confusion
which may arise due to conflicting defmitions. These defmtions are not intended to be absolute nor are
they likely to be precise. However, this is what is meant when then following terms are used.
Attributes

General file attributes including file characteristics (hidden, directory,
etc), file times (creation, modification, backup, etc), file size, parent
directory, file ID, etc.

Stream

Identification of file data associated with a particular identifier.
Macintosh files have two such identifiers, "data" and "resource". All
other files have only one such identifier.

Fork

Synonymous with stream and may be used interchangeably. Most
prominet use is wihtin the context of describing the Macintosh file
system

Directory

Structure containing files or other directories

Folder

Synonymous with directory and may be used interchangeably. Most
prominent use is within the context of describing the Macintosh file
system.

File

Data container. This term is used to describe an addressable entity. It
generally does not include directories (which are considered part of the
address).

Volume

Structure containing directories and files. Represents a collection of
directories and files made accessible to the client.

Synonymous with volume in the context of NOS structures.
Represents the top level directory of a set of files which are made
available to clients.

Client

Remote operating system or user. Generally used to refer to the
orginator of file system requests.

Server

Layer of software above the file system which ececutes operations on
behalf of a client. May also be used to indicate the entire system which
executes operations on behalf of the client. Where confusion may arise
the two uses will be noted as server system or server software.

NOS

Network Operating Sysytem. Generally used to indicate operations or
attributes associated with a supported client type, NOS security, NOS
file system, NOS user, etc.

Host

System on which server software executes. Refers to characteristics of
this system, host security, host file system, host user, etc.

Name space

Identifies the semantics and syntax of a file specification. Example
namepsaces are MSDOS, Macintosh, Unix, VMS, etc.
Digital Confidential

April 20, 1992

PATHWORKS File System

Path

A file location specification. This may be presented in one of many
namespaces.

File System

Defines the semantics for the storage and retrieval of files.

Meta Data

Information about the name, location and attributes of a file.

File Service

A set of routines which define the service offered to clients of one
particular type, i.e. MSDOS file service or Macintosh file service.

The following syntax is used throughout the document.

Denotes optional quantities

{}n

Denotes n or more of the term enclosed in quotes

April 20, 1992

Digital Confidential

PATHWORKS File System

REFERENCES
This specification was written using the following reference material:
Inside Macintosh, Volume IV
Inside AppleTalk
VMS File System
DOS 3.1 User Guide
Guide to porting LMU
PATHWORKS for OS2 Administrator's guide
LanManager Programming Handbook
The top level interface is designed to be a super-set of the FSI interface for Microsoft's LanManager for
Unix. Routine call semantics are preserved where applicable. New routines have been added to provide a
complete set of functions required to support file service access requirements.

April 20, 1992

Digital Confidential

PATHWORKS File System

DESIGN REQUIREMENTS
The following list summarizes the requirements which have influenced this design. Careful
consideration has been paid to insure these requirements are met. The design is tightly coupled to these
requirements such that a change in requirements could have great impact on the application of the
design. It is possible that a change in requirements could cause major redesign efforts.
1. All information relating to a file must be tightly coupled to that file.
For VMS, this requirement translates into a requirement to store all applicable file meta data in
application ACEs attached to the file.
2. Top level interface must support LMU server software without major redesign
This requirement is driven by an agressive schedule and limited resources.
3. The file system must perform at par or better than existing PATHWORKS products.
This is a loosely defined metric which needs careful evaluation. Every effort has been made to
optimize access given the features of the host file system. There is a tradeoff between file system
performance and file system integrity.
4. The file system must operate in a distributed fashion across a VAXCluster.
This requirement has particular significance to the various cache designs in the file system. All file
caches must be distributed. Writeable caches must have data distributed and read only caches must
have consistency distributed.
5. NOS security models and host security models are completely independent.
There will no attempt to provide NOS security in terms of host security. The various security
models involved are sufficiently different such that a mapped security model would not yield
suitable results.
6. NOS file attributes are completely independent.
Attributes set from one NOS will not affect attributes of another NOS, even if there is an obvious
mapping between them. Currently there are a number of such file attributes, hidden, read-only,
creation time and modification time. (While both MSDOS and Macintosh specify a SYSTEM
attribute it is not clear a DOS system file is also a Macintosh system file. It is not clear such a
file could even be shared between NOS types.)

NOTE
A file may be readonly to one NOS and writeable to another. File modification
times will not be visible between NOS types. This means that a file modified by
one NOS may not be seen as modified by another.There is obvious detrimental
behaviour as a result of this requirement.
However, backup times represent attributes that although common between NOS
types may not be suitable for sharing. Consider a backup utility running on both
a Macintosh and a PC client. If backup times were shared neither client would
have a complete backup of the file set. It may or may not be adviseable to set up
such a backup scenario but the results certainly would not be what was intended.
Restoration of client backups will necessarily destroy the file meta data (and
,
potentially file data) associated with other NOS types. It is therefore not
')
suggested that backups be done thru clients except hfl:Hngle NOS applications.
A~rll 20, 1992
Digital Confidential

PATIIWORKS File System

The host backup facilities should be exclusively used in multiple NOS
environments.
7. Data presented to the cache interface must be in stream format.
This requirement simplifies the data paths in the server. The file system must provide all record
deblocking prior to file data being entered in the cache. This requirement PRECLUDES random
access to non stream format files as there is no way to map stream offsets to record offsets.
Sequential access will be allowed.
This requirement also precludes output in non-stream format of cached files as there is no
mechanism to guarantee the order of writes from the cache. There is no direct mapping between
stream offsets and record offsets. Record offsets can only be calculated in sequential write order.
Sequential writes to non stream files will be allowed.

NOTE
There is a pending request to allow the server system to create non-stream files.
If this request is to be honoured it will require files be written without the
assistance of the cache. This will likely be accomplished with the atomic copy
function. (This function has the option of bypassing the cache).
There is no current mechanism for specifying the record attributes to attach to a
file. All files created on behalf of a client will be created as stream files. We do
not have the option of creating a VAR file format for what appears to be an
ASCil file (see above description of cache requirements).

April 20, 1992

Digital Confidential

PATHWORKS File System

OVERVIEW
The file system interface for PATIIWORKS has been abstracted to provide both NOS independence and
PATHWORKS platform independence. PFS (PATHWORKS File System) provides this abstraction.
PFS provides a single interface to multiple host file systems. Functions are provided to access files,
create files, delete files, rename files and provide access to information about files. Files may be
accessed by the semantics of the supported client using the file syntax of the supported client. PFS
provides all translation functions necessary to map the client access to a host file system access.
PFS is a superset of the Microsoft LMU FSI interface. This choice has been made due to a large body
of existing code which uses this interface. While non of Microsoft's software is used, in whole or in
part, in the implementation of PFS, it is necessary to credit the origin of the interface. An algorithmic
view of the implementation of the LMU FSI is provided in Appendix D.

7 .1

Functional

overview

PFS provides functions to create files, delete files, rename files, store and retrieve file attributes and
store and retrieve data associated with the file. PFS provides file access in the semantics and syntax of
both MSDOS and Macintosh clients. This access includes file names, path names, data format and file
attributes.
PFS operates in one of three namespaces (VMS, MSDOS or Macintosh), all of which are tightly
coupled. This means there is a strict relationship between names in various namespaces. While this
relationship presents obvious limitations, it allows file system functions be be significantly
simplified.
PFS provides completely disjoint sets of file attributes to be associated with files.
PFS will provide functions for storing and retrieving NOS security information, provided the
underlying file system is willing to accept the requests. This means that servers need to be prepared to
store security data elsewhere if the underlying file system rejects the request (NET .ACC,
USERMODE.LMX [is this the correct ACL file for LMX ??] , etc).
PFS will provide host security checking provided that the server identifies the host user and all host
user access privileges and rights. If this information is not provided PFS will allow access without
regard to host security.
PFS supports all native file organizations for read access. Write access will be limited to stream format
only. PFS will reject write access requests to non stream files, i.e. the file will not be opened in the
hope that writes will not actually occur.

7 .2

Summary of functions

The following table summarizes the functions provided by PFS.
Directory access functions
PFS_chdir
PFS_diridfcn
PFS_diridini
PFS_getcwd
PFS _getdents
PFS_mkdir
PFS_rmdir
File access functions
April 20, 1992

- Change default directory using PATHID structure
- Convert a directory ID to path name
- Initialize directory ID handling
- Get the current default directory
- Get directory entries in "struct dirent" format
- Create a directory
- Delete a directory

Digital Confidential

PATIIWORKS File System

PFS_close
PFS_copyfile
PFS_create
PFS_delete
PFS_open
PFS_purge
PFS_rename
PFS_truncate
PFS_unmap

- Close a file
- Atomic file copy
- Create a file
- Move file to purge area or delete it (check attributes)
- Open a file for read and or write access
- Delete a file
- Rename file
- Trucnate the file
- Clean up a memory mapped file

Datapath functions
PFS_fsync
PFS_lock
PFS_lseek
PFS_read
PFS_readdesc *
PFS_releasedesc *
PFS_unlock
PFS_write
PFS_writedesc *

- Flush all written data associated with a file
- Lock a byte range in a file
- Set the current file offset for read/write functions
- Read data from file
- Read data by reference
- Release data descriptors
- Unlock byte range
- Write data to file
- Write data by reference

File attributes functions
PFS_chmod
PFS_chown
PFS_getattr
PFS_getextattr
PFS_getcomment
PFS_filesize
PFS _setattr
PFS_setcomment
PFS_setextattr
PFS_stat
PFS_utime

- Change file protection
- Change file owner
- Get file attributes
- Get extended attributes (not supported)
- Get comment associated with file
- Get file size in bytes
- Set file attributes
- Set file comment
- Set extended attributes
- Get file attributes in "struct stat" format
- Set file access and modification times

Path functions
PFS_dentpathid *
PFS_didpathid *
PFS_getpathid
PPS _fullpath
PFS_mapname
PFS _shortpath
PFS_treetop

- Convert "struct dirent" format to pathid
- Tmaslate a default directory plus NOS path into a host path
- Translate a NOS path into a host path
- Get translated host path
-Translate a NOS filename to a host filename (name only)
- Get translated path beyond current default directory
- Set start of NOS path in translated path

General support functions
PFS_init
PFS_mpxclose
PFS_needfds
PFS_needinodes
PFS_setlognores
PFS _setnotifympx
PFS_statvfs
PFS_sync

- Initialize file system
- Close host file associated with file descriptor
- UNIX only
- UNIX only
- Set routine to call when resources are exhausted
- Set routine to call when file multiplexing occurs
- UNIX only
- Flush all written data associated with all files

Security functions
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_access
PFS_faccess *
PFS_getsecurity *
PFS_getuser *
PFS_putsecurity *

7. 3

- Check host access to a file
- Check host access to an open file
- Retrieve NOS security data
- Return PFS_USER structure for specified host user
- Store NOS security data

File service components

A file service may be defined by four major components; namespace, attributes, security and data paths.
These components allow a service to offer files stored in its native file system to a client using another
file system.To implement a file service a mapping between components is necessary.
There are number of components which comprise a file system. Some of these components are more
visible to a file service than others. Some file system components will defme file service components
while others may only have incidental effects. The following table shows how file system components
are mapped to file service components.
File System Component

File Service Component

File name syntax
Directory structure
File allocation
File attributes
Security
File meta data
Quotas

Namespace
Namespace
Data paths
Attributes
Security
Attributes, Security, Namespacd
Data paths

The overall effectiveness of a file service will depend on how complete the mapping between
components can be defined. In general, the more robust the host file system, the more effective the file
service will be.
The mapping of file serVice components to the VMS file system is defmed in section 9.

7. 3. 1

Namespace

Namspace defmes the file name syntax, path syntax and path semantics. A given file service may need
to access files by name, by ID or possibly other mechanisms. These mechanisms need to be mapped to
the supporting file system.
File name syntax varies amoung file services. Filenames range in length from 11 characters to 255
characters and consist of character sets ranging from alphanumeric to virtually unlimited. This range
presents a challenge to a file service which must either be able to map names or limit the range to a
more manageable set. Any limits imposed will be visible to the client
Path syntax and semantics also vary amoung file services. Path lengths may range from 1 member to
virtually unlimited. File systems may impose limits on the number of members in a path and this will
be visible to a client. Path semantics may be biased, relative or absolute.
Absolute path semantics specify each member of the path using a name appropriate to the file service.
This name may be a character set name or an ID.
Relative path semantics specify members relative to prior members. There may be "special" names
assigned to "parent" members (i.e. VMS path [-]) or parent members may be specified by the absense
of a named member (i.e. Macintosh <null>).
Biased path semantics present a base path and a reative path. The base path may be a named path or an
ID (i.e. VMS rooted path [member.][member] or Macintosh ID plus named path).
April 20, 1992

Digital Confidential

PATHWORKS File System

NOTE
The VMS file system is among the most restrictive with respect to namepsace. The
filename character set is the most restrictive as is the effective path member length.
VMS does allow filenames greater in length than both MSDOS and Macintosh but
this is largely negated by character set limitations.
The following table sumarizes the namespace characteristics of various clients and the VMS file
system.
Characteristic
Filename length

MSDOS
8 with 3 ch
extension

Macintosh
31

VMS
39 with 39 ch
extension

Character set

Any greater than
<space> and less
than <del> with the
exception of% and

Any except <null>
and:

Alphanumeric or $,

*
Path length

Unlimited depth
[Character limit ??]

Unlimited depth
[Character limit??]

8 member depth*
255 character length

Path semantics

Absolute

Absolute, biased by
ID, or relative

Absolute, biased by
name, or relative

Access by:

Name or 16 bit
ID**

Name or 32 bit
ID***

Name or 48 bit ID

File limits

[FAT limit ??]

2**32

2**24 per volume
2**32 per bound set

Directory limits

2**16

2**32

2**24

*VMS provides a mechanism to "fix" a bias (concealed logical name) such that unlimited path lengths may
be accessed via 8 member relative paths. This mechanism is not supported across all applications, most
notibly BACKUP. The VMS path length limit applies to applications which use RMS only as there is
no limit to the depth of a path processed directly via QIO.
** MSDOS provides "fixed" directory offsets and functions may reference files via this fixed offset. This in
effect becomes a 16 bit ID which may reference the file within the context of a path.
*** Macintosh assigns a 32 bit ID to each file and directory created on a volume. This number is unique
and will not be reused when a file or directory is deleted. The number bears to special relationship to the
file and may be swapped between files (a numeric rename function). This number is used to establish
links between files declared as "alias".
PFS makes no assumptions about the mapping functions associated with a file system. The mapping
of client namepsace to file system namespace is entirely defined by the file system library. PFS uses
file system library functions to map client names and IDs. PFS provides interface routines to translate
biased paths into absolute paths.

7. 3. 2

Attributes

File attributes are maintained by the file service to provide information to clients about the files to
which the attributes apply. Clients have their own set of attributes which they use for various purposes
as does the host file system. Mapping these attributes to file system attributes is generally not
complete.
April 20, 1992

Digital Confidential

PATHWORKS File System

File service attributes include information about when a file was created, last modified, last accessed or
backed up. File characteristics such as whether the file is a directory, visible, archived, copy protected
and so on are maintained by the file service. File data formats are set when the file is created or
modified and are made availabe to the file service.
The following table shows the various atributes associated with the MS DOS, Macintosh and VMS file
systems.

Attribute
Create time
Modified time
Access time
Backup time
Directory

MSDOS
Modified time
Modified time
Modified time

Archive
Visible
System
Backup Needed
Rename Inhibit

Archive
Hidden
System

Delete Inhibit
Multiple User
Write Inhibit
Copy Protect
Volume ID
Finder Information

NIA
NIA

NIA
Directory

Macintosh
Create time
Modified time
Modified time
Backup time
Implied

VMS
Create time
Revised time
Revised time
Backup time
FCH$V_DIRECTO
RY

NIA

NIA
NIA
NIA

Invisible
System
Backup Needed
Rename Inhibit

NIA
NIA

Delete Inhibit
Multi User
Write Inhibit
Copy Protect

Read Only

NIA

Volume

NIA

Finder Info

Backup time
Write access to
directory
Delete access to file

NIA
Write access to file

NIA
NIA
NIA

As can be seen from the above table, mapping client attributes to file system attributes will not
provide a sufficeint mapping. It is clear some form of storage and retrieval of attributes must be
provided by the underlying file system. The complex challenge to a file system is how to reflect the
client attributes in terms of file system characteristics in a "least surprise" fashion.
PFS makes no assumptions about the mapping between client attributes and host file system
attributes. The underlying file system may be as complete or incomplete as necessary. PFS will pass
the limitations on to the server which will necessarily make the limitations visible to the client.
PFS will honor the following attributes:
Read Only
Delete Inhibit
Rename Inhibit
Copy Protect

Directory

PFS will not allow writes to the file
PFS will not allow the file to be deleted
PFS will not allow the file to be renamed
PFS will not allow the atomic copy to be used on the file. However,
there is no mechanism to prevent an application from copying the file
by direct open and read.
PFS will not allow direct access to the file

The remaining attributes are stored and retrieved to support server functions. It is up to the server to
apply these attributes to file service functions.

7 .3.3

Security

Client security models vary greatly. There is so much disparity between sercurity models that any
attempted mapping would compromise all models. Given this, client security must be implemented
independently of the native file system security model. However, native file system access may still be
restricted by the underlying native security model. This dual model provides for client security models
to be implemented at the expense of additional system management to establish the relationship
between client users and host system users.
April 20, 1992

Digital Confidential

PATIIWORKS File System

PFS provides access to secuirty data stored by servers but does not interpret the data in any way. The
services are provided to associate client security data with the objects to which they apply.
PFS will pass host user identification information to the file system library. The file system library
may choose to use this information as necessary. It is the responsibility of the server to establish the
relationship between the client user and the host user.
All file systems are expected to keep track of which files they create on behalf of a server. It is
necessary for a file system to be able to distinguish between files it has created and those which were
created outside the server such that a hybrid security model may be implemented. This model will check
host security only if the file was not created by the server.
PFS will pass the current security mode to the file system library. It is the responsibility of the server
to determine the security mode for the path. File system libraries are expected to be capable of dealing
with the following three security modes:
Always
Foreign
Never

Check native security on all accesses
Check native security only if the file was not created on behalf of the
server.
Ignore all native security

These file system security modes correspond to the sever security modes HOST, CREATOR and NOS.

7. 3 .4

Data Paths

File services generally deal with stream file formats but there is no assumption about the data formats
of the underlying file systems. For this reason there may be a conversion required between native file
formats and file service formats.
PFS provides for this conversion by allowing a file system to "claim" a data path. This claim function
is more restrictive than the path claim function in that the claim is applied to the path file system
only. This partitioning allows PFS to obtain the path owner, get the file characteristics and then ask
the file system to claim the data path give the characterisitcs. This parititoning allows file systems to
claim paths without necessariliy obtaining file characterisitics (which may only be imporatant if the
file is actually to be accessed).
All file data which passes thru the data cache must be converted to stream format. It is the
responisbility of the underlying file system to supply this conversion. The file system will be supplied
context infomation to support this translation. The information is maintained completly by the file
system, i.e. it is in no way interpretted outside the file system.
It is possible that a file system may implement a different set of functions to deal with files of various
organization and record format. These functions will be established by the FSLIB_claim_datapath()
function. This routine is called at file open time.
NOTE
There are a number of implemenation options around datapaths. These options are
briefly described below. For the purposes of this specification·option 2 listed below
will be assumed.
1. Implement one set of datapath functions and dispatch the appropriate routines based on
record format.
This option allows one set of vectors to be referenced and reduces the data storage
required for the PFS_FID stucture. The tradeoff here is that record formats may need to
be checked on every access and an additional call is placed in the data path.
April 20, 1992

Digital Confidential

PATHWORKS File System

2. Implement a unique set of function vectors for every combination of record formats
supported.
This option allows vectors to be referenced at the expense one copy per file format.
This is most likely the best compromise as file systems which only support one file
format need to do nothing special. File systems which support multiple record formats
need to create one set of function vectors for each supported record format.
3. Copy the function vectors to the PFS_FID structure and allow the
FSLIB_claim_datapthO function to modify the copy.
This option would support the most number of combinations in the simplest fashion
as only a few vectors need to be modified.

7 .4

Structural

overview

PFS is partitioned into two major components, PATHWORKS File Interface and File System Library
(FSLIB).

PATHWORKS
File Interface

FSLIB 1

FSLIB 2

Figure 1. File system top level structure

7 .4. 1

Top level interface

The top level interface provides argument checking and dispatch functions to the appropriate FSUB.
The FSLIB is selected during PFS_getpathid() by calling each FSLIB's FSLIB_claim() routine.
FSLIB_cliam() will determine if this file system owns this path and if so, will supply a set of vectors
to handle all remaining FSUB functions.
All FSLIBs are expected to handle ALL functions, even if the action is simply to return success or
failure. The top level routines DO NOT check the validity of a vector prior to dispatch.

7 .4.2

File System Library Interface (FSLIB)

A File System Library (FSLIB) is a collection of routines which implement the file system functions
necessary to support PFS functions. There is no formal definition of file system such that a clear set of
rules may be established on what is and what is not a file system. Suffce it to say that if a set of
routines is prepared to handle file system functions, PFS will be prepared to use them.
An FSLIB may support "variant" file systems within it. Each variant is treated as an independent file
system and only shares the FSUB_init routine with its other variants. This mechanism allows
April 20, 1992

Digital Confidential

PATIIWORKS File System

multiple collections of routines to be grouped within a file system library. It should be stressed that
each variant is treated separately and must be capable of identifying the paths on which it will operate
without regard to its other variants.
The FSLIB functions are roughly parallel to the PFS functions, i.e. PFS does very little except find
the appropriate FSLffi for a given path and dispatch FSLIB functions to handle PFS functions.
PFS requires that a given path resolve to at least one FSLIB. There is no implied hierarchy in a set of
FSLIBs nor may any one library expect it being asked to handle a path given anopther has rejected the
path. Each FSLIB must be capable of identifying paths which belong to it, independent of decisions
made by another FSLIB. This is crucial given there is no implied order in sequencing path ownership
functions.

7 .4 .2.1 FSLIB Path Claim
Each path on which PFS must operate must be claimed by at least one file system. There is a
possibility that multiple file systems may handle a given path and if so, the first to claim it will be
given the opportunity to service it. Once a path is claimed the FSLIB will be responsible for handling
all subsequent operations on that path.
The FSLIB is given a "pseudo" file system path defining the "root" of the path. In most cases this path
is sufficient to determine ownership. Path ownership may be a function of volume ACP or it may be a
function of path component format (i.e. container files). The format of the "pseudo" path is given
below.

device:{[directory_spec{.@container_file}]}
where device is a physical device name, directory_spec is a VMS hierarchial directory spec
(of the form [directory{ .directory}]) and @container_file is the name of a foreign file
system container file.

NOTE
Foreign container files are currently limited to support of MSDOS FAT file system.
However it is concievable that additional foreign file system container files nay be
added. If this is the case additional work will be required to identify them without
resorting to opening the file and scanning the format.
The FSLIB is also given the client path and client namespace identifier. This information may be used
to select a variant file system within an FSLIB.

7 .4 .2 .2 FSLIB Initialization
Each FSLIB is called at its initialization entry point during PFS initialization. The library should set
up all data structures required to handle subsequent function requests. This routine will be called only
once at system startup time.
The FSLIB is required to initialize a PFS_LIB_ENT structure at this time. The structure contains the
name of the FSLIB, its characteristics and its function dispatch vectors.
PFS will locate the initialization routine by UNIVERSAL SYMBOL name. This routine must be
globally defined in the library and MUST be of the form :XXX_init, where XXX is the name of the
FSLIB. This is the ONLY symbol in the FSLIB which is referenced by name. All other functions will
be referenced by entries in the function dispatch vector.
The initialization routine will be called multiple times allowing the library to establish variant
function dispatch vectors.This feature allows libraries to implement separate functions for handling
April 20, 1992

Digital Confidential

PATHWORKS File System

various client anomolies if necessary. A library is not required to handle various clients in any
particular fashion and variants are strictly optional.

7. 4. 3

Data cache interface

PFS vectors all file read and write requests thru the data cache with the exception of atomic file copy
operations. The data cache is given a set of read and write file functions which it will use to fill the
cache and perform writebacks.
The file read and write functions are established when the path in which the file resides is claimed.
These functions are given to the data cache manager when the file is opened. It is important'to note that
file structure will affect the read and write functions and this information must be known when the path
is claimed.
The interface to the cache is strictly read by reference. A list of data buffer descriptors is passed between
data cache requests as well as being passed to file read and write functions. PFS will make these
descriptors lists available to servers then PFS_readdesc and PFS_writedesc functions.

PFS_open()
FSLIB_read()

PFS_read()

Data Cache

FSLIB_write()
PFS_write()

Figure 2. Data cache top level and FSLIB interface

7. 4. 5

Open file cache

PFS maintains a cache of most recently opened files. The primary purpose of this cache is to keep
information which will allow an MSDOS batch file ot be quickly reopenned. The overall effectiveness
of this cache is questionable as the server must translate the filename prior to finding it in the cache.
This operation represents the vast majority of time spent in opening a file. However, file close is
eliminated and this does represent a substantial savings.
While the primary purpose is specific the cache has application in other areas. The cache may be used
to permanently open a file effectively "installing" it. Sharing options and file locking will affect the
overall effectiveness of this application.
PFS will periodically close files in the open file cache as specified in a configuration parameter. This
will simply represent a "delayed" close of the file. Files may have different close intervals. PFS will
provide a function to set the close interval on an open file. This mechanism may be used by system
management software to open and specify an infinite close interval, thereby "installing" an image.
April 20, 1992
Digital Confidential
24

PATIIWORKS File System

NOTE
The assignment of tags to use in the location of entries is an open issue. PFS must
be able to generate a global unique identifier for the file without actually opening it.
As stated above, this represents the vast majority of work required to open a file and
may potentially result in accessing a file on one channel merely to close it and use
the already open channel.
Client filenames may not be used as a global tag without resolution of relative file
paths. This is particularly true in the Macintosh namespace. This operation may
result in accessing the file to resolve namespace translations.
It is clear more work needs to be done in the architecture of this cache with respect to
the structure of PFS.

7. 5

Data structures

PFS defines a number of data structures which are used to pass information between PFS and servers.
These structures maintain "cached" information to eliminate redundant file system functions. This
mechanism needs careful review when applied to a distributed file system. Certainly the possibility
exists that this information could change without the accessor's knowledge resulting in use of stale
data. In many cases this does not present a significant problem as there is sufficient ambiguity in the
order of operations in a distributed file system. There is no interlock mechanism for modification of file
meta data. To eliminate possible read-modify-write scenarios all data structres which hold modified data
also hold a mask indicating which data is modified. This mask may be used by file system libraries to
limit writeback modifications.

7.5.1

PFS_PATHID

The PFS_PATHID structure is used to hold mapped path information. This structure is returned by
PFS_getpathid() and is used as a file specification for all PPS access functions. Servers must obtain a
PFS_PATHID structure for a given path prior to any file service functions which are expected to deal
with this path.
The structure has the following fields:
funcptrs

Pointer to the file system library dispatch vector in the PFS_LIB_ENT
structure for the file system. This pointer is used to locate all file
system functions.

fullpath

Resolved native file specification. This buffer holds the name of the
host file or path which maps to the specified client path.

shortpath

Pointer to the start of the fullpath which needs further resolution. This
filed is not currently used or suported by PFS. This field is used to
optimize Unix access functions.

endtreetop

Pointer to the start of the fullpath which maps to client path, i.e. the
point beyond the share directory or volume directory. PFS does not use
this field. It is present for server use only. It is not suggested that new
server software use this field.

fsflags

Pointer to file system characteristic flags in the PFS_LIB_ENT
structure. This pointer is used by PFS to determine if a file system
supports various features.

April 20, 1992

•

Digital Confidential

PATIIWORKS File System

status

PFS_STAT structure holding file characteristics, location information
and various other file system specific information. The information in
this structure is known to and used by PPS. It is maintained by the file
system library.

diridptr

Pointer to next directory ID to be assigned on directory creates. This
field is not used by PFS and is not supported. This field represents a
shared partitioning of assignment of directory IDs between the file
system and the server. This partiton does not exist between PFS and
associated servers.

client_name

This is a holding buffer for file system library mapping functions. This
buffer is used to pass information between PFS and file system
libraries.

names pace

Identifies the namepsace in which this path is operating.

Claim parameter. FSLIB_claim functions are allowed to return a
longword parameter. This parameter is stored here and is made
accessible to file system library functions thru this offset. No
assumptions are made about the contents of this longword.

7 .5.2

PFS_FID

The PFS_FID structure represents an open file. This structure is returned by PFS_open() and
PFS_create(). This file identifier is necessary for all data path operations in PFS and is used for some
of the file attributes functions as well. Any file opened by PFS will have an associated PFS_FID
structure.
The PFS_FID structure contains the following fields:
forw

Forward link pointer. This field is not currently used by PFS.

back

Back link pointer. This field is not currently used by PFS.

funcptrs

Pointer to file system library dispatch vector. This pointer may be a
pointer to the PFS_LIB_ENT vector or may be a specific vector based
on file format.

status

PFS_STAT structure containing information about the file.

Open file descriptor. This longword is reserved for use by file system
libraries. The contents of this longword are not interpretted by PPS.

fdinfo

Information about the open file descriptor. This longword is reserved for
use by file system libraries as they deem necessary. No assumptions are
made about its contents by PFS.

stream

Data stream identifier. May be PFS_PRIMARY or PFS_RESOURCE
representing the data or resource streams of a file.

offset

Current stream offset in file.

refcnt

Number of servers which are referencing this shared file.

nompx

Counter to inhibit multiplex closing of this file. This field is not used
by PFS.

April 20, 1992

Digital Confidential

PATIIWORKS File System

7 .5.3

oflag

Copy of open mode passed to PFS_open() or PFS_create(). This field is
used to support file multiplexing and as such is not used by PFS.

flags.mandlock
flags.dirty

File has manditory locking set.
File has been modified.

mapaddr

File memory map address. This feature is not supported by PFS.

maplen

Length of memory map. See above.

fsflags

Pointer to file system library flags in PFS_LIB_ENT structure for the
file system which claimed this file.

endtreetop

This field is not used by PFS.

namespace

Namespace in which this file was opened.

Claim parameter. This parameter is copied from the associated
PFS_PATHID structure and is made available to file system libraries
thru this offset.

fullpath

Copy of the PFS_PATHID fullpath buffer.

PFS_ATTR

The PFS_ATTR structure is used to store and retrieve file service attributes. The attributes structure
has a mask associated with it which specifies which fields are to be read and written. This "bit set"
model solves the problem of shared file access with "cached" data in the structure.
This structure has been modified to better support multiple file systems and platform independence.
Additional fields have been added to represent attributes associated with supported clients. Where
possible the structure has been modified in an upward compatible manner. Time field format changes
are inevitably not upward compatible.
The fields of the PFS _ATIR structure are described below:
mask

Bit mask indicating the validity of each field in the structure. This mask
specifies which fields are to be modified on a get operation and which
fields are to be written on a set function.

dirid

Directory ID associated with the parent directory of the file being
referenced. If no file is referenced (path only) this field is the same as
the fileid field). This field carries the 32 bit Macintosh directory ID.
This field may or may not have significance for other file services.

btime

Backup time in namespace format.

ctime

Create time in backup time format.

finder_info

32 bytes of information associated with the Macintosh Finder. This
filed has no meaning for non Macintosh clients.

attr_bits .archive

File has been archived.

attr_bits .hidden

File is not visible to directory list operations.

attr_bits .is system

File is a system file.

attr_bits.no_rename

File can not be renamed. See PFS_rename().

April 20, 1992

Digital Confidential

PATHWORKS File System

7 .5.4

attr_bits.no_delete

File can not be deleted. See PFS_deleteQ.

attr_bits.no_copy

File can be copied with atomic copy function. See PFS_copyfile().

attr_bits.read_only

File can not be written. See PFS_open().

attr_bits.mac_appl

File is a Macintosh application.

attr_bits.multi_user

File can be open by multiple readers. This bit only has significance if
the mac_appl bit is also set.

attr_bits.no_purge

File can not be purged. See PFS_purge().

attr_bits.exec_only

File can only be open for execute access. It is not clear how this bit can
be honoured but it is here just in case.

fileid

File ID. This field caries the 32 bit Macintosh file ID. It may or may
not be applicable to other file services.

mtime

File modification time in namespace format.

file_count

Number of files contained in a directory. This count may be the total
number of files or just the number of non directory files. The total
number of files in a directory will always be represented as file_count +
directory_count.

directory_count

Number of directories contained in a directory. File systems may report
this value as 0 and return all files in file_count. This field is defined to
support Macintosh security concerns.

PFS_STAT

This structure is a collection of Unix file attributes and has very little application to non Unix
systems. It is highly questionable whther this information should be exported to servers. However,
there is application within the file system. Location information may be saved such that additional file
access may be eliminated when multiple references are made to a file.
NOTE
This structure has been modified to support the VMS ODS-2 file system. This is
clearly a file system issue and should be defmed elsewhere. It is likely more
appropriate to keep this information in an opaque data structure managed by the file
system library. To do so would require a maximum size be established for the
structure such that PFS may continue to manage the allocation of the structres which
contain this structure. This issue may be addressed in future developments of PFS.
The fields of the PFS_STAT structure are as follows:
mask

Mask indicating the validity of members of this structure

stat

Contains a "struct stat" structure defming various low level file
attributes.

gen

File generation number. This field is maintained by the file system
library and may or may not be supported.

stream

Data stream associated with this file. This field may have significance
in file systems which implement serparate files for each data stream

April 20, 1992

Digital Confidential

PATHWORKS File System

supported. This field is maintained by the file system library and may
or may not be supported.
p_ino

Parent INODE. This is a Unix concept and is only supported by Unix
file system libraries.

p_gen

Parent generation number. This field is maintained by the file system
library and may or may not be supported.

count

Number of files contained in a directory. This field is intended for
export to server to support the Macintosh offspring count. This field is
more appropriate in the PFS_AT'fR strcture and has been defined there.
This filed may or may not be maintained in parallel with the
PFS_AT'fR field.

dir_cnt

Directory offspring. This field is more appropriate in the PFS_AT'fR
structure and has been moved there. This field may or may not be
maintained in parallel with the PFS_AT'fR field.

file_cnt

File count. See above disclaimer.

attr

PFS_ATIR structure.

did

ODS-2 directory ID. This field is maintained by the ODS2 file system
library. It is not intended for export.

fid

ODS-2 file ID. This field is maintained by the ODS2 file system
library. It is not intended for export.

elev

ODS-2 volume name. This field is maintained by the ODS2 file system
library. It is no intended for export.

As can be seen from the above descriptions, this structure is of little value outside PFS with the
exception of the PFS_ATIR structure. The structure should be redefined to attempt to merge members
which are relavent to a particular file system. This may be done in future developments of PFS.

7.5.5

PFS_NAMEID

The PFS_NAMEID structure is used by PFS_parse() to store information about components of a
pathname. The structure has fields defined for components of various namespaces. This structure only
deals with named paths and does not carry any translation information. It is used to provide common
server parse function support.
The fields of the PFS_NAMEID structure are as follows:

elev

Pointer to device name in path buffer. If no device is present or if the
namespace does not support device names the field will be NULL.

devlen

Length of the device string. The length includes the trailing device
delimiter.

dir

Pointer to start of directory component. This will generally be the start
of the path for namespaces which do not support devices. The pointer
includes the leading directory delimiter.

dirlen

Length of the dirctory string. The length includes the trailing directory
delimiter.

filename

Pointer to start of filename component.

April 20, 1992

Digital Confidential

PATHWORKS File System

7 .5.6

filenamelen

Length of the filename string.

ext

Pointer to start of extension component. The pointer includes the
leading extension deliminter.

extlen

Length of the extension string.

parent

Pointer to start of the path.

parentlen

Length of the parent string.

path

Buffer containing the full path string. This buffer is included in the
structure such that the structure may be passed without requiring
translation of pointers.

PFS_CWD

The PFS_CWD structure holds the data associated with the current working directory.
The fields of the PFS_CWD structure are as follows:

7.5.7

path

Buffer containing the full path string.

directoryID

Host directory ID (if needed).

funcptrs

Function pointers for file system in which default exists.

PFS_USER

The PFS_USER structure holds the host user identification, privileges and rights for the mapped host
user. This structure is used to represent the client for various security related functions.
The fields of the PFS_USER structure are as follows:

7.5.6

uid

Host user identification in uid_t format.

privs

Quadword privilege mask.

rightlen

Length of rights list

rights

Pointer to rights list. This list consists of a set of two longword pairs.
The first longword is the right identifier and the second is the rights
attributes.

PFS_LIB_ENT

The PFS_LIB_ENT structure holds the data associated with a file system library.
The fields of the PFS_LIB_ENT structure are as follows:
fstype

Pointer to the name of the library.

funcptrs

Pointer to library dispatch vectors.

pfsflags .unixfs

Indicates unix file system.

pfsflags .resource

File system support resource forks.

April 20, 1992

Digital Confidential

PATHWORKS File System

7.5.9

pfsflags.extattrs

File system support extended attributes.

pfsflags.cscreate

File system supports case sensitive file names.

pfsflags.mappedfs

File system is mapped to another file system.

pfsflags .security

File system supports security data.

pfsflags .statmask

PFS_STAT elements supported.

pfsflags.attrmask

PFS_ATIR elements supported.

PFS_IDENT

The PFS_IDENT structure holds the data associated with a print file. While this information is
presented in VMS format it is expected that this structure will be modified to suit other platforms.
The fields of the PFS_IDENT structure are as follows:
count

Length of device name. Limit of 15 bytes.

device

Device name string. This string is not counted and is limited to 15
bytes.

fid

6 byte file identification.

did

6 byte directory identification.

7. 5. 1 0 Stat structure
The stat structure is a Unix concept which is ported to various platforms for compatibility. The
members of the structure may not have the same format nor the same implied function. The
effectiveness of this structure outside of PFS is questionable.

NOTE
Currently the device name and file INODE are used to identify a file. The Unix device
identifier is 32 bits in length and assumed to uniquely identify a device. VMS has no
such concept. Currently the device member is defined as a 16 character array. This is
a good application for a nameservice.
The INODE is also 32 bits and uniquely identifies a file within the Unix file system.
Again VMS has no concept of a. homogenous file system and assigns 48 bit file IDs
relative to volumes. This means that to uniquely identify a file on VMS requires 176
bits. Is is not clear what the implications for other file systems may be.
The fields of the stat structure are as follows:
st_dev

Longword device identifier. This is currently defined as a pointer to a 16
byte structure. Is is not clear where that structure would be located.

st_ino

32 bit file identifier. This field is maintained by the file system library
and is NOT unique across devices.

st_mode

Unix file format. The only bit of particular significance is the S_IFDIR
bit which indicates the file is a directory. PFS uses this bit to determine
if a file is a directory and assumes all file systems will set it
accordingly. (It is not sufficient to use the PFS_ATIR directory bit as
not all file services maintain this attribute).

April 20, 1992

Digital Confidential

PATHWORKS File System

st_nlink

Unix. This field may be set by file system libraries but is otherwise
unused.

st_uid

File owner ID. This longword contains the host file owner. This field
has no significance outside of PFS. PFS does not use this field for
security checks but it may be used by file system libraries.

st_gid

File owner group ID. This field contains the host file owner group ID.
This field has no significance outside PFS. PFS does not use this field
for security checks but it may be used by file system libraries.

st_rdev

Unix. This field may be set by file system libraries but is otherwise
unused.

st_size

File size. This field holds the file size in bytes. It is important to note
that this is the native file size. This may include record format overhead
and is likely to be of no significance outsize of PFS.

st_atime

Access time in Unix time format. This is the host file system access
time. While there may be a relationship between this time and the
client access time this is not necessarily true.

st_mtime

Modification time in Unix format. This is the host file system
modification time. See above disclaimer.

st_ctime

Creation time in Unix format. This is the host file system creation
time. See above disclaimer.

st_fab_rfm

ODS-2 record format. This field is used by the ODS2 file system
library and has no significance outside the library.

st_fab_rat

ODS-2 record attributes. This field is used by the ODS2 file system
library and has no significance outside the library.

st_fab_fsz

ODS-2 fixed size. This field is the length of the fixed portion of a VFC
file foramt. This field is used by the ODS2 file system library and has
no significance outside the library.

st_fab_mrs

ODS-2 maximum record size. This field is the length of the largest
possible record in the file. This field is used by the ODS2 file system
library and has no significance outside the library.

As can be seen from the above descriptions, this structure is for internal use only. It is described here
only because it is contained within data structures which pass across the interface. (and because there is
a body of server code which references fields within the structure). No access to this structure can be
allowed outside PFS as the fields vary amoung file systems.

7. 5. 1 1 Di rent

structure

The dirent structure is used by PFS_getdents() and contains information about files contained in a
directory. This data structure is inteded for server consumption (with the exception noted below) and
should be defined as a native PFS data structure. This is likely for future PFS developements.
The data structure is always allocated in longword quantities within the PFS_getdents() buffer. The
record length member is used to calculate the offset to the next structure within the buffer.
The fields of the direct structure are as follows:
April 20, 1992

Digital Confidential

PATHWORKS File System

d_ino

Opaque quantity. This field contans file location informaton used by
PFS_dentpathid() to improve directory search performance.

d_reclen

Length of the entire record, rounded to the next longword.

d_namelen

Filename length. This field is the byte count of the filename.

d_name

Filename buffer. This field contains the actual filename.

April 20, 1992

Digital Confidential

PATIIWORKS File System

ROUTINE DESCRIPTIONS
The following section describes the routines available to servers. The server should include the file
PFS .H in each module which uses these functions.

8.1

PFS

interface

The top level PFS interface consists of a set of routines to perform file functions. Many of these
routines are merely jacket routines for the underlying file system. PFS determines the file system to
which a file belongs during PFS_getpathid(). All functions from this point on are dispatched thru the
file system library vector returned by the FSLIB_claim() function.
Routines added to support the PATHWORKS server partioning are denoted by(*). These routines
should be ported to all platform implementations even if they are not necessary. Where appropriate
porting suggestions are given.

PFS_access *
PFS_faccess *

8.1.1
8.1.2

Description:
PFS_access checks the specified path for the specified access. This is a host security check only. NOS
security must be checked separately. Note that PFS does not execute in the context of the host user. It
is threfore possible to open a file and then check the file permissions. For VMS this may yeild some
performance improvement for files to which the user has access. There will be a performance
degradation for files to which the user has no access. It may be worth optimizing the success path and
for such, PFS_faccess is provided.

NOTE
This is the only PFS function which verifies host access to a file. The server should
call this function when it needs to verify a specific access.
Alternately, each function which needs to perform a security check can be modified to
accept the PFS_USER structure.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_access (PFS_PATHID *pathid, PFS_USER *user, PFS_SECURITY_MODE
mode, int perms)
PFS_RETVAL PFS_faccess (PFS_FID *fp, PFS_USER *user, PFS_SECURITY_MODE mode,
int perms)

Arguments:
pathid

Resolved pathid for path to check. This arrument is returned from
PFS_getpathid().

Open file pointer. The argument is returned from PFS_open().

user

PFS_USER structure from PFS_getuser().

mode

Volume security mode. The following values are defined:

April 20, 1992

Digital Confidential

PATHWORKS File System

perms

PFS_NOS_SECURITY

Access functions will always
succeed. This mode ignores host
security. Security checks are limited
to server NOS security checks.

PFS_HOST_SECURITY

Host security will be checked,
regarless of file owner. This check
is in addition to server NOS
security checks.

PFS_CREATOR_SECURITY

Host security will be checked on
files not created on behalf of a NOS
client. This check is in addition to
the server NOS security check.

Unix style permission code. The following bits are defined:

000
001
002
004

File exists
Execute access
Write/Delete access
Read access

Translations taken from "Programming in V AX-11 C".

Return values:
PFS_SUCCESS - Access is allowed
PFS_FAILURE - No access or invalid path

8.1.3
8.1.4

PFS_chdir
PFS_fchdir

Description:
PFS_chdir sets the current working directory. Note that the process structure of PPS is such that all
threads executing in the process will see this default. It is threfore required that the server save and
restore this default on thread switch. It is furtehr required that all thread switching performed by PPS be
routed thru the server to allow these tasks to be completed.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_chdir (PFS_PATHID *pathid)
PFS_RETVAL PFS_fchdir (PFS_FID *fp)

Arguments:
pathid

Resolved pathid pointing to a directory.

Open file pointer for a directory. Only PFS_open() will return this
pointer.

Return values:
PFS_SUCCESS - Default set
PFS_FAILURE - Invalid pathid or fp
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_chmod
PFS_fchmod

8.1.5
8.1.6

Description:
PFS_chmod changes the file protection of a host file. Note that there is no access checking with
respect to the client for which this function is being executed. It is the responsibility of the server to
determine if the client has the requisite privileges to affect the change.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_chmod (PFS_PATHID *pathid, mode_t mode)
PFS_RETVAL PFS_fchmod (PFS_FID *fp, mode_t mode)

Arguments:
pathid

Resolved pathid returned from PFS__getpathid().

Open file pointer.

mode

New file protection. The following bits are defined:·
0400
0200
0100
0040
0020
0010
0004
0002
0001

Owner:Read
Owner : Write
Owner : Execute
Group :Read
Group : Write
Group : Execute
World:Read
World : Write
World : Execute

System is always given the same protection as Owner. Write privilege implies Delete. Translations
taken from "Programming in VAX-11 C".

Return values:
PFS_SUCCESS - Protetion changed
PFS_FAILURE-Invalid path

8.1. 7
8.1.8

PFS_chown
PFS_fchown

Description:
PFS_chown changes the host owner of a file. The NOS owner is not affected. It is expected that this
function be used in conjunction with PFS_setsecurity() to affect an owner change consistent with both
NOS and host file systems. Note that there is no access checking with respect to the client for which
this function is being executed. It is the responsibility of the server to determine if the client has the
requisite privileges to affect the change.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_chown (PFS_PATHID *pathid, uid_t uid, gid_t gid)
April 20, 1992

Digital Confidential

PA1HWORKS File System

PFS_RETVAL PFS_fchown (PFS_FID *fp, uid_t uid, gid_t gid)

Arguments:
pathid

Resolved pathid from PFS_getpathid()

Open file pointer

uid

User identification code

gid

Group identification code

Return values:
PFS_SUCCESS - Owner changed
PFS_FAil..URE - Invalid path

8. 1 . 9

PFS_close

Description:
PFS_close will close an open file. This function will flush any modified buffers, remove all locks
associated with the file and update the volume modification time, if required. This call should be made
when a file is actually to be closed (i.e. after open file cache expiration time).

NOTE
It is possible that the PFS_FID may be shared among threads of the same process. If
this is the case a reference count will be decremented and the actual file close will
only occur when the count reaches zero.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_close (PFS_FID *fp)

Arguments:
fp

Open file pointer

Return values:
PFS_SUCCESS - File closed
PFS_FAil..URE - Invalid file pointer

8. 1 • 1 0 PFS_closeandpurge

Description:
PFS_closeandpurge will close an open file and then purge it. This function should be used when a
temporary file is to be deleted.

Digital Confidential

PATHWORKS File System

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_closeandpurge (PFS_FID *fp)

Arguments:
fp

Open file pointer

Return values:
PFS_SUCCESS - File closed and deleted
PFS_FAILURE- Invalid file pointer

8.1 .11 PFS_copyfile
Description:
PFS _copyfile copies a file from one source to a destination. The source and destination may be in
different file system libraries. The function is subject to source file system attribute
PFS_ATTR.attr_bits.no_copy.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_copyfile (PFS_PATHID *source, PFS_PATHID *dest,
PFS_SUPORT_STREAMS dostream, PFS_COPY_ACTION action)

Arguments:
source

Resolved pathid structure for source file. The file must not have the
PFS_ATTR no_copy bit set.

dest

Resolved pathid structure for destination file. The file must not reside in
a read only file system.

dostream

Action to be taken if the destination file system does not support all
streams of the source file.

April 20, 1992

PFS_NONE_OK

Copy the supported streams only.
The remaining streams are lost.

PFS_MUST_RESOURCE

If the destination does not support
resource streams and the source file
has a resource stream then fail.

PFS_MUST_EXTATTRS

If the destination does not support
extended atrtributes and the source
file has extended attrbiutes then fail.

PFS_MUST_SECURITY

If the destination does not support
security data and the source has
security data then fail.

PFS_MUST_ALL

If the destination does not support
either resource streams nor extended

Digital Confidential

PATHWORKS File System

attributes streams and the source
file has either then fail.
action

Action to be taken if the destination file already exists.
PFS_TRUNCATE

Truncate all destination streams.

PFS_APPEND

Append PFS_PRIMARY data
stream. Truncate the resource
stream. Leave extended attributes
stream unchanged. The source
extended attributes are lost.

Return values:
PFS_SUCCESS - File copied
PFS_FAILURE - Invalid path, conflicting file systems or copy protect

8. 1 • 1 2 PFS_create
Description:
PFS_create creates a new file (PFS_PRIMARY stream only) or truncates an existing file. The file is
left open after the function executes.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_create (PFS_PATHID *pathid, mode_t mode, uid_t uid, gid_t gid,
PFS_CREATE_TYPE type, PFS_FID **fp)

Arguments:
pathid

Resolved pathid from PFS_getpathid()

mode

File protection. Set PFS_chmod() for a description.

uid

Host file owner user ID.

gid

Host file owner group ID.

type

Type of file to create. The field has one of the following values:
PFS_CREATEIT

If the file already esists then

truncate it.

PFS_MAKETMP

Create a temporary file. Pathid
points to the directory in which to
create .the file. The filename is
generated.

PFS_MAKNEW

If the file exists PFS_create() fails.

Pointer to return file pointer. The file pointer is allocated by
PFS_create() and must be returned on PFS_close().

Return values:
April 20, 1992

Digital Confidential

PATIIWORKS File System

PFS_SUCCESS - File created
PFS_FAILURE - Invalid path or file exists and PFS_MAKENEW specified

8. 1. 1 3 PFS_delete
Description:
PFS_detete deletes a file. If the PFS_ATTR bit no_purge is set the file is moved to a holding area.
[Where??]. Ifno_purge is not set then the file is actually deleted.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_delete (PFS_PATIIlD *pathid)

Arguments:
pathid

Resolved pathid structure from PFS_getpathid().

Return values:

8. 1 . 1 4 PFS_dentpathid *
Description:
PFS_dentpathid converts a directory "struct dirent" to a PFS_PATHID structure. This function is used
to improve performance of directory search functions. If a file system does not support this function or
if sufficient information is not in the struct dirent then the file system should return failure.
PFS_dentpathid() will then call PFS_getpathid() using the filename from the "struct dirent". It is
assumed that PFS_chdir() has been called to set the default directory to that being searched prior to this
call. While PFS_dentpathid() does not use the default directory, fallbacks to PFS_getpathid() will.

Synopsis:
#include <pfs .h>
#include <dirent.h>
PFS_RETVAL PFS_dentpathid (PFS_FID *fp, struct dirent *dirent, PFS_PATIIlD *pathid)

Arguments:
fp

Open file pointer to directory to be searched

dirent

Struct dirent from PFS_getdents().

pathid

Resulting PFS_PATIIlD structure for file.

Return values:
PFS_EXISTS - Path exists as specified.
PFS_NOEXIST- Path does not exist but the parent path does (i.e. a new file specification).
PFS_FAILED - Neither parent nor path exists.

8. 1 . 1 5 PFS_didpathid *
Description:
April 20, 1992

Digital Confidential

PATIIWORKS File System

PFS_didpathid will accept a default directory structure instead of the root string as in PFS_getpathid().
The remaining function is identical to PFS_getpathid().

Synopsis:
#include <pfs.h>
PFS_RETVAL PFS_didpathid (PFS_CWD *dirid, char *path, PFS_NAMESPACE namespace,
PFS_PATHID *pathid)

Arguments:
dirid

PFS_CWD structure as returned by PFS_diridfunc. The path member of
the structure is not used. The directoryID member is used as the root
directory.

path

NOS path name.

namespace

NOS path name space identifier. This argument specifies the namespace
in which the path resides.

pathid

Resolved pathid structure.

Return values:
PFS_EXISTS - Path exists as specified.
PFS_NOEXIST- Path does not exist but the parent path does (i.e. a new file specification).
PFS_FAILED- Neither parent nor path exists.

8.1.16 PFS_diridfunc
Description:
PFS _diridfunc supports translation of directory IDs. The function will open a set of IDs, close a set of
IDs or translate the IDs into native file system structures. The back translation to path string is
somewhat expensive on VMS and is not required for lookups. The interface has been changed to return
a structure of the same form as used by PFS_cwd(). This structure will only carry the full VMS
directory ID and may be used as input to the function PFS_didpathid().

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_diridfunc (PFS_DIRID_CMD cmd, char *root, unsigned long dirid, PFS_CWD
*dirptr)

Arguments:

cmd

April 20, 1992

Directory ID command. The command is one of the following:
PFS_DIRID_OPEN

Open a new set of directory IDs.
The root argument carries the
volume name to be opened.

PFS_DIRID_GET

Translate the given directory ID to a
PFS_CWD structure. The root
argumenet is not used.

Digital Confidential

.PATIIWORKS File System

PFS_DIRID_CLOSE

Close a set of directory IDs. The
root argument carries the name of
the volume to close.

root

Volume root directory. This field is used forPFS_DIRID_OPEN
functions only.

ctirid

Directory ID to translate

dirptr

Return directory ID structure. This structure may contain the path name
as a string or the native directory ID or both.

Return values:
PFS_SUCCESS - Directory ID translated
PFS_FAILURE- Invalid directory ID or no directory ID set open.

8.1.17 PFS_diridinit
Description:
PFS_diridinit initializes the generation of directory IDs for file systems which do not direcltly support
directory IDs.

Synopsis:
#include <pfs .h>
void PFS_diridinit (PFS_DIRIDS_MATTER dodorods, unsigned long *diridptr)

Arguments:
dodirids

diridptr

Flag to indicate whether to generate directory IDs. The flag has the
following values:
PFS_DIRIDS

Generate directory IDs for
PFS_mkdir(). PFS_getattr() will
return the generated ID.

PFS_NODIRIDS

Do not generate directory IDs. The
file system will handle the function
directly.

Pointer into shared memory for the next unique directory ID.

Return values:
None

8.1.18 PFS_filesize
8.1.19 PFS_ffilesize
Description:
PFS_ffilesize returns the size of an open file. The function may be required to read the file to determine
its size. If so, the filesize will be saved in the ACE associated with the file.

Synopsis:
April 20, 1992

Digital Confidential

PATHWORKS File System

#include <pfs .h>
PFS_RETVAL PFS_filesize (PFS_PATIIlD *pathid, PFS_DATA_STREAM stream, off_t *size)
PFS_RETVAL PFS_ffilesize (PFS_FID *fp, off_t *size)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

stream

Data stream to obtain size of.
Open file pointer

size

Pointer to return file size longword

Return values:
PFS_SUCCESS - Return size is valid
PFS_FAILURE- Invalid file pointer

8.1.20 PFS_fsync
Description:
PFS_fsync flushes all modified data associated with a file. This includes modified header data.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_fsync (PFS_FID *fp)

Arguments:
fp

Open file pointer

Return values:
PFS_SUCCESS - File flushed
PFS_FAil..URE - Invalid file pointer

8.1.21 PFS_fullpath
Description:
PFS_fullpath returns the full file specification for an open file.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_fullpath (PFS_FID *fp, char *pathbuf, int buflen)

Arguments:
fp

Open file pointer

pathbuf

Buffer for return file specification

April 20, 1992

Digital Confidential

PATIIWORKS File System

buflen

Length of return buffer

Return values:
PFS_SUCCESS - Path written to buffer
PFS_FAILURE- Invalid file pointer to buffer too small

8. 1 . 2 2 PFS_getattr
8.1.23 PFS_fgetattr

•

Description:

PFS _getattr will return the file attributes structure. The attributes structure is described in section 7 .5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getattr (PFS_PATIDD *pathid, unsigned long mask, PFS_ATIR *attrp)
PFS_RETVAL PFS_fgetattr (PFS_FID *fp, unsigned long mask, PFS_ATIR *attrp)

Arguments:
pathid

Resolved pathid structure from PFS_getpathid()

Open file pointer

mask

Mask of elements requested. There is one bit in the mask for each field
in the PFS_ATIR structure. This mask has the exact same format as
that in the PFS_ATIR structure.

attrp

Pointer to return attributes structure.

Return values:
PFS_SUCCESS - Attributes updated
PFS_FAILURE - Invalid parameters

8.1 .24 PFS_getcomment
Description:
PFS_getcomment will return the comment record associated with a file. The comment is limited to
199 bytes. The first byte of the comment buffer contains the length of the comment string. The string
is NULL terminated.

l Length
Comment data (maximum length 199 bytes)

NULL

Synopsis:
#include <pfs .h>
April 20, 1992

Digital Confidential

PATIIWORKS File System

PFS_RETVAL PFS_getcomment (PFS_PATIDD *pathid, char *comment, int buflen)

Arguments:
pathid

Resolved pathid from PFS_getpathid().

comment

Return buffer for comment.

buflen

Length of return buffer.

Retur& values:
PFS_SUCCESS - Coment returned
PFS_FAILURE - Invalid parameters

8. 1 . 2 5 PFS_getcwd
Description:
PFS_getcwd returns the current working directory.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getcwd (PFS_CWD *cwd)

Arguments:
c,wd

Pointer to working directory structure

Return values:
PFS_SUCCESS - Directory returned
PFS_FAILURE - No directory set

8. 1.26 PFS_getdents
Description:
PFS_getdents returns directory entries in a struct dirent buffer. The buffer is written with as many full
directory entries as will fit (or as many as are in the directory). The struct dirent is defined in section

7.5.
The function should be called until the bytesread paramater indicates zero bytes written to the output
buffer. The function will not fail when the end of the directory is reached.

Synopsis:
#include <pfs .h>
#include <dirent.h>
PFS_RETVAL PFS_getdents (PFS_FID *fp, struct dirent *direntp, unsigned int nbytes, off_t *offset,
PFS_NAMESPACE namespace, unsigned int bytesread)

Arguments:
fp

April 20, 1992

Open file pointer for the directory to be enumerated.
Digital Confidential

PATHWORKS File System

direntp

Buffer to receive directory entries.

nbytes

Size of the buffer.

offset

Pointer to receive context longword for resuming directory enumeration.
This longword must not be modifed bewteen calls to PFS_getdents.

namespace

Namespace in which to return directory entries.

bytesread

Return count of how many bytes were written to the output buffer.

Return values:
PFS_SUCCESS - Buffer written (including no entries)
PFS_FALURE - Invalid parameters

8.1.27 PFS_getextattr
8.1 .28 PFS_fgetextattr
Description:
PFS_getextattr will return the extended attributes associated with a file. The interface uses a number of
structures to carry requested attributes and return attributes found on the file.
The arrangement of structures is shown below:
PFS - EAOPS
gealistp

........

fealistp

len

namelen
name

cnt
list

erro:ffset

PFS_GEA[]

PFS - GEALIST

1--

PFS_FEA[]
PFS_FEALIST

len

flag
namelen

totlen

vallen

cnt

name

totcnt
list

._.....

value
maxien

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getextattr (PFS_PATIIlD *pathid, PFS_EAOPS *eaopsp)
PFS_RETVAL PFS_fgetextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
pathid

Resolved pathid from PFS_getpathid().

Open file pointer

April 20, 1992

Digital Confidential

PATHWORKS File System

eaopsp

Pointer to return extended attributes structure. [This structure is not yet
defined as there is still question as to whether we support extended
attributes].

Return values:
PFS_SUCCESS - Extended attributes written to buffer
PFS_FAILURE - Invalid parameters

8. 1 . 2 9 PFS_getpathid
Description:
PFS_getpathid resolves a NOS file path given the top of the directory tree, the NOS path and NOS
type. PFS_getpathid locates the file system which handles this path and sets the file system library
dispatch vectors for future reference.
PFS_getpathid calls the following library functions:
FSLIB_claim

File system is asked to claim the path. If a file system claims a path
then it will be responsible for all future requests for that path.

FSLIB_convert

Convert filename to native file specification

FSLIB_lookup

Locate the file

FSLIB_stat

Return file location, type, size, etc.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getpathid (char *root, char *path, PFS_NAMESPACE namespace,
PFS_PATHID *pathid)

Arguments:
root

Top of directory tree or directory which corresponds to the volume root.

path

NOS file path.

namespace

Namespace in which path resides. The following values are defined:
PFS_DOSNAME
PFS_MACNAME
PFS_VMSNAME
PFS_UNIXNAME
PFS_NATIVENAME

pathid

DOS filename format
Macintosh filename format
VMS filename format
Unix name format
Native file system format

Return resolved pathid structure

Return values:
PFS_EXISTS - Path exists as specified.
PFS_NOEXIST- Path does not exist but the parent path does (i.e. a new file specification).
PFS_FAILED - Neither parent nor path exists.

8. 1 . 3 0 PFS_getprintident *
April 20, 1992

Digital Confidential

PATIIWORKS File System

Description:
PFS_getprintident returns file identification information in the PFS_IDENT structure. This structure is
used primarity by the print subsystem to identify a file.
The PFS_IDENT structure is defmed in section 7 .5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getprintident (PFS_PATHID *pathid, PFS_IDENT *identp)

Arguments:
patbid

Resolved pathid structure as returned by PFS_getpathid().

identp

Pointer to return identification structure.

Returns:
PFS_SUCCESS - Print identification returned
PFS_FAILURE - Insufficient information

8. 1 .31 PFS_getsecurity *
8.1.32 PFS_fgetsecurity *
Description:
PFS_getsecurity returns stored NOS security data for a given object. The function does not interpret the
data.
Lan Manager security data is stored as a set of named objects. The name may be any string and the data
is variable length. PFS_getsecurity will retrieve named objects if requested. The semantics are identical
to those for PFS_getextattr(). Lan Manager security data is accessed by specifying PFS_LMXSECURE
as the securspace argument.
Macintosh security data is stored in the Macintosh ACE. The format of the Macintosh security data
returned is identical to that stored in the Macintosh ACE. Macintosh security data is accessed by
specifying PFS_MACSECURE as the securspace argument.
As with PFS_getextattr(), it is the responsibility of the caller to deallocate the PFS_FEALIST
structure.
Note that the PFS_GEA structure is used to request named security data. This structure is initialized by
the caller. The PFS_FEA structure holds one record per requested named security data, even if the data
does not exist. The vallen field will be set to zero in the event that the data does not exist. In this
manner there is a one-to-one correspondence between input array offsets and output array offsets. The
caller must release the PFS_EAOPS pointer fealistp. All pointers within the PFS_FEA and
PFS_FEALIST are contained in this buffer.

NOTE
PFS does not understand the hierarchy of security data. PFS will store and retrieve
security data as it applies to file objects only. It is the server's responsibility to
locate security information stored elsewhere in the path which may apply to the
current request. This partition may cause additional path processing and file access to
locate inherited security data. The server will make repeated calls to PFS to obtain
April 20, 1992

Digital Confidential

PATHWORKS File System

pathid structures and security data for each member of the path for which access
information is not stored.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getsecurity (PFS_PATHID *pathid, PFS_SECURSPACE securspace,
void *securp)
·
PFS_RETVAL PFS_fgetsecurity (PFS_FID *fp, PFS_SECURSPACE securspace, void *securp)

Arguments:
pathid

Resolved pathid structure returned by PFS_getpathidO.

Open file pointer

securspace

Security data space to be modified. The following values are defined:

securp

PFS_LMXSECURE

Lan Manager security space .

. PFS_MACSECURE

Macintosh security space.

Pointer to security data access structure. For PFS_LMXSECURE the
structure is identical to the extended attributes structure. For
PFS_MACSECURE the data starts at offset "ownerlD" and is returned
exactly as specified in the Macintosh ACE. The data is 11 bytes in
length.

Return values:
PFS_SUCCESS - Returned attributes
PFS_FAILURE - Invalid parameters

8. 1 • 3 3 PFS_getuser

Description:
PFS_getuser returns information about the specified host user in a PFS_USER structure. This
structure is used for access checking functions PFS_acess() and PFS_faccess().
The function reads information from the system User Authorization File (UAF) and returns the user
identification, rights and privileges.
It is the callers responsibility to release the memory associated with the structure. The rights list must
be released as well as the structure itself.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getuser (char *username, PFS_USER **user)

Arguments:
username

Host username for which information is desired

user

Return user structure defining user rights and privileges.

April 20, 1992

Digital Confidential

PATHWORKS File System

Return values:
PFS_SUCCESS - Obtained user info
PFS_FAILURE - No such user

8.1.34 PFS_init
Description:
PFS_init initializes the file system interface, loads and calls all file system libraries. Addon libraries
are located in the directory pointed to by PWRK$ADDON_LlBRARY: and must named
PWRK$name_FSLIB.EXE, where name is the file system name. The file system library must have a
universal symbol of the form name_init. For example, the FAT file system would be found as
PWRK$FAT_FSLlB.EXE and would have a universal symbol FAT_init. The universal symbol is the
entry point to the library and is responsible for initializing the PFS_LIB_ENT structure, including
setting up the library vectors.
PFS_init must be called prior to any PFS file access.

Synopsis:
#include <pfs .h>
void PFS_init (void)

Arguments:
None

Return values:
None

8.1.35 PFS_lock
Description:
PFS_lock establishes a byte range lock on the file in the underlying file system. This function is
provided for establishing byte range locks in the file system itself. Btye range locks are handled withing
PATHWORKS by the PATHWORKS Lock Manager and may not involve the file system.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_lock (PFS_FID *fp, short type, off_t offset, short whence, off_t length,
PFS_W AIT_LOCK dowait, off_t *start)

Arguments:
fp

Open file pointer

type

Type of lock to set. The following values are defmed:
F_RDLCK
F_WRLCK

offset
April 20, 1992

Read lock (shared).
Write lock (exclusive).

Position to start lock.
Digital Confidential

PATIIWORKS File System

whence

Position from which to measure offset. The following values are

defined:
SEEK_SET

Offset is relative to the start of the
file. The offset should be a positive
number.

SEEK_END

Offset is relative to the end of the
file. The offset should be a negative
number.

length

Length of range locked. If zero is specified as a length the remainder of
the file is locked from the position defined by offset and whence.

dowait

The following values are defined:

start

PFS_WAIT

Wait for release of existing lock
prior to resuming execution.

PFS_NOWAIT

If any portion of the range is
locked, PFS_lock fails.

Return position relative to the start of the file where the locked range
starts. The pointer may be NULL in which case it is ignored.

Return values:
PFS_SUCCESS - Lock set
PFS_FAILURE-Invalid parameters or lock conflict

8.1.36 PFS_lseek
Description:
PFS_lseek positions the current file pointer to the position specified.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_lseek (PFS_FID *fp, off_t offset, int whence)

Arguments:
fp

Open file pointer

offset

Position to set file pointer to, relative to whence argument.

whence

Position from which to measure offset. The following values are

defined:
SEEK_SET

Offset is measured from the start of
the file.

SEEK_END

Offset is measured from the end of
the file.

Return values:
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_SUCCESS - File position changed
PFS_FAILURE- Invalid parameters

8.1.3 7 PFS_mapname
8.1.38 PFS_fmapname
Description:
PFS_mapname will translate the last member of a given path to the namespace specified. Note that
this function may require file system 1/0 to complete the translation. This function should not be used
to pretranslate filenames prior to access. PFS_getpathid() provides this translation.
It is not clear wht this function is intended for but it should be avoided in performance critical
applications.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_mapname (PFS_PATHID *pathid, PFS_NAMESPACE namespace,
char *namebuf, int buflen)
PFS_RETVAL PFS_fmapname (PFS_FID *fp, PFS_NAMESPACE namespace, char *namebuf, int
buflen)

Arguments:
path.id

Resolved pathid structure from PFS_getpathid()

Open file pointer

names pace

Namespace in which translated name is to be returned

namebuf

Buffer in which to return name

buflen

Length of return buffer

Return values:
PFS_SUCCESS - Name translated
PFS_FAILURE - Invalid parameters or buffer too small

8.1.39 PFS_mkdir
Description:
PFS_mkdir creates a directory. The host owner is set to that specified as welll as the access
permissions.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_mkdir (PFS_PATHID *pathid, mode_t mode, uid_t uid, gid_t gid,
unsigned long *dirid)

Arguments:
April 20, 1992

Digital Confidential

PATHWORKS File System

pa1hid

Resolved pathid for the directory to be created.

mode

Access permissions to be applied to the directory. See PFS_chmod() for
a description of this parameter.

uid

Host user identification for the directory owner.

gid

Host group identification for the directory owner.

dirid

Value is incremented and used as the directory ID unless NULL. If
NULL the file system will generate its own internal IDs.

Return values:
PFS_SUCCESS - Directory created
PFS_FAILURE - Invalid parameters

8. 1 .40 PFS_mpxclose
Description:
PFS_mpxclose closes the file system file. The PFS file pointers are maintained as if the file was still
open. This function allows freeing file descriptors for reuse. If a file which has been multiplex closed is
referenced it will be reopened.
[File multiplexing needs to be reviewed.]

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_mpxclose (PFS_FID *fp)

Arguments:
fp

Open file pointer

Return values:
PFS_SUCCESS - File is close in the underlying file system
PFS_FAILURE - Invalid parameters

8.1.41 PFS_needfds
Description:
PFS_needfds will multiplex close open files such that the requested number of file descriptors are
available for use.
[File multiplexing needs to be reviewed]

Synopsis:
#include <pfs .h>
void PFS_needfds (int count)

Arguments:
April 20, 1992

Digital Confidential

PATHWORKS File System .

count

Required number of file descriptors

Return values:
None

8.1 .42 PFS_needinodes
Description:
PFS_needinodes will multiplex close a number of files to attempt to free inodes in the Unix file
system. This call has no effect on VMS systems.

Synopsis:
#include <pfs .h>
void PFS_needinodes (int timescalled, PFS_OPS *funcptrs)

Arguments:
times called

Number of times the function has been called attempting to get inodes
released. The function will increase the number of files closed on each
successive call which increments this counter.

funcptrs

File system function pointers [which file system ??]

Return values:
None

8. 1 .43 PFS_open
Description:
PFS_open will open a file stream. The function has the ability memory map the file under Unix. For
VMS this option is ignored.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_open (PFS_PATHID *pathid, PFS_STAT *statbufp, int oflag,
PFS_DATA_STREAM stream, PFS_MEM_MAP dommap,
PFS_FID **fp)

Arguments:
pathid

Resolved pathid as returned by PFS_getpathid()

statbufp

Status buffer pointer. If the server has the status buffer for a non
primary stream and wishes to open the stream it can save a PFS_stat()
call by specifying the buffer.

oflag

Open mode flags. The following bits are defined:
00000 O_RDONLY
00001 O_WRONLY
00002· O_RDWR

April 20, 1992

Open the file for read access only.
Open the file for write access only.
Open file for both read and write access.

Digital Confidential

PATIIWORKS File System

00010
01000
02000

O_APPEND
O_CREAT
O_TRUNC

Open file for append access.
Create stream if it does not exist
Truncate stream if it exists

stream

Specifies the stream to open (or create). Note that the primary stream
must already exist.

dommap

Memory map the file. This option has significance under Unix only.

Return open file pointer.

Return values:
PFS_SUCCESS - File open
PFS_FAILURE - Invalid parameters

8. 1.44 PFS_parse *
Description:
PFS_parse returns a structure defining the components of a file path in a specified namespace. This
function is intended to remove file system name space manipulation assumptions from the server. The
server should use this function to process components of a path specification. The PFS_NAMEID
structure is defined in section 7 .5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_parse (char *path, PFS_NAMESPACE namespace, PFS_NAMEID *nameid)

Arguments:
path

File specification

namespace

Namespace in which path exists

nameid

Return structure defining the components of the path.

Return values:

8.1.45 PFS_purge
Description:
PFS_purge deletes a file. The PFS_ATTR no_purge attribute is ignored and the file is deleted.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_purge (PFS_PATHID *pathid)

Arguments:
pathid
April 20, 1992

Resolved pathid as returned by PFS_getpathid().
Digital Confidential

PATHWORKS File System

Return values:
PFS_SUCCESS - File deleted
PFS_FAILURE - Invalid parameters

8. 1 .46 PFS_read
Description:
PFS_read will read data from an open file stream.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_read (PFS_FID *fp, void *buffer, unsigned int nbytes, off_t offset,
unsigned int *bytesread)

Arguments:
fp

Open file pointer

buffer

Buffer for return data

nbytes

Size of return buffer

offset

Position relative to start of the stream from which to read data.

bytesread

Return count of bytes actually read from the stream.

Return values:
PFS_SUCCESS - Bytes read (including none)
PFS_FAILURE - Invalid parameters

8. 1 . 4 7 PFS_readdesc

Description:
PFS_readesc will read data from an open stream and return a set of mapping pointers describing the
data. The data itself remains in the data cache.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_readdesc (PFS_FID *fp, unsigned int nbytes, off_t offset, PFS_DESC **desc)

Arguments:
fp

Open file pointer.

nbytes

Number of bytes to read.

offset

Offset releative to the start of the stream from which to read.

desc

Pointer to receive data description. [Need specification of work element
for data cache].

April 20, 1992

Digital Confidential

PATIIWORKS File System

Return values:
PFS_SUCCESS - Data read
PFS_FAILURE - Invalid parameters

8. 1 •4 8 PFS_releasedesc

Description:
PFS _releasedesc will release the data associated with the descriptors previously returned by
PFS_readdescQ.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_releasedesc (PFS_DESC *desc)

Arguments:
Descriptor pointer returned by PFS_readdescQ.

Return values:
PFS_SUCCESS - Data released
PFS_FAILURE - Invalid parameter

8. 1 .49 PFS_rename
Description:
PFS_rename will rename a file or directory. The files MUST both exist in the same file system. The
function accepts two pathid structures describing the files to be renamed. These structures will have
previously resolved namespace considerations. However, BOTH files must exist in the same
namespace.
There are cross namespace implications in renaming a file. The VMS, DOS and Macintosh names are
all releated and therefore a change to one will result in a change to all. The mapping is as follows:
VMS
If changed
DOS name
Short name

DOS
VMS name
If changed
Short name

Macintosh
VMS name
DOS name
If changed

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_rename (PFS_PATHID *oldpathid, PFS_PATIIID *newpathid)

Arguments:
oldpathid

Resolved pathid structure for origninal file name.

newpathid

Resolved pathid structure for new file name.

Return values:
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_SUCCESS - File renamed
PFS_FAILURE - Invalid parameters, conflicting file systems or conflicting namespace

8.1.50 PFS_rmdir
Description:
PFS_rmdir will delete a directory. The directory must be empty.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_rmdir (PFS_PATHID *pathid)

Arguments:
pathid

Resolved pathid structure as returned by PFS__getpathid().

Return values:
PFS_SUCCESS - Directory deleted
PFS_FAILURE- Invalid parameter, directory not empty

8.1.51 PFS_setattr
8.1.52 PFS_fsetattr
Description:
PFS_setattr sets NOS file atributes. Each member of the PFS_ATIR structure has a corresponding
mask bit. Only the attributes indicated by the mask are affected. In this manner, conncurrent update
may be handled without additional synchronization. Simultaneous updates to the same fields without
external synchronization will not yeild predictable results as the order of individual field updates can not
be guaranteed. However, simultaneous updates to different fields will yeild the expected results.
A file must be writeable in order to modify the attributes. If a file is open when the attributes are
modified it must be open for write access.
Note that the mask of elements to modify is contained in the attributes structure, not specified
separately as in PFS__getattr().
The PFS_ATIR structure is defined in section 7.5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_setattr (PFS_PATHID *pathid, PFS_A'ITR *attrp)
PFS_RETVAL PFS_fsetattr (PFS_FID *fp, PFS_ATIR *attrp)

Arguments:
pathid

Resolved pathid structure as returned by PFS__getpathid()

Open file pointer. File must be open for write access.

attrp

Pointer to PFS_ATTR structure containing attributes to modify

April 20, 1992

Digital Confidential

PATIIWORKS File System

Return values:
PFS_SUCCESS - Attributes modified
PFS_FAILURE - Invalid paramters or file not writeable

8. 1 . 5 3 PFS_setcomment
Description:
PFS_setcomment will associate a text string with a file. The comment format is as defined for
PFS_getcomment().
If a comment is already associated with the file it is replaced.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_setcomment (PFS_PATHID *pathid, char *comment)

Arguments:
pathid

Resolved pathid as returned by PFS_getpathid()

comment

Comment block as defined in PFS_getcomment().

Return values:
PFS_SUCCESS - Comment written
PFS_FAILURE- Invalid paramters or file not writeable

8. 1 . 5 4 PFS_setextattr
8. 1 . 5 5 PFS_ fsetextattr
Description:
PFS_setextattr sets the extended attributes of a file. The extended attrributes are described in
PFS_getaextattr(). The PFS_GEALIST member is ignored on set operations.
The PFS_FEALIST points to an array of extended atrributes blocks, PFS_FEA. Each array member
describes one attribute to add, delete or modify.
If the attributes does not exist it is added. If the attribute already exists it is replaced. If the value length
field of the attribute is zero, the attribute is deleted.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_setextattr (PFS_PATIIID *pathid, PFS_EAOPS *eaopsp)
PFS_RETVAL PFS_setextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid()

Open file pointer.

April 20, 1992

Digital Confidential

PATHWORKS File System

eaopsp

Pointer to extended attributes structure. The gealist member of the
structure is ignored. The structure is defmed in PFS_getextattr().

Return values:
PFS_SCCESS -Attributes modified
PFS_FAILURE - Invalid parameters or file not writeable

8.1.56 PFS_setlognores
Description:
PFS_setlognores accepts a function pointer to be called when resources are exhausted.

Synopsis:
#include <pfs .h>
void PFS_setlognores (void (*func) ())

Arguments:
func

Address of routine entry mask. This routine will be called when PFS
exhausts resources. Memory, disk space, IO channels, etc will be
reported. Note that no arguments are passed to the called function.

Return values:
None

8.1.57 PFS_setnotifympx
Description:
PFS_setnotifympx accpets a function pointer to be called when file multiplexing occurs.

Synopsis:
#include <pfs .h>
void PFS_setnotifympx (void (*func) 0)

Arguments:
func

Address of routine entry mask. This routine will be called when PFS
multiplex closes a file. Note that no arguments are passed to the called
function.

Return values:
None

8. 1 . 5 8 PFS_setsecurity *
8.1.59 PFS_fsetsecurity *
Description:
PFS_setsecurity associates NOS security data with a file object. The security data is not interpretted.
April 20, 1992

Digital Confidential

PATIIWORKS File System

For PFS_LMXSECURE the interface is identical to that of PFS_setextattr().
For PFS_MACSECURE the interface accepts a pointer to the "ownerlD" member of the Macintosh
ACE and writes 11 bytes of data to the file's Macintosh ACE.

If PFS_setsecurity() returns PFS_NOTSUPPORTED the server must be prepared to find alternate
storage means for the security data. Not all underlying file systems support association of security data
with files.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_setsecurity (PFS_PATHID *pathid, PFS_SECURSPACE securspace,
void *securp)
PFS_RETVAL PFS_fsetsecurity (PFS_FID *fp, PFS_SECURSPACE securspace, void *securp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid()

Open file pointer

securspace

Security data space to be modified. The following values are defined:

securp

PFS_LMXSECURE

Lan Manager security space.

PFS_MACSECURE

Macintosh security space.

For PFS_LMXSECURE, a pointer to extended attributes structure
containing named security data. The semantics are identical to those of
PFS_setextattr(). For PFS_MACSECURE a pointer to the "ownerlD"
member of the Macintosh ACE.

Return values:
PFS_SUCCESS - Data associated
PFS_FAILURE- Invalid parameters or file not writeable
PFS_NOTSUPPORTED - Security data not supported

8. 1 .60 PFS_shortpath
Description:
PFS_shortpath sets the shortpath member of the pathid structure relative to the current working
directory, if working directories are supported. Not all file systems support this and for those which
dont, this function is a NOP.

Synopsis:
#include <pfs .h>
void PFS_shortpath (PFS_PATHID *pathid)

Arguments:
pathid
April 20, 1992

Resolved pathid structure as returned by PFS_getpathid()
Digital Confidential

PATHWORKS File System

Return values:
None

8.1 .61 PFS_stat
8.1 .62 PFS_fstat
Description:
PFS_stat will obtain file location information and file structure information for the file containing the
given stream. The data structures returned are indended to be opaque. This call is provided for potential
performance optimizations in the server. It is expected that the return PFS_STAT structure is to be
given back to PFS at some later time, potentially saving multiple stat calls in PFS.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_stat (PFS_PATIUD *pathid, PFS_DATA_STREAM stream,
unsigned long mask, PFS_STAT *statbufp)
PFS_RETVAL PFS_fstat (PFS_FID *fp, unsigned long mask, PFS_STAT *statbufp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

Open file pointer

stream

File stream for which information is to be returned.

mask

Mask of elements to be returned.

statbufp

Pointer to return PFS_STAT structure.

Return values:
PFS_SUCCESS - Information obtained
PFS_FAILURE - Invalid parameters

8. 1 . 6 3 PFS_statvfs
8.1 .64 PFS_fstatvfs
Description:
PFS_statvfs provides information about a mounted file system under Unix only. This call is a NOP on
VMS systems.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_statvfs (PFS_PATHID *pathid, statvfs_t *fsbufp)
PFS_RETVAL PFS_fstatvfs (PFS_FID *fp, statvfs_t *fsbufp)

Arguments:
April 20, 1992

Digital Confidential

PATHWORKS File System

pathid

Resolved pathid as returned by PFS_getpathid()

Open file pointer

fsbufp

Return file system information block. This structure is defined for Unix
systems only.

Return values:
PFS_SUCCESS - Information obtained
PFS_FAILURE - Invalid parameters

8.1.65 PFS_sync
Description:
PFS_sync will flush all modified data. All file headers are written out to disk as well as all file data.

Synopsis:
#include <pfs .h>
void PFS_sync (void)

Arguments:
None

Return values:
None

8.1.66 PFS_treetop
Description:
PFS_treetop sets the treetop member of the pathid structure to that specified. This field is not used by
PFS and is provided for server use.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_treetop (PFS_PATHID *pathid, char *treetop)

Arguments:
pathid

Resolved pathid structure as returned by PFS__getpathid()

treetop

Pointer to be copied to treetop member of pathid structure. PPS makes
no assumptions about the contents of this pointer.

Return values:
PFS_SUCCESS - Treetop written
PFS_FAILURE - Invalid parameters

8.1.67 PFS_ftruncate
April 20, 1992

Digital Confidential

PATHWORKS File System

Description:
PFS_truncate will truncate a file at a given offset. This call yeilds the same result as PFS_write() with
a zero buffer length.

Synopsis:
#include <pfs.b>
PFS_RETVAL PFS_ftruncate (PFS_FID *fp, off_t size)

Arguments:
fp

Open file pointer

size

Position at which to truncate the file.

Return values:
PFS_SUCCESS - File truncated
PFS_FAILURE - Invalid parameters or file not writeable

8.1 .68 PFS_unlock
Description:
PFS_unlock releases a file system byte range lock established by PFS_lock().

Synopsis:
#include <pfs .b>
PFS_RETVAL PFS_unlock (PFS_FID *fp, off_t offset, short whence, off_t length)

Arguments:
fp

Open file pointer

offset

Position at which lock starts

whence

Position from which to measure offset. The following values are

defined:

length

SEEK_SET

Offset is measured from the start of
the file. Offset should be a positive
number.

SEEK_END

Offset is measured from the end of
the file. Offset should be a negative
number.

Length of range lock. A value of zero indicates range from offset to the
end of the file.

Return values:
PFS_SUCCESS - Range lock removed
PFS_F~URE - Invalid parameters or no range locked

April 20, 1992

Digital Confidential

PATHWORKS File System

8. 1 .69 PFS_unmap
Description:
PFS_unmap cleans up a memory mapped file. It does not close the file.

Synopsis:
#include <pfs .h>
void PFS_unmap (PFS_FID *fp)

Arguments:
fp

Open file pointer which was memory mapped by PFS_open().

Return values:
None

8.1. 70 PFS_utime
8.1. 71 PFS_futime
Description:
PFS_utime sets the file modification time and file access time. The time is specified PLATFORM
DEPENDENT, i.e. it will be in Unix time format for Unix systems and VMS format for VMS
systems. This function does not affect the NOS times associated with a file. Use PFS_setattr() for
modification of NOS times.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_utime (PFS_PATHID *pathid, void *timebufp)
PFS_RETVAL PFS_utime (PFS_FID *fp, void *timebufp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

Open file pointer

timebufp

Platform dependent time format. For Unix this is a pointer toa
longword and for VMS this is a pointer to a quadword time buffer.

Return values:
PFS_SUCCESS -Time modified
PFS_FAILURE - Invalid parameters or file not writeable

8.1. 72 PFS_write
Description:
PFS_write will write data to a file. The file must be open for write access.
If nbytes is zero the file is TRUNCATED at the current offset.

April 20, 1992

Digital Confidential

PATHWORKS File System

[Is this really necessary given the PFS_truncate function?? Sure makes a mess of the write code!]

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_write (PFS_FID *fp, void *buffer, unsigned int nbytes, off_t offset,
unsigned int byteswritten)

Arguments:
fp

Open file pointer

buffer

Data buffer to write

nbytes

Size of buffer to write. If this argument is zero the file will be truncated
at the position specified by offset.

offset

Position relative to the start of the file at which data is to be written.

byteswritten

Return count of bytes actually written.

Return values:
PFS_SUCCESS - File written
PFS_FAILURE - Invalid parameters or file not open for write.

8. 1 • 7 3 PFS_writedesc

Description:
PFS_writedesc will write data to a file by descriptor reference. The descriptor format is defined in
PFS_readdescO. The server is responsible for creating the descriptors and releasing the storage
associated with them.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_writedesc (PFS_FID *fp, off_t offset, PFS_DESC *desc)

Arguments:
fp

Open file pointer

offset

Position relative to start of file at which data is to be written.
Descriptior list pointer.

Return values:
PFS_SUCCESS - File written
PFS_FAILURE- Invalid parameters or file not open for write access.

8.2

File System Library (FSLIB) interface

8.2.1
8.2.2

FSLIB_access *
FSLIB_faccess *

April 20, 1992

Digital Confidential

PATHWORKS File System

Description:
See PFS_access().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_access (PFS_PATHID *pathid, PFS_USER *user, PFS_SECURITY_MODE
mode, int perms)
PFS_RETVAL FSLIB_faccess (PFS_FID *fp, PFS_USER *user, PFS_SECURITY_MODE mode,
int perms)

Arguments:
See PFS_access().

Return values:
PFS_SUCCESS -Access is allowed
PFS_FAILURE - No access or invalid path

8.2.3
8.2.4

FSLIB_chdir
FSLIB_fchdir

Description:
See PFS_chdir().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_chdir (PFS_PATHID *pathid)
PFS_RETVAL FSLIB_fchdir (PFS_FID *fp)

Arguments:
See PFS_chdir().

Return values:
PFS_SUCCESS - Default set
PFS_FAll.URE - Invalid pathid or fp

8.2.5
8.2.6

FSLIB_chmod
FSLIB_fchmod

Description:
See PFS_chmod().

Synopsis:
#include <pfs .h>
April 20, 1992

Digital Confidential

PATIIWORKS File System

PFS_RETVAL FSLIB_chmod (PFS_PATHID *pathid, mode_t mode)
PFS_RETVAL FSLIB_fchmod (PFS_FID *fp, mode_t mode)

Arguments:
See PFS_chmod().

Return values:
PFS_SUCCESS - Protetion changed
PFS_FAILURE - Invalid path

8.2.7
8.2.8

FSLI B_chown
FSLIB_fchown

Description:
See PFS_chown().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_chown (PFS_PATHID *pathid, uid_t uid, gid_t gid)
PFS_RETVAL FSLIB_fchown (PFS_FID *fp, uid_t uid, gid_t gid)

Arguments:
See PFS_chown().

Return values:
PFS_SUCCESS - Owner changed
PFS_FAILURE - Invalid path

8.2.9

FSLIB_claim

Description:
FSLIB_claim determines if the given path is in the current file system. The function may store one
longword in the pathid structure cp member for future use.

Synopsis:
#include <pfs .h>
PFS_FSTATUS FSLIB_claim (PFS_PATHID *pathid, char *path, PFS_NAMESPACE namespace)

Arguments:
pathid

Partially resolved pathid structure. This structure will contain the root
name in the fullpath member. The file system should use this and
possibly the client path name to determine if it owns the path.

path

Client path.

namespace

Namespace in which path resides.

April 20, 1992

Digital Confidential

PATIIWORKS File System

Return values:
PFS_EXISTS - File exists and is claimed by this library
PFS_NOEXIST - File does not exist but the parent path does and is claimed by this library.
PFS_UNCLAIMED_EXISTS - File exists but this library does not support it
PFS_UNCLAIMED_NOEXIST - File does not exist but the parent does. It is not supported by this
library.
PFS_FAILED -,Neither the file nor the parent exist in this library.

8.2.1 0 FSLIB_close
Description:
See PFS_close().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_close (PFS_FID *fp)

Arguments:
See PFS_close().

Return values:
PFS_SUCCESS - File closed
PFS_FAILURE- Invalid file pointer

8.2.11 FSLIB_convert

Description:
FSLIB_convert translates a filename from NOS format to native format. This function is used by
PFS_getpathid() to resolve filenames prior to file lookup. H the file system does not require name
translation this function should simply return PFS_SUCCESS.
The root directory is assumed to be located in the fullpath member of the pathid structure.
The resultant filename is returned in fullpath member of the pathid structure.
It is possible that this function will be merged with FSLIB_mapname.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_convert (PFS_PATHID *pathid, char *path, PFS_NAMESPACE namespace)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid()

path

Client file path

names pace

Namespace in which path resides.

April 20, 1992

Digital Confidential

.PATIIWORKS File System

Return values:
PFS_SUCCESS - Name translated
PFS_FAILURE - Invalid parameters

8. 2. 1 2 FSLIB_create

·Description:
See PFS_create().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_create (PFS_PATHID *pathid, mode_t mode, uid_t uid, gid_t gid,
PFS_CREATE_TYPE type, PFS_FID **fp)

Arguments:
See PFS_create().

Return values:
PFS_SUCCESS - File created
PFS_FAILURE - Invalid path or file exists and PFS_MAKENEW specified

8. 2. 1 3 FSLIB_dentpathid

Description:
See PFS_dentpathid().

Synopsis:
#include <pfs .h>
#include <dirent.h>
PFS_FSTATUS FSLIB_dentpathid (PFS_FID *fp, struct dirent *dirent, PFS_PATHID *pathid)

Arguments:
See PFS_dentathid().

Return values:
PFS_EXISTS - Path exists as specified.
PFS_NOEXIST- Path does not exist but the parent path does (i.e. a new file specification).
PFS_FAILED- Neither parent nor path exists.

8. 2. 1 4 FSLIB_didpathid

Description:
See PFS_didpathid().

Synopsis:
April 20, 1992

Digital Confidential

PATHWORKS File System

#include <pfs .h>
PFS_FSTATUS FSLIB_didpathid (PFS_CWD *dirid, char *path, PFS_NAMESPACE namespace,
PFS_PATHID *pathid)

Arguments:
See PFS_didpathidQ.

Return values:
PFS_EXISTS - Path exists as specified.
PFS_NOEXIST- Path does not exist but the parent path does (i.e. a new file specification).
PFS_FAILED - Neither parent nor path exists.

8.2.15 FSLIB_diridfunc
Description:
See PFS_diridfunc().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_diridfunc (PFS_DIRID_CMD cmd, char *root, unsigned long dirid, PFS_CWD
*dirptr)

Arguments:
See PFS_diridfunc().

Return values:
PFS_SUCCESS - Directory ID translated
PFS_FAILURE- Invalid directory ID or no directory ID set open.

8.2.16 FSLIB_diridinit
Description:
See PFS_diridinit().

Synopsis:
#include <pfs .h>
void FSUB_diridinit (PFS_DIRIDS_MATTER dodorods, unsigned long *diridptr)

Arguments:
See PFS_diridinit().

Return values:
None

8.2.17 FSLIB_filesize
8.2.18 FSLIB_ffilesize
April 20, 1992

Digital Confidential

PATIIWORKS File System

Description:
See PFS_ffilesize().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_filesize (PFS_PAIDD *pathid, PFS_DATA_STREAM stream, off_t *size)
PFS_RETVAL FSLIB_ffilesize (PFS_FID *fp, off_t *size)

Arguments:
See PFS_ffilesize().

Return values:
PFS_SUCCESS - Return size is valid
PFS_FAILURE- Invalid file pointer

8.2.19 FSLIB_fsync
Description:
See PFS_fsync().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_fsync (PFS_FID *fp)

Arguments:
See PFS_fsync().

Return values:
PFS_SUCCESS - File flushed
PFS_FAILURE- Invalid file pointer

8.2.20 FSLIB_getattr
8.2.21 FSLIB_fgetattr
Description:
See PFS_getattr().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_getattr (PFS_PATIDD *pathid, unsigned long mask, PFS_ATTR *attrp)
PFS_RETVAL FSLIB_fgetattr (PFS_FID *fp, unsigned long mask, PFS_ATTR *attrp)

Arguments:
April 20, 1992

Digital Confidential

PATHWORKS File System

See PFS_getattrO.

Return values:
PFS_SUCCESS - Attributes updated
PFS_FAILURE - Invalid parameters

8.2.22 FSLIB_getcomment
Description:
See PFS_getcomment().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_getcomment (PFS_PATHID *pathid, char *comment, int buflen)

Arguments:
See PFS_getcomment().

Return values:
PFS_SUCCESS - Coment returned
PFS_FAILURE - Invalid parameters

8.2.23 FSLIB_getdents
Description:
See PFS_getdents().

Synopsis:
#include <pfs .h>
#include <dirent.h>
PFS_RETVAL FSLIB_getdents (PFS_FID *fp, struct dirent *direntp, unsigned int nbytes, off_t
*offset, PFS_NAMESPACE namespace, unsigned int bytesread)

Arguments:
See PFS_getdents().

Return values:
PFS_SUCCESS - Buffer written (including no entries)
PFS_FALURE - Invalid parameters

8.2.24 FSLIB_getextattr *
8. 2. 2 5 FSLIB_fgetextattr *
Description:
See PFS_getextattr().
April 20, 1992

Digital Confidential

PATHWORKS .File System

This is an optional function. If the library does not support extended attributes the corresponding bit in
the PFS_LIB_ENT structure should be clear and this routine need not be present.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSUB_getextattr (PFS_PATIDD *pathid, PFS_EAOPS *eaopsp)
PFS_RETVAL FSUB_fgetextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
See PFS_getextattr().

Return values:
PFS_SUCCESS - Extended attributes written to buffer
PFS_FAILURE - Invalid parameters

8.2.26 FSLIB_getprintident

Description:
FSLIB_getprintident returns file identification information in the PFS_IDENT structure. This structure
is used primarity by the print subsystem to identify a file.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_getprintident (PFS_PATHID *pathid, PFS_IDENT *identp)

Arguments:
patbid

Resolved pathid structure as returned by PFS_getpathid().

identp

Pointer to return identification structure.

Returns:
PFS_SUCCESS - Print identification returned
PFS_FAILURE- Insufficient information

8. 2. 2 7 FSLIB_getsecurity *
8.2.28 FSLIB_fgetsecurity *
Description:
See PFS_getsecurity().
This is an optional function. If the library does not support security data the corresponding bit in the
PFS_LIB_ENT structure should be clear and this routine need not be present.

Synopsis:
#include <pfs .h>

April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_RETVAL FSLIB_getsecurity (PFS_PATIDD *pathid, PFS_SECURSPACE securspace,
void *securp)
PFS_RETVAL FSLIB_fgetsecurity (PFS_FID *fp, PFS_SECURSPACE securspace, void *securp)

Arguments:
See PFS_getsecurity().

Return values:
PFS_SUCCESS - Returned attributes
PFS_FAll.URE - Invalid parameters

8.2.29 FSLIB_init
Description:
FSLIB_init initializes the file system library. The routine is called once, when the file system is
loaded. This routine should be given a universal name of the form <name>_init where <name> is the
name of the file system if the library is to be dynamically loaded.
See PFS_init() for a description of dynamic library loading.

Synopsis:
#include <pfs .h>
PFS_FSTATUS FSLIB_init (PFS_LIB_ENT *libentp, FILE *log_file)

Arguments:
Iibentp

Pointer to next library entry slot.

log_file

File pointer for debug use. This may be a temporary debug aid for
product qualification.

Return values:
None

8.2.30 FSLIB_lock
Description:
See PFS_lock().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_lock (PFS_FID *fp, short type, off_t offset, short whence, off_t length,
PFS_WAIT_LOCK dowait, off_t *start)

Arguments:
See PFS_lock().

Return values:
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_SUCCESS - Lock set
PFS_FAILURE - Invalid parameters or lock conflict

8.2.31 FSLIB_lookup

Description:
FSLIB_lookup will locate the file in the current file system.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_lookup (PFS_PATHID *pathid, char *client_name)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

client_name

Specified a client name to translate by lookup. This is used for the
Macintosh filename translation algorithm.

Return values:
PFS_SUCCESS - File located
PFS_FAILURE - File not found

8.2.32 FSLIB_lseek
Description:
See PFS_lseek().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_lseek (PFS_FID *fp, off_t offset, int whence)

Arguments:
See PFS_lseek().

Return values:
PFS_SUCCESS - File position changed
PFS_FAILURE - Invalid parameters

8.2.33 FSLIB_mapname
8.2.34 FSLIB_fmapname
Description:
See PFS_mapname().

Synopsis:
#include <pfs .h>
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_RETVAL FSLIB_mapname (PFS_PATHID *pathid, PFS_NAMESPACE namespace,
char *namebuf, int buflen)
PFS_RETVAL FSLIB_fmapname (PFS_FID *fp, PFS_NAMESPACE namespace, char
*namebuf, int buflen)

Arguments:
See PFS_mapname().

Return values:
PFS_SUCCESS - Name translated
PFS_FAILURE - Invalid parameters or buffer too small

8.2.35 FSLIB_mkdir
Description:
See PFS_mkdir().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_mkdir (PFS_PATHID *pathid, mode_t mode, uid_t uid, gid_t gid,
unsigned long *dirid)

Arguments:
See PFS_mkdir().

Return values:
PFS_SUCCESS - Directory created
PFS_FAILURE - Invalid parameters

8.2.36 FSLIB_mpxclose
Description:
See PFS_mpxclose().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_mpxclose (PFS_FID *fp)

Arguments:
See PFS_mpxclose().

Return values:
PFS_SUCCESS - File is close in the underlying file system
PFS_FAILURE - Invalid parameters
April 20, 1992

Digital Confidential

PA'TIIWORKS File System

8.2.37 FSLIB_mpxopen
Description:
FSLIB_mpxopen will multiplex open a file previously multiplex closed. The open mode is stored in
the PFS_FID structure and will be used to reopen the file in the same mode as previously open. Note
that a file with locks can not be multiplex closed. This eliminates the need to attempt to reestablish
lcoks within the file.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_mpxopen (PFS_FID *fp)

Arguments:
fp

Previously open file pointer. The file will be reopened in the same
mode as originally open.

Return values:
PFS_SUCCESS - File open
PFS_FAILURE - Invalid parameters

8.2.38 FSLIB_open
Description:
See PFS_open().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_open (PFS_PATHID *pathid, PFS_STAT *statbufp, int oflag,
PFS_DATA_STREAM stream, PFS_MEM_MAP dommap,
PFS_FID **fp)

Arguments:
See PFS_open().

Return values:
PFS_SUCCESS - File open
PFS_FAILURE - Invalid parameters

8.2.39 FSLIB_purge
8.2.40 FSLIB_fpurge
Description:
See PFS_purgeQ.
Note that PFS_fpurge is provided to support PFS_closeandpurge. The file pointer points to a closed
file but the file pointer is still valid. Information in the file pointer should be used to guarantee the
exact file opened will be deleted (care must be taken if the file is to be deleted by name as multiple
April 20, 1992

Digital Confidential

PATHWORKS File System

versions and search paths may cause the name to be ambiguous). The file system library should provide
some means to uniquely identify a file and store this information in the pathid/fid structure.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_purge (PFS_PATIDD *pathid)
PFS_RETVAL FSLIB_fpurge (PFS_FID *fp)

Arguments:
See PFS_purgeO.

Return values:
PFS_SUCCESS - File deleted
PFS_FAILURE - Invalid parameters

8.2.41 FSLIB_read
Description:
See PFS_read().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_read (PFS_FID *fp, void *buffer, unsigned int nbytes, off_t offset,
unsigned int *bytesread)

Arguments:
See PFS_read().

fReturn values:
PFS_SUCCESS - Bytes read (including none)
PFS_FAILURE - Invalid parameters

8. 2. 4 2 FSLIB_readdesc

Description:
See PFS_readesc().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_readdesc (PFS_FID *fp, unsigned int nbytes, off_t offset, PFS_DESC **desc)

Arguments:
See PFS_readdesc().

Return values:
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_SUCCESS - Data read
PFS_FAil.URE - Invalid parameters

8.2.43 FSLIB_rename
Description:
See PFS_rename().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_rename (PFS_PATHID *oldpathid, PFS_PATHID *newpathid)

Arguments:
See PFS_rename().

Return values:
PFS_SUCCESS - File renamed
PFS_FAILURE- Invalid parameters, conflicting file systems or conflicting namespace

8.2.44 FSLIB_rmdir
Description:
See PFS_rmdir().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_rmdir (PFS_PATHID *pathid)

Arguments:
See PFS_rmdir().

Return values:
PFS_SUCCESS - Directory deleted
PFS_FAll.URE - Invalid parameter, directory not empty

8.2.45 FSLIB_setattr
8.2.46 FSLIB_fsetattr
Description:
See PFS_setattr().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setattr (PFS_PATHID *pathid, PFS_ATTR *attrp)
April 20, 1992

Digital Confidential

PATHWORKS File System

PFS_RETVAL FSLIB_fsetattr (PFS_FID *fp, PFS_ATIR *attrp)

Arguments:
See PFS_setattr().

Return values:
PFS_SUCCESS - Attributes modified
PFS_FAILURE - Invalid paramters or file not writeable

8.2 .4 7 FSLIB_setcomment
Description:
See PFS_setcomment().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setcomment (PFS_PATHID *pathid, char *comment)

Arguments:
See PFS_setcomment().

Return values:
PFS_SUCCESS - Comment written
PFS_FAILURE - Invalid paramters or file not writeable

8. 2. 4 8 FSLIB_setextattr *
8.2.49 FSLIB_fsetextattr *
Description:
See PFS_setextattr().
For a description of optional functions see FSLIB_getextattr().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setextattr (PFS_PATHID *pathid, PFS_EAOPS *eaopsp)
PFS_RETVAL FSLIB_setextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
See PFS_setextattr().

Return values:
PFS_SCCESS - Attributes modified
PFS_FAILURE - Invalid parameters or file not writeable
April 20, 1992

Digital Confidential

PATHWORKS File System

8.2.50 FSLIB_setsecurity *
8. 2. 5 1 FSLIB_fsetsecurity *
Description:
See PFS_setsecurity().
For a description of option functions see FSLIB_getsecurity().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setsecurity (PFS_PATHID *pathid, PFS_SECURSPACE securspace,
void *securp)
PFS_RETVAL FSLIB_fsetsecurity (PFS_FID *fp, PFS_SECURSPACE securspace, void *securp)

Arguments:
See PFS_setsecurity().

Return values:
PFS_SUCCESS - Data associated
PFS_FAILURE - Invalid parameters or file not writeable
PFS_NOTSUPPORTED - Security data not supported

8.2.52 FSLIB_stat
8.2.53 FSLIB_fstat
Description:
See PFS_stat().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_stat (PFS_PATHID *pathid, PFS_DATA_STREAM stream,
unsigned long mask, PFS_STAT *statbufp)
PFS_RETVAL FSLIB_fstat (PFS_FID *fp, unsigned long mask, PFS_STAT *statbufp)

Arguments:
See PFS_stat().

Return values:
PFS_SUCCESS - Information obtained
PFS_FAILURE - Invalid parameters

8.2.54 FSLIB_statvfs
8.2.55 FSLIB_fstatvfs
Description:
See PFS_statvfs().
April 20, 1992

Digital Confidential

PATHWORKS File System

Synopsis:
#include <pfs .b>
PFS_RETVAL FSLIB_statvfs (PFS_PATHID *pathid, statvfs_t *fsbufp)
PFS_RETVAL FSLIB_fstatvfs (PFS_FID *fp, statvfs_t *fsbufp)

Arguments:
See PFS_statvfs().

Return values:
PFS_SUCCESS - Information obtained
PFS_FAILURE - Invalid parameters

8.2.56 FSLIB_sync
Description:
See PFS _sync().

Synopsis:
#include <pfs .b>
void FSLIB_sync (void)

Arguments:
None

Return values:
None

8.2.57 FSLIB_ftruncate
Description:
See PFS_ftruncate().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_ftruncate (PFS_FID *fp, off_t size)

Arguments:
See PFS_ftruncate().

Return values:
PFS_SUCCESS - File truncated
PFS_FAILURE - Invalid parameters or file not writeable
April 20, 1992

Digital Confidential

PATHWORKS File System

8.2.58 FSLIB_unlock
Description:
See PFS_unlock().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_unlock (PFS_FID *fp, off_t offset, short whence, off_t length)

Arguments:
See PFS_unlock().

Return values:
PFS_SUCCESS - Range lock removed
PFS_FAILURE - Invalid parameters or no range locked

8.2.59 FSLIB_unmap
Description:
See PFS_unmap().

Synopsis:
#include <pfs .h>
void FSLIB_unmap (PFS_FID *fp)

Arguments:
See PFS_unmap().

Return values:
None

8.2.60 FSLIB_utime
8.2.61 FSLIB_futime
Description:
See PFS_utime().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_utime (PFS_PATHID *pathid, void *timebufp)
PFS_RETVAL FSLIB_utime (PFS_FID *fp, void *timebufp)

Arguments:
See PFS_utime().
April 20, 1992

Digital Confidential

. PATHWORKS File System

Return values:
PFS_SUCCESS - Time modified
PFS_FAILURE - Invalid parameters or file not writeable

8.2.62 FSLIB_write
Description:
See PFS_write().

Synopsis:
#include <pfs.h>
PFS_RETVAL FSLIB_write (PFS_FID *fp, void *buffer, unsigned int nbytes, off_t offset,
unsigned int byteswritten)

Arguments:
See PFS_write().
~eturn

values:

PFS_SUCCESS - File written
PFS_FAILURE - Invalid parameters or file not open for write.

8.2.63 FSLIB_writedesc

Description:
See PFS_writedesc().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_writedesc (PFS_FID *fp, off_t offset, PFS_DESC *desc)

Arguments:
See PFS_writedesc().

Return values:
PFS_SUCCESS - File written
PFS_FAILURE - Invalid parameters or file not open for write access.

April 20, 1992

Digital Confidential

PATHWORKS File System

STANDARD LIBRARIES
PFS provides two standard file system libraries for VMS, ODS2 DOS library and ODS2 MAC library.
These two libraries are very tightly coupled. The partion is provided for functional separation only. The
underlying file storage is mapped on the ODS2 file system for both libraries.

9. 1

0052 DOS library

The ODS2 DOS library is responsible for all DOS related file access in the ODS2 file system. The
library provides name translation, attribute storage, data storage and Lan Manager security data storage.

9. 1 . 1

Names pace

The ODS2 DOS library uses the following algorithm for mapping DOS filenames to VMS filenames:

Convert lowercase to uppercase
[What do we do about underscore in filename ??]
FOR each VMS illeagal character DO
Insert two underscores LJ
Convert character to hex ASCII code
IF extention EQL "DIR" insert two underscores LJ
For example, name@.dir would be converted to NAME_40._DIR

The ODS2 DOS library uses the following algorithm to map VMS filenames to DOS filenames:

Convert uppercase to lowercase
FOR each double underscore DO
Remove underscore
Convert hex ASCII code to character
IF extention EQL "_dir" remove double underscore
For example, NAME_40._DIR would be converted to name@ .dir

9. 1 . 2

Attributes

The ODS2 DOS library stores DOS file attributes in a VMS applicaton ACE. The format of this ACE
is shown below.

April 20, 1992

Digital Confidential

PATHWORKS File System

ace$w_flags

ace$b_type

ace$w_facility_flags
pfs$b_flags

l pfs$b_version

l ace$b_size

ace$w_facility
pfs$b_type

l pfs$b_size

0
4
8

dos$l_file_size

dos$r_attributes

dos$q_modify_time

dos$l_file_size (cont)

dos$q_modify_time (cont)

dos$l_create

dos$q_modify_time (cont)

dos$l_lastaccess

dos$l_create (cont)

dos$l_lastmod

dos$l_lastaccess (cont)

dos$l_lastmod (cont)

The ACE contains DOS file times in DOS format. The file size is calculated by reading the file and
counting record lenghts (VAR file format). This count is marked with the file modification time such
that it need not be recalculated unless the file has been modified.
The DOS$L_LASTACCESS field holds the time at which the file was last accessed, regardless of
modification. This is an expensive field to maintain and may not be supported. This field would need to
be set for read-only files (such as application images) each time the file was opened or closed.

9.1.3

Security

The DOS file system has no security data associated with it. However, DOS clients are supported by
Lan Manager which defines its own security model. The ODS2 DOS library will support storage and
retrieval of security information for Lan Manager.
NOTE
The file system library has no concept of the security model, association of security
data nor security data hierarchy. This may force the server to querry all members of a
file path in search of security data (Lan Manager security inheritance). This access
may nullify the advantages of using path caches to optimize file access as the path
may need to be processed member by member to obtain security data.
Alternately, the file system library may understand the security data hierarchy and
obtain security data above the requested object. The path cache may perform better in
this environment.

9. 1 •4

Data paths

The ODS2 DOS library supports native DOS file formats (stream) as well as native VMS file formats
(VAR, FIXED, INDEXED, etc). The library will use RMS for complex file organization (INDEXED).
The library will use QIO for simple file organization (VAR, VFC, FIXED, STREAM XX).
The ODS2 DOS library will only create files -in STREAM format. If a particular file format is desired
on the host an external file conversion utility must be used.

9.1.5

FID cache

To facilitate ACE lookups and security data processing the ODS2 DOS library maintains recently
accessed file headers in a cluster-wide distributed cache. This cache is used to obtain the DOS ACE on
directory search functions as well as file access.
April 20, 1992

Digital Confidential

PATHWORKS File System

The FID cache is invalidated when a file is deleted or header data is modified. The local node cache
invalidates the specific entry involved. Cluster-wide invalidation is limited to the hash chain which
contains the entry in order to limit the amount of distributed locks.

9. 1 . 6

Directory cache

The ODS2 DOS library maintains a cache of directory entries. This cache presents directories as fixed
length structures to support the Search SMB. It is currently not clear whether this cache will be
necessary given the Lan Manager directory structures.

9.1.7

Path cache

The ODS2 DOS library maintains a cache of recently translated paths. This cache is used to improve
performance of file lookups. This cache contains path name to directory ID (DID) translations. Host
security data for the directory is also stored here to imporve host security checking. It should be noted
that VMS (RMS in particular) only stipulates security checking on the last member of a path. Was
this not the case the path cache would not be useful for security data.

9.2

ODS2 MAC library

The ODS2 MAC library supports Macintosh clients. The library provides filename mapping, attribute
storage, security data storage and Macintosh multifork file formats. The library maps all functions to
the VMS ODS2 file system.

9.2.1

Namespace

The ODS2 MAC library stores Macintosh filenames in an application ACE associated with the file.
This arrangement provides consistency between Macintosh filenames and Macintosh files. However,
VMS provides very little to support filename lookups by anything other than VMS directories. It is
necessary to establich external structures to provide this translation. The performance of the Macintosh
file system is extremely dependent on the efficiency of these external structures.

NOTE
The design of the ODS2 MAC library creates all external structures in memory, on
demand. There are no external files to buffer the building of these in memory
structures. While this design provides a high degree of consistency there are huge
differences in perfomance for functions which hit the in memory structures and those
for which the structures must be built. The overall performance will depend of the
availability of memory to hold these structures and the frequency of invalidates.
In order to limit the length of directory searches for a Macintosh file there is a strict relationship
between the Macintosh filename and the VMS filename (and hence the DOS filename). To allow an
unrestricted filename relationship with no external structure file support would result in unacceptable
performance for moderate to large directories. Preliminary performance measurements show that header
lookups take between 5-15ms (VAX3100 M48). This would mean up to 30 seconds to locate a file in a
directory of 2000 files (actual measurement).
File creates are done by converting the Macintosh name to a VMS name and creating the file. The file
create will either a) fail due to existing file of the same name (and version) b) succeed with a higher
version warning or c) succeed. Case a) and b) are failures. Macintosh filename creates are mapped to
VMS names using the following algorithm:

Split filename and extension at first '.'
Remove all DOS illegal characters
Truncate to 8 .3 format
UNTIL unigue DO
April 20, 1992
Digital Confidential

PATHWORKS File System

Convert DOS name to VMS name
IF file exists replace last DOS character with digit 0-9
IF replacement at '9' then filename conflict
END
For example, "Macintosh Filename" would be converted to MACINTOS., MACINTOl.,
MACINT02., etc.

Macintosh filename lookups are performed by converting the Macintosh filename to a VMS wildcarded
pattern and then searching for this filename. For each match the Macintosh ACE is examined for a
matching filename. Macintosh filename lookups are converted to VMS names using the following
algorithm:

Split filename and extension at first '.'
Remove all DOS illegal characters
Truncate to 8 .3 format
Remove last DOS character
Convert DOS name to VMS name
Append VMS wilcard to filename and extension (*)
Search directory and match Macintosh filename against name stored in ACE
For example, "Macintosh Filename" would be converted to MACINTO* .*.

NOTE
It is possible that this algorithm may be modified for Macintosh-only installations.
The conversion to DOS legal format could be replaced by a conversion to VMS legal
format. This change may result in more meaningful filenames to Macintosh/host
users.

9.2.2

Attributes

The ODS2 MAC library stores Macintosh attributes in an application ACE. This ACE shares the same
physical VMS ACE as the DOS ACE. The header is shown here for completeness but is actually the
same ACE header as for the DOS ACE. The PFS header is present on the Macintosh ACE, i.e. the data
starting at byte 8.

April 20, 1992

Digital Confidential

PATHWORKS File System

ace$w_flags

ace$b_type

ace$w_facility_flags
pfs$b_flags

ace$b_size

ace$w_facility

Jpfs$b_version

pfs$b_type

pfs$b_size

4
8

longName

shortName

parentID

fileID

60
attributes

finderlnfo

finderInfo (cont)

64
68

finderlnfo (cont)

offspringCount

proDOSinfo

createDateTime

100

modifyDateTime

104

backupDateTime

108

ownerID

112

groupID

116

l world.Rights

groupRights

ownerRights

proDOSinfo (cont)

120
124

dataForkLength

proOOSinfo (c)

128

resForkLength

dataForkLen (c)

132

resForkLen (c)

136

The times stored in the ACE are in Macintosh format. The fileID and parentID fields are modified VMS
FID format. The sequence field and relative volume number fields are shortened to map to 32 bits. This
requires a direct index file lookup to translate the file number back to the VMS FID. Again, this design
choice has been made to eliminate the need for external files describing the Macintosh environment.
The library does not maintain the file creation times, modification times or backup times in the
Macintosh ACE. This is the responsibility of the server.

9.2.3

Security

The ODS2 MAC library stores Macintosh security data in the appropriates fields of the Macintosh
ACE (described above). The data is not interpretted.
Macintosh has a concept of "giving folders away". To Macinsosh, this is as simple as changing the
owner of a directory. As file protection in Macintosh is inherited there is no further modification
required. VMS has no such concept. It may be required for the server to modify each file in the directory
to be "given away". This is likely a time consuming task. PFS supports this function by providing
functions to change the host owner of a file. The server must use a combination of directory
enumerates and change owner functions to complete the host mapping of security changes associated
with the new owner.

9.2.4

Datapaths

April 20, 1992

Digital Confidential

PA1HWORKS File System

The ODS2 MAC library supports the native VMS file formats are Macintosh data fork only files. The
resource length for these files will always be returned as zero. The library supports a special file format
to handle two forks per file. This file format is described in Appendix E.
The library will create files in STREAM format UNLESS a resource fork is created prior to the data
fork. In this case the Macintosh file format is used on create. Ha resource fork is added to a STREAM
file it will be converted to a Macintosh format file (by remapping block 1 of the file). Non-stream files
can not have a resource fork added to them with out conversion to stream format first. The library does
not support this.

9.2.5

Name cache

The ODS2 MAC library maintains a cache of recently translated Macintosh filenames. This cache can
only be used for file lookups as a miss in the cache is never sufficient to declare a file does not exist.
(However, a hit would indicate the file already exists). The cache is tightly coupled to the ODS2 DOS
FID cache and invalidates are done in the exact same manner.

April 20, 1992

Digital Confidential

PATHWORKS File System

Appendix A - VMS ODS level 2 file system
This appendix contains information about the VMS ODS level 2 file system. This information is
presented to provide context for evaluating the mapping between NOS file systems and ODS2. The
information herein is meant to be complete. Only the attributes and semantics relavent to NOS file
systems are presented.

A.1

Directory

structure

ODS2 uses hierarchial directory structure. Directory files appear as contiguous variable length files
with variable record format. Records can not cross record boundaries.
Directory entries are packed within disk blocks. The records are arranged alphabetically. The records will
be shuffled when a new entry is added to maintain alphabetic order.
Directory entries contain filenames, version numbers and file identificaton information. File
identification information (FID) is associated with a specific version of each file. The individual version
to FID mapping records are stored in order following the filename record.
Directory nesting depth is not limited by ODS2. However, RMS limits the depth of a directory
specification to 8 levels. Unlimited depth may be processed by RMS with the use of concealed logical
names. The names.specify at least the part of the directory tree which would exceed 8 levels.
VMS BACKUP is limited to 8 levels in a directory tree. There is no warning that additional directory
levels are being skipped.

A.2

File

structure

ODS2 associates file attributes and generic file meta data with files in the file header. The file header is
stored in the index file and is accessed by the file identification number (FID). The FID is a 48 bit
structure which contains the relative volume number (volume number of bound volume set), sequence
number (used to identify the instance of the file number) and file number. The file number is the index
into the index file.
ODS2 provides direct file access by FID. The FID is sufficient to uniquely identify a file on a volume.
No additional directory information is required.
The file header maps the virtual blocks in the file to logical blocks on the disk. Only one set of file
retrieval pointers are maintained. This set coresponds to the data portion of the file.
The file header contains ACE information. This information specifies aditional security information,
RMS attributes, or application specific information. PPS makes extensive use of the application ACE
capabilities of ODS2 to associate NOS data with a file.

A. 2. 1

Access Control Lists (ACL)

ODS2 provides storage of information in the file header. Multiple file headers will be used if this
information will not fit in the primary header. Additional fil headers are allocated from the index file
and chained to the primary header. (This reduces the number of file which can be stored on the volume).
Access control lists are lists of Access Control Elements (ACE). While the term implies the
information associated with the list controls access to the file, generic information may be stored in
~&.
.
VMS XQP (extended QIO processor) provides access to information strored in the file header. ACEs
may be added, deleted or modified. The XQP accepts multiple ACE manipulation functions per
invocation. However, not all combination of functions will result in predictable results. The XQP
April 20, 1992
Digital Confidential
92

PATHWORKS File System

maintains context information which is used to address a specific ACE. There is no direct address
capability, however, a specific ACE may be located and the current pointer set to it. Once an ACE is
located it may be modified or deleted. It is possible to locate multiple ACEs and modify them in a
single invocation but FIND functions must be interspersed within the function list to maintain correct
ACE positioning. Multiple new ACEs may be added without too much trouble.

A.3

File

attributes

ODS2 maintains a set of file attributes. These attributes specify the file organization, record format,
access times, etc. While this information may be common with some of the NOS file attributes, a
complete mapping is not possible.

A.3.1

File creation time

The time at which a file is created is stored in the file header. This time is set when an XQP create
function is executed.

A.3.2

File revision time

The file revision time is modified when a write function or modify function is executed. Initially the
revision time is set to the creation time.

A.3.3

File backup time

The VMS BACKUP utility sets the time at which a file is backed up. This field may be used to
determine if a file has been modified since the last backup.

A.3.4

File expiration time

ODS2 allows a specification of time at which file may not be accessed.

A.3.5

File organization

ODS2 itsefk does not provide any support for file organization. Files are simply collections of logical
blocks. However, VMS RMS does provide various file organizations and in order to process a file the
organization must be known and understood. RMS provides three file organizations:

A.3.6

SEQUENTIAL

Records are stored sequentially. Access is allowed either sequentially or
by record address. Records may be variable length or fixed.

RELATIVE

Records are stored in fixed length blocks addressable via block number.
The records within the blocks may be of any size. The record blocks
may or may not be related to disk blocks.

INDEXED

Records are chained to an index key. Multiple indicies may be used.
Records may be variable length.

Record structure

ODS2 itself does not provide any record structure. Files are accessible via 512 bytes blocks. However,
VMS RMS does provide record format and in order to process a file this record format needs to be
known and understood. Neyther ODS2 nor RMS provide any means for determining how much data is
actually stored in a file. The only information available is where the current end of file mark is. RMS
provides the following record formats:
VARIABLE

April 20, 1992

Records are prefixed by a count. The count is one word in length and
counts the actual number of bytes in the record. All records are aligned
on a word boundary (so there may be an extra byte in the actual record
as stored in the file). Most VMS text files are stored in this format.
Digital Confidential
93

. PATIIWORKS File System

A. 3. 7

VFC

Variable with fixed control. The record contains a fixed number of bytes
followed by a variable format record. File created with DCL OPEN,
DCL WRITE and DCL CLOSE will be of this format.

FIXED

Fixed length records. The records may be of any size although 512 is
most common. VMS images will be of this format.

STREAM

No record prefix. Records are terminated with <CR>, <LF> or <FF>,
<VT> or <CR><LF'>.

STREAM_CR

No record prefix. Records are terminated with <CR>.

STREAM_LF

No record prefix. Records are terminated with <LP>.

UNDEFINED

No record format.

Record attributes

ODS2 does not define any record attributes. As with record formats, the record attributes must be
known and understood to process the file. VMS RMS defmes the following record attributes:
BLK

Records may not cross block boundaries. Blank space may be found at
the end of disk blocks.

<CR><LF> to be prefixed to record when displayed on carraige control
device. (Not applicable to file service).
Fortran carraige control. (Not applicable to file service).

PRN

A.4

File

Print carraige control. (Not applicable to file service).

allocation

ODS2 allocates file in groups of disk blocks called clusters. The cluster size is determined when the
disk is initialized.
·
Files may be allocated contiguous meaning all logical blocks of the file are contiguous.

A.4. 1

File header

The file header contains all information stored about a file. The file attributes, ACEs, retrieval pointers
and linkage to extension headers is stored in the file header.
File headers reside in the index file. Prior to processing a file, the index file must be read to obtain at
least the primary header. This read is in addition to filename processing information located in the
directory file.

A.4.2

Index file

ODS2 volumes contain an index file, INDEXF.SYS. This file is present on each volume, including
each volume in a bound volume set. The index file is used to store file headers. There is a set of fixed
length file headers which may be chained to store information about a file. The index file is addressed
with the file identification number from the FID or DID.

A.4.3

Bitmap file

April 20, 1992

Digital Confidential

. PATHWORKS File System

ODS2 contains a bitmap file which marks disk clusters either in use or free. The bitmap file is rebuilt
if the volume is improperly dismounted. The bitmap is rebuilt by reading the index file and processing
each file's retrieval pointers. In this manner, multiple linkages to disk blocks can be eliminated.

A.4.4

Quota file

ODS2 provides disk usage quotas for specific users. Any file allocations are subtracted from the user's
quota. The user will be prevented from allocating more blocks than specified in the quota and overdraft
limits provided by the quota file.

A.S

Security model

ODS2 security is provided in two levels, user identification (UIC) and ACLs. Four classes of users are
defined:

OWNER

User whose UIC matches the file owner

GROUP

Users whose group portion of their UIC matches the group portion of
the file owner UIC.

SYSTEM

Users in the system group [l,].

WORID

Any user who does not fall in one of the above.

For each class there are four access modes:
READ

Users may read file or perform wildcard directory lookups.

WRITE

Users may write file or change its attributes.

EXECUTE

Users may execute file or perform specific directory lookups.

DELETE

users may delete a file.

ACLs provide the same basic access with one additional access:
CONTROL
ACLs differ from UIC protection in that they are checked against a user's rights identifiers, not the
user's UIC. In this manner groups of users may be granted or denied access independent ofUIC group.
ACLs are applied after the UIC check is made. Therefore a user may be given access based on UIC even
if the user is denied access based on the ACL.

April 20, 1992

Digital Confidential

PATHWORKS File System

Appendix B - MSDOS FAT file· system
This appendix provides information about the MSDOS FAT file system. This file system is used in
MSDOS clients. While many functions the server needs to provide are outside the scope of the FAT
file system, many are directly related to the structure. This appendix is provided to present the issues
which relate to the FAT file system.

B.1

Directory

structure

MSOOS FAT provides variable length directories consisting of fixed records. Each record corresponds
to a file. All file information is stored in the directory entry with the exception of file allocation table
entries (FAT) which are pointed to by the directory record.
The filename is limited to 8 .3 format, described in section 7 .3.
The directory is not arranged in any partcular order. The directory expands as files are added and does not
shrink once files are deleted. A given file's directory entry will occupy exactly the same position in the
directory as long as the file exists. Once a file is deleted, its slot in the directory is free for reuse.

NOTE
The Search SMB is very much dependent on this directory structure. The success of a
given server implementation is largely determined by the degree of consistency
between the server's virtual directory stucture and that of MSDOS FAT. This
structure can be seen in LanManager's implementation of the Search SMB.

B.2

File

structure

MSDOS FAT files contain one data stream only. There are no extended attributes associated with the
file. The file has no record structure.

B.3

File

attributes

MSDOS FAT provides a set of five file attributes, described in section 7.3. There is only one file
modification time stored with the file. This time is initially set to the file creation time.

B. 3. 1

Modification time

The MSDOS FAT file system saves the time at which a file is created or modified. Once a file is
modified, the original file creation time is lost.

B.4

File

Allocation

The MSDOS FAT file system allocates file blocks in groups called clusters. The size of a cluster is set
at volume initialization time. For each cluster there is a 12 or 16 bit field in the File Allocation Table
(FAT). 12 bitFATs are used for small volumes (less than 20740 blocks). 16 bitFATs are used for
large volumes. The largest volume supported by FAT is approximately lOM bytes.

B.5

Security model

MSDOS FAT file system provides no native security. The security associated with an MSDOS client
will be that of the server. If the MS DOS client is served by LanManager the security requirements will
be those of LanManager. If the MSDOS client is supported by AFP the security model will be that of

AFP.
April 20, 1992

Digital Confidential

PATHWORKS File System

Appendix C - Macintosh HFS file system
This appendix provides information about the Macintosh Hierarchial File System (HFS). This
information is provided as a reference to the requirements placed on the server and hence on the file
system.

C.1

Directory

structure

Macintosh maintains a hierarchial directory structure. The directory information is stored in the catalog
tree on each volume.
Filenames are limited to 32 characters and are described in section 7.3.
Each directory is assigned a unique 32 bit value which may be used to directly reference the directory.
This information may be held by Macintosh applications including the Macintosh Finder.
A server file system must be capable of associating a 32 bit ID with each directory and provide direct
access to the directory by this ID.

C.2

File

structure

Macintosh maintains various file attributes associated with the file. The information is stored in the
directory entry for the file. Macintosh assigns a unique 32 bit ID to each file. This ID may be stored in
"alias" entries in V7 Macintosh file systems. Starting with V7, files must be accessible via this 32 bit
ID. V7 clients can specify that a file ID is o be "swapped" between two files.
A server must be capable of assigning a unique 32 bit ID to each file and directly accessing the file by
its ID. The server file system must either swap the file IDs on request or swap the data associated with
each file ID.
Macintosh also supports two data streams per file. There are two sets of mapping pointers for each file.
A server file system must be capable of associating two data streams with each file.

C. 2. 1

Data fork

Macintosh files have a data stream associated with them. This data stream contains nromal file data and
is accessible to all clients supported by a server.

C.2.2

Resource fork

Macintosh also associates a resource stream with the file. This stream is Macintosh specific and is
assumed to have a specific format. The information stored in this stream is of little or no use to other
client types. This stream may not be addressible to non Macintosh clients.

C.3

File

attributes

Macintosh maintains a set file file attributes stored in the directory entry for the file. These attributes
describe access to the file and file visibility. The Macintosh file attributes are described in section 7 .3.

C. 3. 1

File creation time

Macintosh stores the time at which a file is created. This time will not be modified. All Macintosh
times are signed 32 bit quantities designating the time before or after 00:00:00 January 1, 2000.

C. 3. 2

File modification time

April 20, 1992

Digital Confidential

PATHWORKS File System

Macintosh stores the time at which a file is modified. This time is initially set to the creation time.

C.3.3

File backup time

Macintosh also stores a file's backup time. This time may be set and used by external backup utilities.

C.4

File

allocation

Macintosh allocates groups of disk blocks into allocation blocks. The size of the allocation block is set
at volume intializatino time. Groups of allocation blocks are stored in records called extents. Each
extent is an allocation block number followed by the count of blocks in the extent. The first set of
extents (3 records) is stored in the directory entry for the file. If a file requires additional extents they are
stored in the extents tree. The extents tree is arranged as a set of index nodes containing three extent
descriptors. The index nodes are kept sorted by file ID and file allocation block number.
This arrangement is conceptually similar to ODS2s retrieval pointers.

C.S

Security

model

The Macintosh file system provides no native security. The security associated with a Macintosh client
will be that of the server. Currently Macintosh clients are only served by AFP.

April 20, 1992

Digital Confidential

PATIIWORKS File System

Appendix D - FSI interface
This appendix was written from notes taken during the initial review of the LMU PSI implementation.
The structure and function of the PSI is described. Various notes about the application of the design to
the VMS file system are included.

D.1

General

Architecture

The LMU File System Interface (FSI) is designed to be used with multiple back end file systems. The
file system selection is based on the concept of "path" ownership. This design will allow multiple file
systems to be used in a server environment. The basic assumption is that various file systems can be
used anywhere in the UNIX file system space. The path is the client file name translated into the server
file system's semantics.
The PSI routines use a function dispatch table to execute file system specific tasks associated with the
path's file system. Most of these routines are mapped one-to-one with the FSI routines. This scheme
partitions the file system into two levels, general file access (performed at the PSI layer) and file
system specific access (performed thru dispatch table). Functions common to all file systems are
performed at the FSI layer. Functions to perform file system specific tasks are collectively known as
"libraries".

NOTE
The FSI functions use UNIX features and assume that UNIX is under the file system
(errno and UNIX error numbers). This assumption greatly reduces the overall effect of
the library partition.
The concept of file system libraries is further reduced by the use of "special libraries"
which map FSLIB functions to special FSI functions, most notably the
FSI_setvmtime(), FSI_update_dtO and FSI_checkvolume() which map to
MACUTILS library FSLIB functions FSLIB_chdir(), FSLIB_fchdirO and
FSLIB_access(), respectively. While this provides dynamic loadable support for
MAC style access, it is certainly to be viewed as somewhat less than clean. This
library mapping is handled by a special check in the INIT_ENTRY loadable library
support. The MAC library is not otherwise mapped. We do not have sources for this
library extension.
It would probably be best if the FSI routines directly handled MAC extensions.

D. 1 .1

File

Descriptor

Multiplexing

The FSI implements "file descriptor multiplexing" to prevent client access failure due to server process
file descriptor resource depletion.
The FSI makes calls available to perform multiplexing and to provide notification when automatic
multiplexing is done.

NOTE
This mechanism seems to be UNIX specific and may not be required with SVR4. It
would appear that this service really belongs in the file system library level, not the
FSI. The FSI should be a platform independent interface and file multiplexing may
be a phenomenon peculiar to UNIX.
Multiplexing will occur when an FSLIB_open call fails and returns the UNIX errno ENFILE (file table
overflow) or EMFILE (too many open files). ENFILE will result in a call to FSI_needinodes which
uses an internal count to determine how many files to close based on the number of times the function
April 20, 1992

Digital Confidential

PATHWORKS File System

is called (the more times it is called the greater the number of files it will try to close at once). There is
a limit of calling the function 4 times (magic number declared in multiple routines, forceopen,
opencreate, FSl_needinodes). EMFILE will result in a call to a local routine (close_a_file) which will
close FSI_closecount files. This variable is set by INI package calls and is fixed for each call. Both
mechanisms result in a call to FSLIB_mpxclose to actually close open files.

D. 1 . 2

Volume Services

The FSI does not provide volume level services. It must assume that the server layer has some
knowledge of volumes and path names to volume directories. The server layer must also maintain
information about volume status.

D. 1 . 3

Directory IDs

The FSI has functions to support MAC style directory IDs. The interface is somewhat primitive and
does not appear to be fully implemented. The current implementation returns a UNIX pathname of
<root>/n for pathnames to MAC directories, where <root> is the UNIX pathname to the volume root
and n is the directory ID number. This would likely force the listed "folder" names to be the same as
their directory ID. While this may provide file storage it most likely would not be viewed as
acceptable. The FSI also does not enforce this name convention of directories it creates. I would assume
it would be left to the server to assign a directory ID to the FPCreateDir and pass this ID as the
directory name to FSl_mkdir. The original folder name would either be stored by the server in its own
database or lost. I would further assume that the server would have to convert the directory name to its
ID for return to the client on FPOpenDir. If the server stored the actual name it would need to convert
directory names on FPEnumerate.

NOTE
Certainly this mechanism needs to be changed. In the VMS environment, the file ID
provides a unique 24 bit number (32 with RVN) which could be used as the directory
ID. It is not clear whether direct access via this FID is provided.
A similar mechanism in the UNIX/OSF space needs to be investigated.

D.1.4

Namespace

The FSI has some knowledge of namespace, however, it is not implemented. The FSI could attempt to
"claim" a path in the client namespace and convert the name to UNIX. The FSI could also return
directory entries in the client namespace. The FSI passes all namespace issues to the underlying file
system. This may result in many duplicated functions. While it may be less efficient a more general
architecture would specify the native namespace as used by the FSI and require all FSLIB routines to
operate in this namespace, converting names as required. The FSI would then convert names to the
client namespace as required.

D.1.5

Streams

The FSI supports two streams per file, the primary stream (data stream) or Macintosh resource stream.
The implementation of streams is left to.the library. The FSI will specify the stream on file open calls.
The basic assumption is only one stream may be accessed per open file and the stream must be
specified at open time. This allows implementation of separate streams in separate files or both streams
in one file. If a file is to have a resource stream it must also have a primary stream. The primary
stream is always created when a file is created, regardless of the stream specified.
1

D. 1 . 6

Extended Attributes

The FSI implements support of OS/2 extended attributes. This support is provided at the FSI level, not
in the libraries. The library open function allows three streams, unlike the FSI open function. The FSI
level uses library read and write functions to access the data in the extended attribute stream and
April 20, 1992

Digital Confidential

100

PATHWORKS File System

interprets the data directly. The entire file containing the stream is locked for the duration of attribute
access.
Extended attributes have an ASCII name and non specified data value associated with them. They are
referenced by name and may be added, deleted or modified. Access to the attributes is provided thru two
parallel structures, one specifying the name of the attribute to return and the other containing the return
attribute (get functions) or attribute and value to add, modify or delete (set functions).
Attributes are stored in the stream as an array of attribute structures followed by the attribute name
followed by the attribute value. The structure contains a field which indicates the total size of the
structure plus name and value length. This size can be used to calculate the offset of the next attribute.
Deleted attributes are marked in the EA header and the space may be used to store a new attribute, if it
fits. If no slots are found the stream will be extended to hold the new attributes. Attributes are not
sorted. Deleted attributes are marked by a NULL name pointer. The header will hold 10 deleted attribute
pointers. The rest must be found by searching the attribute list.

NOTE
The support of extended attributes is in rough shape. The attribute stream is read into
a static buffer and specified attributes are copied to the return structure as needed. This
design relies on non-preemtive scheduling and single process access. A lock would be
required to synchronize extended attribute functions. There are file access calls which
use separate static buffers (one for the EA header and one for the data). These file read
functions can not cause a process switch. While the current LMU tasker may provide
for this it is not clear this is desired in a general 1/0 environment. If the tasker is
changed to allow process switch while read data is fetched from disk this code could
break and allow a second process to overwrite the EA header or data buffers.
Certainly the support of extended attributes needs to be moved to file system
libraries.
Extended attributes are stored in a file with the suffix ".r". It would appear this file
can be opened directly, however, directory enumerates specifically suppress listing the
files. It is not clear what would happen if a user created a file with the ".r" suffix.
The UFS library open function checks for a ".r" suffix and if present opens the file as
is. If it is not the filename is appended with ".r". This would result in
"FILENAME.EXT.R". While UNIX may allow this filename, VMS would not. I
would guess that if a user created a ".r" file, it would be suppressed on directory
enumerates.
The code references the support of extended attributes as EAHACK. It is possible this
support was added in a last minute fashion and will be reworked.

D. 1 . 7

FSI Routine Classification

The FSI routines can be grouped into 5 major classes, directory access functions, file access functions,
file attributes functions, path access functions and general support functions.
Directory access functions
FSI_chdir
FSl_diridfcn
FSI_diridini
FSI_getcwd
FSI_getdents
FSl_mkdir
FSl_rmdir
April 20, 1992

Digital Confidential

101

PATIIWORKS File System

File access functions
FSI_access
FSI_close
FSI_copyfile
FSI_create
FSI_delete
FSI_fsync
FSI_lock
FSI_lseek
FSI_open
FSI_purge
FSI_read
FSI_rename
FSI_sync
FSI_truncate
FSI_unlock
FSl_utime
FSI_unmap
FSI_write
File attributes functions
FSl_chmod
FSl_chown
FSI_getattr
FSI_geteas
FSI_getcmnt
FSI_filesize
FSl_setattr
FSl_setcmnt
FSI_seteas
Path functions
FSI_getpathid
FSI_fullpath
FSI_shortpath
FSl_treetop
General support functions
FSI_init
FSI_mapname
FSl_mpxclose
FSI_needfds
FSI_needinodes
FSI_setlognores
FSI_setnotifympx
FSl_stat
FSI_statvfs

D.2

PATH ID {FSl_PATHID)

Path IDs are structures which describe the path to a file. The path has attributes associated with it
which may be the parent directory attributes.
April 20, 1992

Digital Confidential

102

PATHWORKS File System

Many calls operate on a path ID which contains the following information:
Function pointers
This field contains a pointer to the function dispatch table for the file system which "owns" this
path.
Full path name
This field contains a string of fixed length to hold the full file name in the syntax of the server file
system.
Short path name
This field contains a pointer into the full path name buffer which points to the start of the path
which needs to be resolved, i.e. the point past the current default directory.
End treetop
This field contains a pointer into the full path name buffer which points to the start of the path
beyond the "tree top" (volume directory on the server file system). This field must be set by the
server application.
FSI flags
This field points to the FSI flags of the file system which "owns" this path. The flags include the
following information:
File system is real UNIX file system
Resource forks are supported
Extended attributes are supported
Case sensitive file names are supported
File system is mapped to another file system (alias)
Mask of FSI status elements supported
Mask of FSI attributes supported
Status
This field contains the FSI status structure. This structure contains the following information:
Mask of which elements are valid
UNIX statO function structure
File generation number
Data stream identifier (resource, data, attributes)
Parent INODE structure (this must assume that UNIX file
system is present)
Parent generation number
Count of entries in directory
Count of files in directory
Count of directories in entry
File attributes
Directory ID pointer
This field is a pointer to a cell which contains the current directory ID generation number to be
used with MAC variable ID format AFP calls.

D.2.1

File

April 20, 1992

(FSl_FID)
Digital Confidential

103

PATIIWORKS File System

Many calls operate on a file ID, a structure which contains the following information:
Function pointers
This field contains a pointer to the function dispatch table for the file system which "owns" this
path.
File status
This field contains the FSI status structure. This structure contains the following information:
Mask of which elements are valid
UNIX statO function structure
File generation number
Data stream identifier (resource, data, attributes)
Parent INODE structure (this must assume that UNIX file
system is present)
Parent generation number
Count of entries in directory
Count of files in directory
Count of directories in entry
File attributes
File descriptor
This field contains the file system descriptor (UNIX). The descriptor may be marked as closed if
multiplexing has occurred.
File descriptor information (low, high, closed)
This field indicates which type of file descriptor this file is associated with.
Data stream identifier
This field indicates which data stream is being accessed, primary stream (data stream), resources
stream or attributes stream.
Current file offset
The current file offset is preserved in case the file is closed due to file descriptor multiplexing. The
file will be reopened and positioned here when the file is next accessed.
Open file reference count
This field contains the count of file IDs which .point to this file.
Multiplex control count
This field contains the count of how many times the file is currently ineligible for multiplexing.
The file may be closed if the count is zero.
Open flags
The file open mode must be preserved in case the file descriptor is closed due to multiplexing. The
file will be reopened using this mode when it is next referenced.
File flags
Locking flag and file written flag.
April 20, 1992
Digital Confidential

104

PATHWORKS File System

File mapping information
[Need to fmd out how this works.]
FSI flags
This field points to the FSI flags of the file system which "owns" this path. The flags include the
following information:
File system is real UNIX file system
Resource forks are supported
Extended attributes are supported
Case sensitive file names are supported
File system is mapped to another file system (alias)
Mask of FSI status elements supported
Mask of FSI attributes supported
End tree top pointer
This field contains a pointer into the full path name buffer which points to the start of the path
beyond the "tree top" (volume directory on the server file system). This field must be set by the
server application.
Full path name
This field contains a string of fixed length to hold the full file name in the syntax of the server file
system.

D.3

ROUTINE SUMMARY

D.3.1

FSl_access

Description:
This function will determine if a file may be accessed according to the mode specified.

Synopsis:
FSl_Access (FSI_PATHID *pathid, int perms)

Algorithm:
BEGIN
Check perms argument for validity
Dispatch FSLIB_ACCESS (pathid, perms)
END

D.3.2

FSl_chdir

Description:
This function will change the working directory. Modifies global variables FSI_curdir, FSI_curdirlen.

Synopsis:
April 20, 1992

Digital Confidential

105

PATIIWORKS File System

FSI_chdir (FSI_PATHID *pathid)

Algorithm:
BEGIN
IF Current directory <> pathid THEN BEGIN
Dispatch FSLIB_chdir (pathid)
Copy fullpath to FSl_curdir
END
END

D.3.3

FSLfchdir

Description:
This function will change the working directory. Modifies global variables FSI_curdir, FSl_curdirlen.

Synopsis:
FSl_fchdir (FSI_FID *fp)

Algorithm:
BEGIN
IF Current directory <> fp THEN BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_fchdir (fp)
Copy fullpath to FSI_curdir
END
END

D.3.4

FSLchmod

Description:
This routine will change the access permission to the specified file.

Synopsis:
FSI_chmod (FSl_PATHID *pathid, mode)

Algorithm:
BEGIN
Dispatch FSLIB_chmod (pathid, mode)
END

D.3.5

FSLfchmod

Description:
This routine will change the access permission to the specified file.
April 20, 1992

Digital Confidential

106

PATHWORKS File System

Synopsis:
FSI_fchmod (FSI_FID *fp, mode)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_chmod (fp, mode)
END

D.3.6

FSLchown

Description:
This routine will change the owner of the specified file

Synopsis:
FSI_chown (FSI_PATHID *pathid, user_id, group_id)

Algorithm:
BEGIN
Dispatch FSLIB_chown (pathid, user_id, group_id)
END

D.3. 7

FSLfchown

Description:
This routine will change the owner of the specified file

Synopsis:
FSl_fchown (FSLPATHID *pathid, user_id, group_id)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_chown (pathid, user_id, group_id)
END

D.3.8

FSLclose

Description:
This function will close a file.

NOTE

April 20, 1992

Digital Confidential

107

PATHWORKS File System

The data fork and extended attributes fork are currently implemented in separate files.
These files will not have equivalent modification times and may therefore not be
backed up as a pair.

Synopsis:
FSI_close (FSl_FID *fp)

Algorithm:
BEGIN
IF written THEN Set volume modify time
IF last reference THEN BEGIN
DEQUEUEfp
Dispatch FSUB_close
END
END

D.3.9

FSLcopyfile

Description:
This function will copy a file. The resource fork is discarded (truncated) if the destination file system
does not support it. The extended attributes fork is also discarded if the destination file system does not
support it.

Synopsis:
FSI_copyfile (FSI_PATIIID *src, FSI_PATIIID *dest, dostream, action)

Algorithm:
BEGIN
IF src does not exist THEN error
IF read only fs OR no copy THEN error
IF dostream resource AND <lest not supported THEN error
IF dostream attributes AND dest not supported THEN error
Open src primary stream
IF dest does not exist THEN BEGIN
Create <lest primary stream
Copy file attributes from src
END
ELSE Open dest primary stream
FOR all streams DO BEGIN
Dispatch FSI_lock (src)
Dispatch FSl_lock (dest)
Dispatch FSUB_ffilesize (src)
FOR all bytes DO BEGIN
Dispatch FSUB_read (src)
Dispatch FSUB_write (dest)
END
Dispatch FSI_unlock (src)
Dispatch FSI_unlock (<lest)
Dispatch FSI_close (src)
Dispatch FSl_close (dest)
Open next src stream
Open next <lest stream
April 20, 1992

Digital Confidential

108

PATHWORKS File System

END
IF FSLIB_copyfile THEN Dispatch FSUB_copyfile
IF MAC application THEN update desktop
Set volume modify time

END

D. 3. 1 0 FSLcreate
Description:
Create a new file or truncate an existing file.

NOTE
There is an FSI_FID sharing mechanism which will return a pointer to a previously
allocated FID if the file is already open. Note that FSI_create will truncate this file
without explicit lock checking or synchronization with other readers and or writers.
Mandatory locking appears to be defeated in this case.
FSLIB_open allocates the FSI_FID. It also initializes the following fields of the FSl_FID:

fullpath (copied from pathid)
fd (returned by UNIX)
fdinfo (fd low or high)
status (copied from passed statbufp)
flags (mandlock set from st_mode)
mapaddr (allocated)
maplen (st_size)
FSI_create initializes the following fields of the FSl_FID following a successful call to FSLIB_open
(actually done in local routine opencreate):
refcnt (set to 1)
stream (FSl_PRIMARY)
oflag (O_RDWR)
funcptrs (copied from pathid)
fsflags (copied from pathid)
endtreetop (copied from pathid)
nompx (if file not regular or directory)

Synopsis:
FSI_create (FSl_PATHID *pathid, mode, uid, gid, FSI_CREATE_TYPE type, FSI_FID **fp)

Algorithm:
BEGIN
IF type is FSI_MAKETMP THEN BEGIN
[Need to supply description here]
END
ELSE BEGIN
IF path does not exist THEN get parent attributes
ELSE get file attributes
IF read only THEN error
IF type is FSI_MAKENEW and file exists THEN error
IF file already open THEN BEGIN
Dispatch FSLIB_truncate
April 20, 1992

Digital Confidential

109

PATHWORKS File System

Use existing FID
END
ELSE BEGIN
Dispatch FSLIB_open (pathid, &pathid->status, O_RDWR I O_CREAT I O_TRUNC, mode, FSI_PRIMARY, FSl_NOMAP, fp)
IF no more file space THEN start multiplex close
IF too many open files THEN close any files
IF access denied OR image busy OR readonly fs OR no memory OR no space OR no more processes TIIBN error
Initialize the remainder of the FID
Add it to the FID list
IF file does not exist THEN BEGIN
IF FSI_PRIMARY stream THEN Dispatch FSLIB_fchown
Dispatch FSLIB_fstat
IF FSl_PRIMARY THEN pathid->status = fp->status;
END
END

END
END

D. 3. 11 FSLdelete
Description:
Delete a file.

Synopsis:
FSI_delete (FSI_PATHID *pathid)

Algorithm:
BEGIN
IF file does not exist THEN error
IF readonly OR no delete THEN error
IF no_purge THEN error
Dispatch FSLIB_purge (pathid)

IF MAC application THEN update desktop
Set volume modify time

END

D.3.12 FSl_diridinit
Description:
This routine will initialize the handling of directory IDs.

Synopsis:
FSI_diridinit (dodirids, diridptr)

Algorithm:
April 20, 1992

Digital Confidential

110

PATHWORKS File System

BEGIN
FOR any non mapped file system DO
Dispatch FSLIB_diridinit (dodirids, diridptr)
END

D.3.13 FSLdiridfunc
Description:
This routine handles directory ID functions, FSI_DIRID_GET, FSl_DIRID_OPEN,
FSI_DIRID_CLOSE. The DIRID_OPEN call indicates a volume has been mounted and a new set of
directory IDs are to be used. DIRID_GET will convert a directory ID and UNIX pathname (representing
the volume root) to a full unix pathname to the directory. DIRID_CLOSE indicates the volume has
been closed.

Synopsis:
FSI_diridfunc (cmd, startpath, dirid, ptr, pathbuf, buflen)

Algorithm:
BEGIN
Verify startpath is a valid UNIX directory
Dispatch FSLIB_diridfunc
END

D.3.14 FSLffilesize
Description:
This function will return the number of bytes stored in the file.

Synopsis:
FSI_ffilesize (FSl_FID *fp, size)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_ffilesize (fp, size)
END

D.3.15 FSLfsync
Description:
This routine will flush any written buffers associated with the file.

Synopsis:
FSI_fsync (FSl_FID *fp)

Algorithm:
April 20, 1992

Digital Confidential

111

PATIIWORKS File System

BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_fsync (fp, size)

END

D.3.16 FSLfullpath
Description:
This function will return the full UNIX pathname of the file

Synopsis:
FSI_fullpath (FSl_FID *fp, pathbuf, pathlen)

Algorithm:
BEGIN
Copy fullpath from fp to pathbuf

END

D. 3. 1 7 FSLgetattr
Description:
This function will return the requested file attributes and update the FSI_PATIIlD structure. Attributes
which may be requested are as follows:
FSI_AT_DIRID-Directory ID
FSI_AT_BTIME - Backup time
FSl_AT_CREATE- Creation time
FSl_AT_F_INFO - Finder info
FSl_AT_ARCHIVE - File is archived
FSl_AT_HIDDEN - File is archived
FSI_AT_SYSTEM - File is a system file
FSI_AT_NOREN - File can not be renamed (can be copied)
FSl_AT_NODEL - File can not be deleted
FSI_AT_NOCOPY - File can not be copied (can be renamed)
FSl_AT_READONLY - File is read only
FSl_AT_NOPURGE - File is deleted on delete
FSI_AT_MACAPPL- File is Macintosh application
FSl_AT_MULTIUSER - File can be opened simultaneously
FSl_AT_EXECONLY - File is execute only
FSI_AT_INDEXED - Netware index file
FSI_AT_TRANS - Netware transation tracking
FSl_AT_RDAUDIT- Netware transaction tracking
FSI_AT_WRAUDIT - Netware transaction tracking

Synopsis:
FSI_getattr (FSl_PATHID *pathid, mask, FSl_A'ITR *attrp)

Algorithm:
BEGIN
Dispatch FSLIB_getattr (pathid, mask, attrp)
Copy attrp to pathid
April 20, 1992

Digital Confidential

112

PATHWORKS File System

END

D.3.18 FSLfgetattr
Description:
This routine will return the requested attributes and update the FSl_FID structure. Attributes and masks
are the same as for FSI_getattr.

Synopsis:
FSI_fgetattr (FSl_FID *fp, mask, FSI_ATTR *attrp)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_fgetattr (fp, mask, attrp)
Copy attrp to fp

END

D.3.19 FSLgetcomment
Description:
This function will return a comment associated with a file. This is presumably present to support the
MAC desktop database.

Synopsis:
FSI_getcomment (FSI_PATHID *pathid, commentbuf, commentlen)

Algorithm:
BEGIN
Dispatch FSLIB_getcomment (pathid, commentbuf, commentlen)

END

D.3.20 FSLgetcmd
Description:
This function will return the current working directory.

Synopsis:
FSI_getcwd (cwdptr)

Algorithm:
BEGIN
Set cwdptr to FSI_curdir

END

D.3.21 FSLgetdents
April 20, 1992

Digital Confidential

113

PATHWORKS File System

Description:
This function will return directoi:y enti:y names in a specified format. The directory structure contains a
longword ID, length word and text buffer. The name is returned in the namespace as specified below.
FSl_UNIXNAME - Use UNIX format
FSI_DOSNAME - Use DOS format
FSl_OS2NAME - Use OS/2 format
FSI_MACNAME - Use Macintosh format
The NBYTES parameter specifies how large the direntp buffer is and BYTESREAD specifies how
much data was actually written to the buffer. OFFSET specifies where to start the read.
The dirent structures is defined as follows:
unsigned long d_ino; /*Unique identifier for file*/
unsigned short d_reclen; /* Size of this record *I
unsigned short d_namlen; /* Length of filename */
char d_name[MAXNAMLEN+ 1]; /* Buffer for filename*/
Multiple entries may be packed in the buffer and may be found by using the buffer offset plus the
d_reclen parameter.

Synopsis:
FSI_getdents (FSl_FID *fp, struct dirent *direntp, nbytes, offset, namespace, bytesread)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_getdents (fp, direntp, nbytes, offset, namespace, bytesread)
END

D.3.22 FSLgetextattr
Description:
This function will return the extended attributes specified in the return buffer provided. The function
will return the size of the return attributes in case the buffer is not large enough. It is the caller's
responsibility to allocate a buffer large enough and call the function again. The function will fail if the
buffer is not large enough.

Synopsis:
FSI_getextattr (FSl_PATHID *pathid, FSI_EAOPS *eaopsp)

Algorithm:
BEGIN
IF file does not exist THEN error
IF extended attributes not supported by fs THEN error
Dispatch FSLIB _stat for FSI_EXTA'ITRS stream
Open or create the stream
Dispatch FSI_lock for whole file containing stream
Dispatch FSLIB_ffilesize
IF no stream THEN BEGIN
IF return buffer large enough THENApril 20, 1992

Digital Confidential

114

PATHWORKS File System

set return buffer to indicate no attributes
Set size of return buffer

END
ELSE BEGIN
Dispatch FSI_read for EA header
Dispatch FSI_read for EA data
Scan all attributes and calculate stream size
Store stream size in return buffer
IF no attributes requested THEN done
FOR all requested attributes DO BEGIN
If requested attribute in list THEN append attribute and value to return buffer
ELSE append NULL attribute value to return buffer
Set size of return buffer
END
END
Dispatch FSl_unlock
Dispatch FSl_close
END

D. 3. 2 3 FSl_getpathid
Description:
This function will initialize an FSI_PATHID structure used for subsequent access to the path. The
function will determine if the path exists and which file system it belongs to. The function uses a
combination of UNIX stat() calls and FSLIB_claim calls to resolve the path. There is a provision for
handling path translation from the client namespace but it is not yet implemented.
The function may return one of three return codes, FSI_EXISTS (path exists and pathid contains
information about the path), FSI_NOEXIST (path does not exist but parent does and pathid contains
information about the parent) or FSI_FAILURE (neither path nor parent exists and pathid does not
contain any information).
The UNIX stat() function will succeed if the path exists in one of the UNIX file systems. If the path
represents a "pseudo" file system, (i.e. a file system not mounted) then stat() may fail even though the
FSI can access the path. In this case, FSLIB_claim would be responsible for identifying the path.

NOTE
The FSI implementation is not complete within the LMU server. There are server
functions which directly call UNIX 1/0 functions on resolved path names ( chksvr4()
called by chkuxpath() called by smbcreate() uses open() to check write access to a
directory). This would seem to preclude support of "pseudo" file systems as generic
entities. Pseudo file systems may find application in specific sections of the LMU
server, for example, the implementation of the desktop database may use a pseudo
file system.
The FSLIB_claim function may return one of 4 return codes, FSI_EXISTS (path exists and is in the
file system supported by this library), FSI_NOEXIST (path does not exist but the parent does and is in
the file system supported by this library), FSI_UNCLAIMED_EXISTS (path exists in UNIX file
system but is not supported by this library) or FSI_UNCLAIMED_NOEXIST (path does not exist but
parent exists in the UNIX file system but is not supported by this library.

NOTE
The algorithm used by FSI_getpathid seems to resort to "forced claims" as the
algorithm progresses. If a library returns an UNCLAIMED status it is "forced" to
April 20, 1992

Digital Confidential

115

PATHWORKS File System

accept the path if no one else did. It is not clear what the benefit of this "last chance"
mechanism could be. Either the path is supported or it is not.

Synopsis:
FSI_getpathid (path, startcase, FSl_PATIDD *pathid)

Algorithm:
BEGIN
Clear pathid structure
IF relative path THEN append to working directory
Copy resolved path to fullpath
Setup shortpath
FOR FSI_PSEUDO_FS file systems DO BEGIN
Dispatch FSLIB_claim
IF claimed THEN done FSl_EXISTS or FSI_NOEXIST
END
UNIX stat() the path

IF path exists THEN BEGIN
IF NOT FILLPATH(path pathid) THEN error
IF UNIX namespace THEN done FSl_EXISTS
IF NOT case sensitive creates supported THEN BEGIN
Dispatch FSLIB_claim
IF claimed AND file exists THEN done FSI_EXISTS
ELSE error
END

ELSE done FSl_EXISTS
END

Get parent path
UNIX stat() the path

IF path exists THEN BEGIN
IF path is not a directory THEN error
IF NOT FILLPATH(parent pathid) THEN error
IF UNIX namespace THEN done
Dispatch FSLIB_claim
IF exists THEN BEGIN
IF NOT FILLPATH(path pathid) THEN error
done FSI_EXISTS
END

ELSE done FSl_NOEXIST
END
IF UNIX namespace THEN error

FOR ALL file systems DO BEGIN
Dispatch FSLIB_claim
IF file exists AND unclaimed THEN BEGIN
IF NOT FILLPATH(path pathid) THEN error
done FSI_EXISTS
END

IF file does not exist AND unclaimed THEN BEGIN
IF NOT FILLPATH(parent pathid) THEN error
done FSI_NOEXIST
END
END

IF not claimed THEN error
END

D.3.24 FSLlock
April 20, 1992

Digital Confidential

116

PATIIWORKS File System

Description:
This function sets a byte range lock on a file. The file may be locked from the start of the file or the
end of the file. The offset is the distance from the set point. The length argument specifies how many
bytes to lock (NULL implies the remainder of the file). The routine will either fail if the lock is set or
it will block until the lock is released (the block is the responsibility of the FSLIB). The offset from
the start of the file to the lock point is returned, if requested.

NOTE
There appears to be a bug in this routine in that the start argument is not updated
unless the file is actually locked, i.e. if the file is mapped the start argument is not
guaranteed to be correct.

Synopsis:
FSl_lock (FSl_FID *fp, type, offset, whence, length, dowait, start)

Algorithm:
BEGIN
Check whence argument (SEEK_SET or SEEK_END)
Check lock type (F_RDLCK or F _WRLCK)
IF FSI_locksmatter AND file not memory mapped TIIEN BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
IF offset is over UNIX limit TIIEN done (YIKES!!!)
IF end of lock is over UNIX limit THEN set end of lock to UNIX limit
Dispatch FSLIB_lock (fp, type, offset, whence, length, dowait, start)
IF NFS not running TIIEN ignore NFS errors
ELSE IF error THEN error
Disallow multiplex closing this file (increment reason)
END
ELSE set start argument to start offset of lock
END

D.3.25 FSl_lseek
Description:
This function will set the current file position to that specified.

NOTE
This routine must be present for compatibility only as file position is not guaranteed
across any FSI calls.

Synopsis:
FSI_lseek (FSl_FID *fp, offset, whence)

Algorithm:
BEGIN
Check whence argument (SEEK_SET or SEEK_END)
Check offset argument
Dispatch FSLIB_lseek (fp, offset, whence)
April 20, 1992

Digital Confidential

117

PATHWORKS File System

END

D.3.26 FSLmapname
Description:
This function will convert the last component of the path to the namespace requested.

Synopsis:
FSl_mapname (FSl_PATHID *pathid, namespace, namebuf, buflen)

Algorithm:
BEGIN
Dispatch FSLIB_mapname (pathid, namespace, namebuf, buflen)

END

D.3.27 FSLfmapname
Description:
This function will convert the last component of the path to the namespace requested.

NOTE
This function DOES NOT reopen a multiplex closed file. This may be an oversight, especially if the
file system library expects to store converted names in the file itself.

Synopsis:
FSI_fmapname (FSl_FID *fp, namespace, namebuf, buflen)

Algorithm:
BEGIN
Dispatch FSLIB_fmapname (fp, namespace, namebuf, buflen)

END

D.3.28 FSl_mkdir
Description:
This function will create a directory.

NOTE
The directory ID parameter is not supported in UPS and will be forced to 0.

Synopsis:
FSl_mkdir (FSl_PATHID *pathid, mode, uid, gid, dirid)

Algorithm:
BEGIN
April 20, 1992

Digital Confidential

118

PATHWORKS File System

IF directory exists THEN error
IF readonly THEN error
Dispatch FSUB_mkdir(pathid, mode, dirid)
Dispatch FSUB_chown(pathid, uid, gid)
Set volume modify time
END

D.3.29 FSLmpxclose
Description:
This function will multiplex close the specified file. It is presumed to be present to allow servers to
determine the best candidates for multiplex closing without resorting to FSI forced multiplexing.

Synopsis:
FSI_mpxclose (FSI_FID *fp)

Algorithm:
BEGIN
IF NOT fp multiplex closed THEN Dispatch FSUB_mpxclose (fp)
END

D.3.30 FSLneedfds
Description:
This function specifies a number of UNIX file descriptors which must be available. If this number of
file descriptors is not available then the function will multiplex close files until it is.

Synopsis:
FSI_needfds (count)

Algorithm:
BEGIN
IF dupQ a file descriptor THEN BEGIN
closeO the new file descriptor
fcntl(F_DUPFD) as many file descriptors as needed
close() them all
IF not enough THEN multiplex close the balance
END

END

D.3.31 FSLneedinodes
Description:
This function will multiplex close a number of files.

NOTE
This routine is primarily for internal FSI use.

Synopsis:
April 20, 1992

Digital Confidential

119

PATHWORKS File System

FSI_needinodes(timescalled, FSLIB_ptrs)

Algorithm:
BEGIN
Get the number of files to close based on timescalled
FOR all open multiplexable fp DO BEGIN
Dispatch FSLIB_mpxclose (fp)
IF notify on mpxclose THEN Dispatch FSI_notifympx

END
END

D.3.32 FSLopen
Description:
This function will open a data stream for read or write access.

Synopsis:
FSI_open (FSI_PATHID *pathid, statbufp, oflag, stream, domap, fp)

Algorithm:
BEGIN
IF NOT primary stream OR resource stream THEN error
IF resource stream AND resource not supported THEN error
IF primary stream AND NOT open read/write OR readonly OR writeonly THEN error
IF file does not exist TIIEN error
IF read only AND open for write THEN error
IF NOT primary stream THEN BEGIN
Dispatch FSLIB_stat
Get UID, GID and protection mode

END
ELSE use file default UID, GID and protection mode
IF directory THEN open for read only
IF file already open THEN BEGIN
Dispatch FSLIB_truncate
Use existing FID

END
ELSE BEGIN
Dispatch FSLIB_open
IF no more file space TIIEN start multiplex close
IF too many open files TIIEN close any files
IF access denied OR image busy OR readonly file system OR no memory OR no disk space OR no more processes THEN error
Initialize the remainder of the FID
Add it to the FID list
IF file does not exist THEN BEGIN
IF FSI_PRIMARY stream TIIEN Dispatch FSLIB_fchown (fp, uid, gid)
Dispatch FSLIB_fstat (fp, FSI_ST_USTAT, &fp->status)
IF FSl_PRIMARY THEN pathid->status =fp->status;

END
END
END
April 20, 1992

Digital Confidential

120

PATHWORKS File System

D.3.33 FSLpurge
Description:
This function will delete a file.

Synopsis:
FSI_purge (FSl_PATHID *pathid)

Algorithm:
BEGIN
IF file does not exist THEN error
IF read only fs OR no delete THEN error
Dispatch FSLIB_purge
IF MAC application THEN update desktop
Set volume modify time
END

D.3.34 FSLread
Description:
This function will read data from the file.

Synopsis:
FSI_read (FSI_FID *fp, buffer, nbytes, offset, bytesread)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
IF NOT mandlock AND NOT mapped THEN lock record
Dispatch FSLIB_read
IF record locked THEN unlock record
END

D.3.35 FSLrename
Description:
This function will rename a file.

Synopsis:
FSI_rename (FSl_PATHID *old, FSl_PATHID *new)

Algorithm:
BEGIN
IF both paths not in same fs THEN error
IF old file does not exist THEN error
IF read only fs OR no delete THEN error
April 20, 1992

Digital Confidential

121

PATHWORKS File System

Dispatch FSUB_rename
IF MAC application THEN update desktop
Set volume modify time
END

D.3.36 FSl_rmdir
Description:
This function will delete a directory.

NOTE
This function makes a call to FSI_checkvolume to determine if the directory can be
deleted on a MAC volume. There is no information on this function call.

Synopsis:
FSl_rmdir (FSI_PATHID *pathid)

Algorithm:
BEGIN
IF read only fs OR no delete THEN error
IF current directory THEN set current to root
Dispatch FSUB_rmdir
Set volume modify time
END

D.3.37 FSLsetattr
Description:
This function will set the file's attributes. These attributes are those which the FSI operates on.

Synopsis:
FSI_setattr (FSI_PATHID *pathid, attrip)

Algorithm:
BEGIN
IF attributes not supported by fs THEN error
Dispatch FSLIB_setattr
Set volume modify time
END

D.3.38 FSLfsetattr
Description:
This function will set the file's attributes. These attributes are those which the FSI operates on.

Synopsis:
FSI_fsetattr (FSI_FID *fp, attrip)
April 20, 1992

Digital Confidential

122

PATHWORKS File System

Algorithm:
BEGIN
IF attributes not supported by fs THEN error
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_setattr
Set volume modify time

END

D. 3. 3 9 FSLsetcomment
Description:
This function will associate a string of up to 199 characters with a file name.

Synopsis:
FSI_setcomment (FSl_PATHID *pathid, string)

Algorithm:
BEGIN
IF comment too long THEN truncate to 199
Dispatch FSLIB_setcomment
Set volume modification time

END

D. 3. 40 FSLsetextattr
Description:
This function will add, delete or modify extended attributes associated with a file. The GEA list
member of the EA OPS structure is ignored for this function. The FEA list contains a list of attributes
and their values. If the attribute does not exist it will be added. If the attribute exists it will be modified
unless the value pointer is NULL, in which case the attribute will be deleted. Attributes not specified
in the FEA list will remain unchanged.

Synopsis:
FSI_setextattr (FSl_PATHID *pathid, FSl_EAOPS *eaopsp)

Algorithm:
BEGIN
IF file does not exist THEN error
IF extended attributes not supported by fs THEN error
IF no FEA list THEN done
Dispatch FSLIB_stat for FSI_EXTATTRS stream
Open or create the stream
Dispatch FSI_lock for whole file containing stream
Dispatch FSLIB_ffilesize
IF no stream THEN BEGIN
Write out attributes in FEA list
Done

END
ELSE BEGIN
April 20, 1992

Digital Confidential

123

PATIIWORKS File System

Dispatch FSI_read for EA header
Dispatch FSI_read for EA data
FOR all FEA in list DO BEGIN
IF attribute found THEN BEGIN
IF value fits THEN modify existing entry
ELSE BEGIN
Delete attribute
IF empty space THEN add attribute
ELSE increase size of stream buffer
END
END
ELSE BEGIN
IF empty space THEN add attribute
ELSE increase size of stream buffer
END

END
END
Dispatch FSI_write for EA data
Get clean stream buffer for remaining FEA
FOR all FEA which did not fit DO add attribute
Dispatch FSI_write for EA data
Dispatch FSI_write for EA header
Dispatch FSl_unlock
Dispatch FSI_close

END

D.3.41 FSLsetlognores
Description:
This function specifies a routine for the FSI to call when resources have been exhausted.

Synopsis:
FSl_setlognores (routine)

Algorithm:
BEGIN
Set FSI_LogNoResource to routine

END

D.3.42 FSLsetnotifympx
Description:
This function specifies a routine for the FSI to call when multiplexing begins.

Synopsis:
FSI_setnotifympx (routine)

Algorithm:
BEGIN
Set FSI_notifympx to routine
END
April 20, 1992

Digital Confidential

124

PATHWORKS File System

D.3.43 FSLshortpath
Description:
This function will set the short path element of the FSl_PATID structure to the point past the current
directory, if it is part of the full path. If not the short path is set to the full path.

Synopsis:
FSI_shortpath (FSl_PATHID *pathid)

Algorithm:
BEGIN
IF current directory in fullpath THEN set short path past current directory
ELSE set short path to full path
END

D.3.44 FSLstat
Description:
This function will return file statistics in the UNIX stat format.

Synopsis:
FSI_stat (FSl_PATHID *pathid, stream, mask, statbufp)

Algorithm:
BEGIN
IF mask not supported by fs THEN error
IF stream NOT (FSl_PRIMARY OR FSI_RESOURCE) THEN error
IF stream is FSI_RESOURCE AND not supported by fs THEN error
Dispatch FSLIB_stat
IF stream is FSI_PRIMARY THEN copy statbufp to pathid status
END

D.3.45 FSl_fstat
Description:
This function will return file statistics in the UNIX stat format.

Synopsis:
FSI_fstat (FSI_FID *fp, stream, mask, statbufp)

Algorithm:
BEGIN
IF mask not supported by fs THEN error
IF stream NOT (FSI_PRIMARY OR FSI_RESOURCE) THEN error
IF stream is FSI_RESOURCE AND not supported by fs THEN error
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
April 20, 1992

Digital Confidential

125

PAIBWORKS File System

Dispatch FSLIB_stat
IF stream is FSl_PRIMARY THEN copy statbufp to fp status

END

D.3.46 FSLstatvfs
Description:
This function will return file information in a UNIX statvfs structure.

Synopsis:
FSI_statvfs (FSl_PATIDD *pathid, statvfsbufp)

Algorithm:
BEGIN
Dispatch FSLIB_statvfs

END

D.3.47 FSLfstatvfs
Description:
This function will return file information in a UNIX statvfs structure.

Synopsis:
FSI_fstatvfs (FSl_FID *fp, statvfsbufp)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_fstatvfs

END

D.3.48 FSLsync
Description:
This function will flush all file system information from memory to disk.

Synopsis:
FSI_sync ()

Algorithm:
BEGIN
FOR all non mapped fs DO Dispatch FSLIB_sync

END

D. 3 .49 FSLftruncate
Description:
April 20, 1992

Digital Confidential

126

PATHWORKS File System

This function will truncate a file.

Synopsis:
FSI_ftruncate (FSl_FID *fp, offset)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
Dispatch FSLIB_ftruncate
END

D.3.50 FSLtretop
Description:
This function sets the treetop pointer in the pathid structure to the point past the "root directory" for a
share point or mounted volume.

Synopsis:
FSI_treetop (FSl_PATHID *pathid, treetop)

Algorithm:
BEGIN
IF treetop in full path THEN set treetop
ELSE error
END

D.3.51 FSLunlock
Description:
This function will unlock a range of bytes in the file.

NOTE
The function will multiplex open a file and then try to release a lock. This should be
guaranteed to fail as UNIX releases locks when a file is closed. Perhaps it is best to
either leave the file closed and return success (the lock was actually released) or
reopen the file and return success without unlocking anything.

Synopsis:
FSl_unlock (FSl_FID *fp, offset, whence, length)

Algorithm:
BEGIN
IF whence NOT (SEEK_SET OR SEEK_END) THEN error
IF FSI_locksmatter AND file not memory mapped THEN BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
IF offset is over UNIX limit THEN done (YIKES!!!)
IF end of lock is over UNIX limit THEN April 20, 1992

Digital Confidential

127

PATHWORKS File System

set end of lock to UNIX limit
Dispatch FSLIB_unlock
Allow multiplex closing this file (decrement reason)
END
END

D.3.52 FSLunmap
Description:
This function will clean up a memory mapped file.

Synopsis:
FSl_unmap (FSI_FID *fp)

Algorithm:
BEGIN
Dispatch FSLIB_unmap
END

D.3.53 FSLutime
Description:
This function will set the modification time of a file.

Synopsis:
FSl_utime (FSI_PATHID *pathid, timebufp)

Algorithm:
BEGIN
Dispatch FSLIB_utime
END

D.3.54 FSLfutime
Description:
This function will set the modification time of a file.

Synopsis:
FSl_futime (FSl_FID *fp, timebufp)

Algorithm:
BEGIN
Convert fp to pathid
Dispatch FSLIB_utime
END

April 20, 1992

Digital Confidential

128

PATHWORKS File System

D.3.55 FSl_write
Description:
This function will write bytes to a file.

Synopsis:
FSI_write (FSI_FID *fp, buffer, nbytes, offset, byteswritten)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
IF NOT mandlock AND NOT mapped THEN lock record
Dispatch FSLIB_write
Set dirty flag
IF record locked TIIEN unlock record
END

April 20, 1992

Digital Confidential

129

PATHWORKS File System

Appendix E - RMS Extent for Macintosh file format
The Macintosh file system provides two data contexts per file rather than the usual single context.
This concept makes it difficult to represent a Macintosh file in a file system which supports only
single contexts. VMS Files 11 is such a file system.
There appear to be two approaches to this problem. The fll'St represents the Macintosh file as two
separate files. It is the responsibility of the software which provides access to the Macintosh file to
associate the two separate files. This approach has a number of advantages, most noteworthy is the
ability of the native file system to access either of the Macintosh contexts directly. However, there is a
serious disadvantage in that the two separate files may be modified, moved or deleted such that the
association is no longer valid. The second approach represents both data contexts in the same file. This
approach solves the asociation of data contexts, however, Files 11 can not access either data context
directly. It is necessary to have a translator between the native file system and the user such that the
appropriate data context may be accessed. RMS provides such a mechanism in what is called an RMS
extent. The capabilities of the extent are somewhat limited but do provide the basics for the type of
translation necessary to access each data context. The only caveat is that the user MUST use RMS to
access the file. If not, the internal file format is visible.
This paper describes a trial development of an RMS extent which provides access to the Macintosh
DATA fork (one of the data contexts in the Macintosh file).

E. 1

File

Format

The trial development file format borrows from the mapping concepts of Files 11 in that there is a set
of retrieval pointers which map the virtual blocks of each data context to virtual blocks within the file.
This mapping ·is exactly analogous to the virtual block to logical block mapping provided by Files 11.
The file consists of a header followed by data blocks or mapping blocks. To limit the overhead the first
set of mapping pointers is contained in the header. As a further simplification all data blocks are
aligned on a block boundary which provides for a simple revectoring of virtual blocks within the data
context (alias data stream) to the virtual blocks within the file.
Data blocks are allocated as needed and mapped to one of two streams, the DATA stream or the
RESOURCE stream. Each stream has its own set of mapping pointers and the file is limited to two
streams for the purpose of this trial development. The extensions to multiple streams are
straightforward, however, the file format assumes a fixed number of streams.
Mapping blocks are allocated as the·streams become fragmented and there is no longer sufficient space
in the file header to map blocks. The format of the mapping blocks is identical to that of the mapping
blocks in the header. This concept is not implemented in the trial development. The streams may not
be arbitrarily fragmented. The implementation chooses 16 mapping pointers in the header block
(completely arbitrary choice, although the upper limit would be about 60 per stream). This limits the
fragmentation to 16 individual segments. The tests performed were on contiguous streams mapped by a
single pointer.

E. 1 . 1

File Semantics

RMS provides a File Semantic feature which identifies the internal structure of a file which requires an
RMS extent for access. RMS scans a file semantic tag structure to locate the routines which will
provide access to the file. This tag structure is loaded at system startup time by the initialization
routines of the extent image.
The trial development uses the file sematic tag "MACFILE". This tag is represented as the ASCII
translation of "MACFILE" in the RMS stored semantics. When RMS finds a file with this tag, it will
dispatch the routines specified by the extent image.
April 20, 1992

Digital Confidential

130

PATIIWORKS File System

RMS will bypass the routines if the user supplies an access sematics tag which matches the stored
semantics. It is assumed that the caller want to directly access the internal file format in this case. This
access mode is not currently used by would be useful to a utility which could modify the Macintosh
file internals (for building such a file directly from the host system for example).

E.1.2

Header

The header consists of three sections; allocation, stream descriptors and mapping blocks. The allocation
information is simply the next virtual block for allocation (although this information could be obtained
from internal RMS structures). The stream descriptors consist of three longwords; the end of stream
VBN, the end of stream byte within the VBN and the offset to the first set of mapping pointers. The
mapping pointers are one logword each and consist of four types; NULL, MAP, FREE and OFFSET.

E.1.2 .1 Allocation
The allocation section simply consists of the next virtual block to be allocated. This section must be
expanded to include allocation data for the mapping blocks

E .1.2 .2 Stream Descriptors
There are currently two stream descriptors; one for the DATA fork and one for the RESOURCE fork.
Each descriptor consists of three longwords to contain the end of stream VBN, the end of stream byte
and the offset to the mapping pointers. If the number of streams per file is to be increased new
descriptors would need to be added.

E .1.2 .3 Mapping Pointers
The mapping pointers consist of one longword each and map streams, free blocks or mapping blocks.
The pointer format is variable based on a two bit field in the upper two bits of the longword. Currently
VBNs are limited to 16 bits which sets the upper limit to 32MByte file which can be represented. This
number can be changed to accomodate the largest file expected or extended to map to the full Files 11
limit.

E.1 .3

Data Stream Format

Currently the data stream is represented as a STREAM CR format with the assumption that it contain
text. Clearly this needs to be extended. It is not clear how the data fork should be interpretted, there is
no indication, short of scanning for non-printable characters which could be used to determine the data
format. RMS based applications assume the file format is stored in the file and can be used to
determine how to process the file. For the purposes of this tial development, we have assumed that the
data should be returned as RMS VAR format with CR attributes and is stored as a stream of records
terminated by <CR> (sample Macintosh text file is stored this way).

E. 1 .4

Resource Stream Format

The resource stream is simply represented as a stream of bytes. The caller will have as many bytes
returned as will fit in the buffer. The file is still reported as RMS VAR format with CR attributes as
this information needs to be returned before the stream access is done (RMS $CONNECT). While the
support to read the resource fork is implemented it can not be accessed by RMS in this trial
development.

E.2

Extension

Structure

The RMS extent is structured as an initialzation routine, series of callout routines and a set of support
routines. The basic approach was to use RMS facilities to read and write a block of the file and perform
the rest of the record access in support routines. RMS supplies two such routines;
RMS$GET_BUFFER and RMS$RELEASE_BUFFER. The routines access the RMS data cache and
will perform file reads (if requested) or file writes (if requested). For the purpose of this trial
April 20, 1992

Digital Confidential

131

PATIIWORKS File System

development only those routines necessary to access a sequential text file have been implemented. Both
sequential and random access to these records is provided.
The callout routines completely replace the normal RMS routines. This means the routines must
update user fields of the RMS structures (FAB/RAB/XAB) and also move data to and from the user
buffers pointed to in these structures.

E.2.1

Initialization

The extent initialization consists of a call to add the semantic tag to the RMS table and provide a set of
callout entry points. RMS will call the routines declared by a non zero entry in the appropriate slot in
the dispatch table. If an entry is zero, RMS will handle the function internally using the normal RMS
access. RMS provides a standard "not implemented" callback routine which should be used if an RMS
function is to be denied. IF the normal RMS handling for a function is sufficient, a zero should be
placed in the dispatch table slot.
This is the only execution time function of the extent. It simply sets up the table, calls RMS to
identify the sematics and exits. The remainder of the extent remains mapped and will be called in the
context of an RMS thread.

E.2.2

RMS support routines

RMS provides a series of routines to provide the extent with access to internal data structures and file
data. These routines are only partially implemented. The history of the RMS extent development is
such that only the first phase of development was completed. This development was done to support
the CDA architecture. Unfortunately, this developement only required read access to files and as such,
no simple mechanisms for file writes and file extend operations are provided. These functions must be
implemented by using the low level RMS calls and direct QIO access to the file (for file extends).
The trial development uses a small set of routines primarily for block level read and write access to the
Macintosh file.

E. 2. 3

Data Structures

The extent uses a simple context block to store information needed across calls to process the file. This
information includes the stream mapping data and various data buffers.
The extent caches mapping data while accessing the file. this data will be written back to the file when
the stream is disconnected (either thru an RMS $DISCONNECT or an RMS $CLOSE).

E.2 .3 .1 CXT - Context Block
The context block is used to store the extent internal state information across RMS access calls. The
information stored maps access to the file, identifies the current position in the stream and also stores
pointers to RMS internal structures.
CXT$L_STMEOS - End of stream VBN
The stream EOS position is the last virtual block of the stream. This pointer is obtained from the
Macintosh file header block (VBN 1 in the Macintosh file). This pointer will be updated for writes
beyond end of file (if they cross into a new VBN). The field will be written back to the Macintosh
file header when the stream is disconnected.
CXT$L_STMFFB - First free byte
The stream first free byte is the first free byte in the last block of the stream. Together, the two
fields defme the end of the stream. This position will be updated for writes beyond the end of
stream. This field will be written back to the Macintosh file header when the stream is
disconnected.
April 20, 1992

Digital Confidential

132

PA1llWORKS File System

CXT$L_WINDOW - Mapping window
The mapping window contains a set of stream mapping pointers. The window is "turned" as the
stream is accessed, if necessary. While the concept of turning is defined, it is not implemented for
this trial development. A number of issues have been identified which will necessarily require
modifications to the data structures to handle window turns.
As defined currently, a backward tum requires the window be turned back to the start of the stream
and then turned forward to the requested VBN. A linked list of window pointers could be
maintained to reduce this operation but there is a limit as to how many pointers may be
maintained. While this implementation would reduce the need for complete turns, it would not
eliminate it.
This area needs to be explored for the final development.
CXT$L_WINBASE - Base stream VBN of window
This field defines the starting stream VBN of the current mapping window. This field is used while
translating stream VBN to file VBN.
CXT$L_BUF - General buffer
A 512 byte general bufer is allocated. It is not currently used but is envisioned to be necessary to
handle window turns.
CXT$L_BUFFER - Data buffer
The current RMS data buffer's data pointer is stored in the context block, as well as the RMS data
buffer pointer itself. The data buffer's data pointer is used as the base address for stream reads and
writes.
CXT$L_BUFPTR
The current buffer pointer is stored to support sequential record access and also for record deblocking. As the extent routines completely replace RMS routines, this de-blocking must be
performed by the extent.

E. 2. 4

Global Routines

The trial development supports access routines necessary to test host based applications which deal
with text files. These routines are generally limited to $GET, $PUT and $FIND access. The extensions
to include $READ and $WRITE are straightforward. $EXTEND functions will be difficult to
implement as the routines to actually extend a file are not provided by RMS. $1RUNCATE would
simply convert the mapping pointers in the Macintosh file header to FREE pointers.

E.2.4.1 EXT_CONNECT - RMS $CONNECT callout
The $CONNECT callout allocates space for the context block and links it to the internal RMS IRAB
structure. This internal structure pointer is passed on all access callouts.
This callout is only a supplement to the normal RMS $CONNECT handling.

E.2.4.2 EXT_GET - RMS $GET callout
The $GET callout translates stream VBNs to file VBNs, reads file blocks and de-blocks file records.
File access by RFA or sequential access are supported. Read ahead access is not supported and is
ignored.
April 20, 1992

Digital Confidential

133

PATHWORKS File System

This routine completely replaces the normal RMS $GET function.

E.2.4.3 EXT_PUT - RMS $PUT callout
The $PUT callout translates stream VBNs to file VBNs and merges records into the file block. File
access by RFA or sequential access are supported. Write behind access is not supported and is ignored.
This routine completely replaces the normal RMS $PUT routine.

E .2 .4 .4 EXT_FIND - RMS $FIND callout
The $FIND callout simply sets the next VBN and BUFPrR fields for subsequent access. The specified
file block is read in if not already in the data buffer.
This routine completely replaces the normal RMS $FIND routine.

E.2.4.5 EXT_DISCONNECT - RMS $DISCONNECT callout
The $DISCONNECT callout writes out the fmal data buffer (if present), updates the Macintosh file
header and deallocates the context block and data buffers.

E.2.4.6 EXT_DISPLAY - RMS $DISPLAY callout
The $DISPLAY callout simply sets the FAB record format and attributes field to indicate a VAR CR
file format. The XAB chain is also scanned to modify any XABFHC blocks present.
The $DISPLAY callout supplements the $DISPLAY function and the $OPEN function.

E.2.4.7 EXT_MUCK_XABFHC - callback for scan XAB
This routine is called if an XABFHC block is present in the XAB chained, linked to the FAB.
This routine is called as a callback for the RMS$SCAN_XAB_CHAIN routine.

E.3

Restrictions

There are a number of restrictions on the extent and on its use.

E.3.1

File

writes

File writes are possible but a direct QIO call must be made to extend the file allocation. It is not clear
what internal state must be modified after this is done. (It is assumed that IFB$L_HBK is sufficient).

E. 3. 2

Buffer usage

The buffer use must be completely understood. There are a number of issues around buffer use which
are somewhat unclear. In particular, the IFB$L_AV ALCL field, which indicates the number of buffers
available, is not maintained by the buffer calls provided. The field is currently updated after calls to
RMS$GET_BUFFER. Failure to do this will bugcheck RMS as no buffers are available.

E.3 .3

File updates

Tests have been performed with EDT and EMACS to determine if the contents of the file may be
modified an preserve the file structure. Unfortunately, both editors (and probably most others) create a
new version of the file which does not propagate the file structure. The resource fork is lost. Note that
this is precisely the same behaviour as would be seen if the file was edited from a DOS client.

April 20, 1992

Digital Confidential

134

PATHWORKS File System

It is clear that the PATHWORKS file system MUST support Macintosh files in both native mode file
structure and Macintosh format file structure. (It is currently envisioned that Macintosh files would not
be stored in the Macintosh format unless a resource fork was present. Note that converting a native
mode file to a Macintosh format file involves simply moving the first block and adding the Macintosh
file header with two mapping pointers. This would have to be done when a resource fork was added to a
native mode file).

E. 3 .4

Printing

Files

It has been rumoured that various print symbionts do not use RMS to access the records of a file. This
needs to be looked into closely as this would mean Macintosh format file could not be printed without
conversion. This may be an issue for the PATHWORKS Print Subsystem

E.4

Issues

The purpose of this trial development was to demonstrate the capabilities or the RMS extent as applied
to Macintosh files, test simple host utilities and get some insight into the issues around the file
format. These objectives have been accomplished. It now needs to be decided if we should continue
with this two data context file concept or if we should address the problems of representing Macintosh
files as two separate files.

April 20, 1992

Digital Confidential

135