Digital PDFs

MISC-0004-PW-40

June 1993

290 pages

Original

9.6MB

Document:	PATHWORKS File System 4.0
Order Number:	MISC-0004-PW-40
Revision:	0
Pages:	290
Original Filename:

OCR Text

PATHWORKS File System
Personal Computer Systems Group

Abstract
This specification contains the function description of the PATHWORKS File System
(PFS) and standard file system libraries.

DRAFT COPY

Written by:

Michael Evans

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

Issued by:

Michael Evans
-----------------------------Reviewed by:
------------------------------

Issue date:

June 9, 1993

Revision/Update
Information:

Version #4.0

Software Revision

BIA

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

PREF ACE .•••••••••••••••••••••••.••••••.•••••••.•••••••••••.••.•••••• 10

REVISION

INTRODUCTION .••••••••••••••••••••••••••••••••..••••••.•••••••.•• 12

REFERENCES ......•••.....•..•....•..•........••......•...•••.••.... 15

DESIGN REQUIREMENTS .••...••••••••••.••.•••.•••••••..•..•...• 16

OVERVIEW •.••••••••...••••.••••.•.••.••••••..•.•...•••.•••...•.••..• 18
7 .1 Functional overview ..•....................................... 18
7. 2 Summary of functions •...•.••..•.••..••....•.•....•......•..• 18
7. 3 File service components •.•.•...••.••..•..•.•..•.•••..•••.•... 2 0
7 .3.1
7 .3 .2
7 .3 .3
7 .3 .4

7 •4

7 .4 .3

Top level interface ..................................................26
File System Library Interface (FSLIB) ..........................26
7 .4 .2.1 FSLIB Path Claim ...................................... 27
7 .4 .2 .2 FSLIB Initialization .....................................27
Data cache interface ................................................28

Data structures . . . . • • • . • . . . . • • . . . • . . • • . • . . . . . . • • • • . • • . . • . . . • . . • 3 1
7.5.1

7.5.2
7.5.3
7.5.4
7.5.5
7.5.6
7.5.7
7.5.8
7.5.9
7.5.10
7.5.11
7.5.12
7.5.13
7.5.14
7.5.15

7 •6
7 •7
8

Namespace ..........................................................21
Attributes ............................................................22
Security ..............................................................24
Data Patlls ...........................................................24

Structural overview ..•..•.••...••..••........•.•••••..•.....•. 2 6
7 .4 .1
7.4.2

7 •5

HISTORY ••••••.•••••••.•••••••••.•.•••••••.••••••••••••• 11

PFS_PATHID ........................... .-..........................32
PFS_FID ...............................................35
PFS_ATTR .........................................................38
PFS_STAT ..........................................................40
PFS_NAMEID .....................................................42
PFS_CWD ..........................................................44
PFS_USER .........................................................45
PFS_LIB_ENT .....................................................46
PFS_IDENT ........................................................47
PFS_ROOTID ......................................................48
PFS_EAOPS ........................................................49
PFS _MACSECUR .................................................52
Stat structure ........................................................53
Dirent structure .....................................................56
Utimebuf structure .................................................57

Function error codes •.•....••..••.••.•.•.....•••.•••.•••.•..•. 5 7
Initialization parameters •..••..•••.••.•.••.•.•••••••..•..•.... 5 9

PFS ROUTINE DESCRIPTIONS •...••..•...•..•...••..•...••••...• 6 0
8.1. PFS_access *.................................................. 61
8. 2. PFS_faccess *................................................. 61
8 •3 . PFS canceldesc * ............................................. 6 3
8 . 4 . PFS=chdir ••.•..••••...•••.••••.•.•••..••.••••••••.••.••.•.•... 6 4
8. 5. PFS_fchdir •.••..•..•..••....••.•..•...••..•...••..••.••.•••... 6 4

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8. 6. PFS_checksecurity ••••••••••••••••.••••••••••••••••••••••••.•• 6 5
8. 7. PFS_chmod •••.••••••••••.•••••••••••••••••••••••••••••••••.••. 67
8.8. PFS_fchmod .•••••••..•.••••.•••.•.•••..•••••••••••••.••••••... 67
8.9. PFS_chown ••••••••••••••.•••••••••••••••••.••••••••••••••••••• 68
8.10. PFS_fchown •••••••.••••••••••••••••••••••••••••••.••••••••.••. 68
8 .11. PFS_close •••••••••••••••..•••••••••••.••••.•••••••••.•.••••••• 69
8 .12. PFS_closeandpurge *......................................... 7 0
8 .13. PFS_copyfile •••••.••••••.••••..••••••••••••••••••••••••••••••• 71
8.14. PFS create .••••••••••••..•••.••..•••••••••••••••••••••••••••••. 73
8.15. PFS- delete .••••••••••••.••.•••.•••••.•••••.•••••••••••••••••••• 75
8 .16. PFS_dentpathid * ............................................. 7 6
8 .17. PFS_didpathid * .............................................. 7 7
8 .18. PFS diridfunc ••••••••••••.•••••••••••••••••••••••••••••••••••• 7 8
8 .19. PFS=diridinit •••.•..••••....•..••••••..•••••••••••••.•••••••••• 7 9
8. 2 0. PFS filesize ••••••••...•••.•••.•••••••••.•••••••••••••••••••••• 8 0
8. 21 . PFS-ffilesize ••••••.••••••.••••••••••.••••••.••.••...•••••••••. 8 0
8 .22. PFS-freeuser *................................................ 81
8.23. PFs-=.rsync •••••.•••.•••.••.•••••••.•••.•••••••••••••.•••••••••. 82
8.24. PFS_fullpath ••....••..•.•..•.....••..•••.••.•••••••••••••••••• 83
8. 2 5. PFS_getattr ••••••••..••.•..•••.•.•.•••••..••.••••.•.•.••••••.•. 8 4
8. 2 6. PFS_fget.attr ••.•••••••.•••..•..••..•..•••••••••••••••••.••••••• 8 4
8 . 2 7 . PFS_getcachedesc * .......................................... 8 5
8.28. PFS_getcomment ••..••....•••.•...•.•.••.•••.•••••...•..•••••. 86
8.29. PFS_getcwd .••.•••......•..•...•..••••.•.••..••••.•••••.••••.• 87
8.30. PFS_getdents •.••..•••.•....••.•...••••.••••.••.•••..••....•••. 88
8 .31. PFS_geterrno
* ................................................ 90
8.32. PFS_getextattr .••••.•.•...•••..•.•••.••••.•••.•••••.•.•.••.•••. 91
8.33. PFS_fgetextattr •.•...••..••••..•.••••••••.•••••••••.••.••....•. 91
8. 3 4. PFS _getpathid ...•••.•.............•....•.••..••••••••••.•••••• 9 3
8.35. PFS_getpathidX
95
8.36. PFS_getprintident
*··········································· 97
8 .37. PFS_fgetprintident
*·········································· 97
8 . 3 8 • PFS _getrootid *.............................................. . 98
8 .39. PFS_getsecurity
99
* .............................................
8 .40. PFS_fgetsecurity
............................................
99
* •...••••••••••......................... 101
8 .41. PFS_getsecuritymode
*
8. 4 2. PFS_getuser * ................................................ . 102
8.43. PFS_init •..•..••.•••...•...•.......•.••....••.•••••..••.•..•... 103
8.44. PFS_lock •.....••...•••••..•..•..•.•.•.•..•••.•.•.....••...••.•• 104
8.45. PFS_lseek ....••..••.•.••.•......•...••••.••.••••••.•..••..•.•• 106
8.46. PFS_mapname ••.•.•••.••.•••.•..•..••.•..•••••.•...•.••....... 107
8. 4 7. PFS_fmapname ••.•••..•••••..•.•...•.•..•.••••••••••......•.•• 107
8.48. PFS mkdir •.•••.•.•...••..••.•.....••.•...•..•••••••.•..•...••• 108
8.49. PFS_mpxclose •••••.•••••.•..••.•••..••...••••••••••••..••..... 109
8.50. PFS_needfds ..••.•••..•••.•.••..•..••.•....•••.....•.••...•••. 110
8.51. PFS_needinodes ..••....•.•..•...•••.••.••.•••...•.••••.••.•.•• 111
8.52. PFS_open ..•..•••.•.••••.••..••..•.•.•••...••••.•.....•.•...•.• 112
8 •5 3 • PFS_parse * .................................................. . 114
8.54. PFS_pathfunc *
115
8 .55. PFS_purge .•.....................•.•.........•................. 118
8.56. PFS_read .....•••••.••.•..••.••.••...•..•..••.••.•.••.......••• 119
8.57. PFS_readdesc *
120
8 .58. PFS_releasedesc *
121
8. 5 9. PFS_rename ...••...••••..••••••••.........••.•..•.••.•.•.....• 122

*·············································

...............................................

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .60. PFS_rmdir ••••.••••••••.••••••••••••••••••••••••.•••••••••••••• 123
8 .61. PFS_setattr •••.••••••••.••.•••••••••••••••••••••.•••••••••••••• 124
8 •6 2 • PFS _fsetattr ••.•••••••••.•.•••••••••••••••••••••••••••••••••... 124
8 .63. PFS_setcomment •••••••••.•••••••••••••••••••••.•••••••••••••• 125
8 .64. PFS_setcontext •••••.••..••.•.••••••••••••••••••••••••••••••••• 126
8 .65. PFS_setextattr •••••..•••••.•••••••••••••••••••••••••••••••••.•• 127
8 .66. PFS_fsetextattr ••••••••..•••••••••••••••••••••••••••••••••••••• 127
8 .67. PFS_setlognores •••••...••••.•••••••••••• • •••••••••••.•••••••• 128
8 .68. PFS_setnotifympx •.••....•••••••••••••••••••••.•••••••••••.•• 129
8 •6 9 • PFS _setsecurity *............................................ . 130
8. 7 0. PFS_fsetsecurity *........................................... . 130
8. 71. PFS_setsecuritymode •..•••••..•.••••••••••••••..••••.•••••••• 132
8.72. PFS_setuser ••...•••••.•....••••••••••••••••••••.•••••••••••..• 133
8.73. PFS_shortpath .•.•••••••••••••••.••••••.••••••••••....•..•••.•• 134
8. 7 4. PFS_shutdown ••••.•••..••••....•.•••••••.•••••••••••.•••••..• 135
8. 7 S. PFS_stat .•••...•.•.•.•......•....•••••.•••••.•••..••••.•••••..• 136
8. 7 6. PFS_fstat •••.....••..•..•..•••...•••••.••••••••••..•.•.••.••..• 136
8.77.PFS statvfs •••.••...•..•••.•••..•••••••••.•••..••••..•••••••..• 137
8.78. PFS fstatvfs ••.....••..•...•..•...•••••••••••..••.•••••..•••... 137
8.79. PFS_sync ••••.....••••..••..•...•.••••.•••••••.•..••••.••....•• 138
8 •8 0 . PFS _treetop ••.•.•••.•......••.••.••••.••••••••••.••••.•••••... 139
8.81. PFS_timefunc ..................•.••••.•••.•.•••..••••.•.•.•..• 140
8 .82. PFS_ftruncate .......•......•••...••••••••.•..••...•••.•.•••..• 142
8.83. PFS_unlock •...••..••...•••.•••..•..•..•..••.•.•••••.••.•.••..• 143
8.84. PFS_unmap ......••..•......•.•..•••••.••••••.••..••.•.••.••... 144
8.85. PFS_utime •••....•••.•...•..•....•...•.•••.••.••.....•.••.••... 145
8.86. PFS_futime .•....•..............••••••.•••.••..•..••••.••..••.• 145
8 . 8 7 . PF S _write ••.•...•...•..•...•....••.••..••.••.••..••...•••••... 146
147
8 .88. PFS_writedesc *

..............................................

FSLIB (File System Library) ROUTINE DESCRIPTIONS .•.•..• 148
9 .1 . FSLIB_access * ............................................... 14 8
9. 2. FSLIB_faccess * .............................................. 14 8
9 .3. FSLIB chdir .•...••.•.....•....•..•..•.•..•••.....••.•....••..• 149
9.4. FSLIB fchdir •......•••..•••...•••..••..•.•.••..••..••..•••••.• 149
9 .5. FSLIB_checksecurity ..................•...................... 150
9. 6. FSLIB_chmod ...••.••......•......•••.••..•..•..•.•.••••.••..• 151
9. 7. FSLIB f chmod ...••.•...........•.•••..•..•••••••••••.••.•...• 151
9.8. FSLIB=chown ••.•...•......•.....•.••..•..••••..•••••....••..• 152
9 .9. FSLIB_fchown .••...•......•••.•...•..•••.•••••.••.•..••..•.•• 152
9.10. FSLIB_claim .....••.•.........••.•.•..••.••.•••..••••.•••••.•• 153
9 .11. FSLIB close ••.•..••...••.•••.••.••.•.•••.•••..••••.•••.•..•..• 154
9.12. FSLIB_closedesc .••.•.••.•••••..•••••...•...••.••....•...•..•• 155
9 .13. FSLIB_convert *.............................................. 15 6
9.14. FSLIB_create
* ................................................ 157
9 .15. FSLIB_dentpathid * .......................................... 15 8
9.16. FSLIB_didpathid
*............................................ 159
9 .17. FSLIB_diridfunc ••..•......•.•.•..•••••••••••••.•••••.••.••.•• 160
9 .18. FSLIB diridinit ••••.••.....•••.•.••.••••.••.•••..•.••••••.•.•• 161
9.19. FSLIB=fextend •....•......••..••.•••..•••••..••..•••••.......• 162
9 •2 0 . FS LIB _filesize •..••...............•••..••.••.•.•.•.••.•..••..• 16 3
9 .21. FSLIB_ffilesize ...•.•..........•..•••..•••••.••.•••••.•..••..• 163
9 .22. FSLIB_fsync ••••.•.•••.•.....•••..•••••.•••••••.•••••.•..••..• 164
9 .23. FSLIB_getattr .•••••••.•.•.•...••.•••..•••.•..••.••••.••••••..• 165

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

9.24. FSLIB_fgetattr •.••••••.•••••••••••••••••••••••••••••••••••..•• 165
9 .25. FSLIB_getcomment •••••••••••••••.••••••••••••••••••••••••••• 166
9. 2 6. FSLIB_getdents •.••••...•••••.•.•••••.••••••••••••••••••••.••• 167
9 .27. FSLIB_getextattr
* ............................................ 168
168
9 .28. FSLIB_fgetextattr
* ........................................... 169
9 .29. FSLIB_getprintident *
9 •3 0. FSLIB _getsecurity *......................................... . 170
9 .31. FSLIB_fgetsecurity *........................................ . 170
9.32. FSLIB_init ...••••••••.••••••.•.••...•••••.••••••••••••.••.••.•• 171
9.33. FSLIB_lock ••••••••••••••••••••••..••••••••••••••••••••.••••••. 172
9 •3 4 • FSLIB _lookup * ............................................. . 173
9.35. FSLIB_lseek •.••••••••••••••.••••••.••••..•••••••••••••••.••••• 174
9. 3 6. FSLIB_mapname ••••••••.•••••••••.••••.•••••••••••••.•••••••. 175
9 .3 7. FSLIB_fmapname .••.•••••••••..•••..••••.•••••.••••••..•••.•• 175
9 •3 8 • FSLIB _mkdir •..•.••••••.••••••.••••••••••..•••••••.••••.•.•••. 176
9 .39. FSLIB_mpxclose ..•.•••••.•.•••.•••••••••.•••••..••••••••••.•• 177
9. 4 0. FSLIB_mpxopen •••••••..••••...••.•.••••••••••••••••.••••••.. 178
9 .41. FSLIB_open .•.•••••••••••.••.•.•..••••••...••.•..••••••.•••••• 179
9.42. FSLIB_opendesc .••••••...•••.•.•...•••.••.••••••••.•.•••.•••. 180
9 . 4 3 . FSLIB _purge •..••••.••..•.••.•....•.•••••.•••.•....••••..••••• 181
9 . 4 4 • FSLIB _fpurge .••.•••.••.•..•••..•.....••••••••••..•••..•.••.•• 181
9.45. FSLIB read ••.•••••••..••••..••••.•••..•••.•••••••............. 182
9 . 4 6 • FSLIB _readdesc * ........................................... . 183
9 .4 7. FSLIB_rename ••.•••...•••••.•.•...•.•.••.•••••.•..••.•...••.. 185
9 . 4 8 • FSLIB _rmdir .•.•.••..•..•.•..•....•.•...•••••.•..•••.•...••••. 186
9 .49. FSLIB_setattr •...••.•.•.•..•.........•.••.•••......••....•••.. 187
9 .SO. FSLIB_fsetattr ...•••••••••.•......•....••••••••..........••.•• 187
9.S1. FSLIB_setcomment ..•.••••..•....•.•••.••.••....•.••.••.••... 188
9. S 2. FSLIB_setextattr *........................................... . 189
189
9 .53. FSLIB_fsetextattr *
9 .54. FSLIB_setsecurity *
190
9 .SS. FSLIB_fsetsecurity * ........................................ . 190
9 .56. FSLIB_stat ...•...........•.••.....•....•.••.......•..•......•. 191
9 .57. FSLIB_fstat· ..........•..•..........................•......•... 191
9 .58. FSLIB_statvfs •...••.•....•...••.........••....•...•.••.....••• 192
9 .59. FSLIB_fstatvfs ..............•................................. 192
9 .60. FSLIB_sync ..•..••••....•••.••.•..•••.•.••.•.••..••••.....••.• 193
9 •61 . FSLIB _ftruncate .••....••.•••......•••.•.•...•••.•••..•.....•. 194
9 .62. FSLIB_unlock •...•••...•.•..••.••.•••.•.••.••....••.••.....•.. 195
9 .63. FSLIB_unmap •.•••.••...•..••.•••.•.•.••.••..••••.....•...•••. 196
9 .64. FSLIB_utime .•...••...••••...•.•..••••..••.••••..•••.......... 197
9 .65. FSLIB_futime •..•••••••......••••.••..••..•.•••..••.••.....••• 197
9.66. FSLIB write .••••••••......••••......•••••••.•••..•••...••...•. 198
199
9 .67. FSLIB_writedesc *

........................................

...........................................
..........................................

...........................................

PATHLIB (Path Library) ROUTINE DESCRIPTIONS •.•••.•.•.•• 200
10.1 PATHLIB_parse ••...••••.••..•••.•.•.••.•••••.•••.••.•••.•..•. 200
10.2 PATHLIB_split .•••.•••.••••.•...••...••.••••••••..•.....•.•... 201
10.3 PATHLIB_parent ••••.••.•.•.••.•.••..•••..••.•.•..••..•.••.... 202
10.4 PATHLIB_directory ..•.......••...•......••......•.......••.. 203
10. S P ATHLIB _matchpath •..•..•.••••..•••....••••••••.••..•.••••. 2 0 4
1 0 •6 PATHLIB_matchname •••.••••••••.•..•.•••••••..••.••••....•. 2 0 S
1 0 •7 PA THLIB _match pattern • . . • • . • • • • . • • . • • . • • • • • . • • • . • • • • . • . . . • • 2 0 6
10. 8 PATHLIB _expandname ••••...•.•.••.....•••••..•••....•...... 2 0 7

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

10.9 PATHLIB_mvwild •••••••••••••••••••••••••••••••••••••••••••• 208
11

TIMELIB (Time Library) ROUTINE DESCRIPTIONS ............ 209
11 .1 TIMELIB fromnativetime ••••••••••••••••••••••••••••.•••••.• 210
11. 2 TIMELIB- tonativetime •••••••••••••••••.••••••••.•••••••.•••• 211
11 •3 TIMELIB- tounixtime ••••...•••••••••••••••••••••••••••••••••• 212
11 •4 TIMELIB=todostime •••••••.•••••••••••••••••••••••••••••••••• 213
11. 5 TIMELIB_tomactime ••..•••.•••••••••••••••••••••••••••••.•.•• 214
11.6 TIMELIB tovmstime •••••••••••••••••••••••••.•••••••.•••••.•• 215
11. 7 TIMELIB_totexttime ••.••.•••••••••••••••••••.••••••••••..•••• 216

T ANDARD
L BRAR IE •.••.•.••••••.•••••.••••••.••••.••••.••..... 217
12 .1 ODS2 DOS library ••••.•••••••.••.••••.••.••••••••••••.••••••• 21 7
12.1.1
12 .1.2
12.1.3
12 .1.4
12.1.5
12 .1.6
12 .1.7

Namespace ..........................................................217
Attributes ............................................................218
Security ..............................................................219
Datapatlls ............................................................220
FID cache ............................................................220
Directory cache .....................................................220
Patll cache ...........................................................220

12.2 ODS2 MAC library ••.•.••.•.••••....•..•••••••••.••..•.•••.•.. 220
12 .2 .1
12 .2 .2
12 .2 .3
12 .2 .4
12 .2 .5

Namespace ..........................................................221
Attributes ............................................................222
Security ..............................................................225
Datapatlls ............................................................225
Name cache .........................................................225

Appendix A - VMS ODS level 2 file system ............................. 226
A .1 Directory structure •......••..•...•.••••....••....•.••.....•... 2 2 6
A •2 File structure • . • • • • • . . . . . . . . . • . . . . • • • . . . • • • • . . . • • • • . • • . . • . . • • . . 2 2 6
A.3

A .4

A.2.1

Access Control Lists (ACL) .......................................226

File

attributes ••••..............•••....•••.•..••..••.....••••... 227

A.3.1
A.3.2
A.3.3
A.3.4
A.3.5
A.3.6
A.3.7

File creation time ...................................................227
File revision time ...................................................227
File backup time ....................................................227
File expiration time .................................................227
File organization ....................................................227
Record structure ....................................................228
Record attributes ....................................................228

File allocation .•.••...•......••...•.••.•••••.•••••...•..•..•... 2 2 9
A.4.1
A .4 .2
A.4.3
A .4 .4

A .5

File header ...........................................................229
Index file ............................................................229
Bitmap file ...........................................................229
Quota file ............................................................229

Security model •..•..••.•....•..•.•.•••....••.•••••.••...•..... 229

Appendix B - MSDOS FAT file system ••••.••.••.•••••••••••••.••••..•.. 231
B .1 Directory structure •••....•...•..•.•••••..•••..••••.••..•...•.. 2 31
B •2 File structure . . . • • . . . • • . . • . . . • • . • . • • • • • • • • • • • • • • • • . • . • . . • • . • . . . 2 31
B.3 File
attributes ••.•.•••.•••••••••••.••••••.•...••••••....•...•... 231
B .3 .1

B.4
B .5
June 9, 1993

Modification time ...................................................231

File
Allocation ••......••.••••••••..••.•••••••••.••.•.•.•..•.... 231
Security model ...•.••••.•..•••••••.•••..•.••..•••••.••....•... 2 3 2
Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Appendix C - Macintosh HFS file system •••.•••••••••••••••.••••••••••• 23 3
C .1 Directory structure .•.•.•••.••••••..••••••••••••••••••••••••••• 2 3 3
C . 2 File structure • • . • . • • . . • • . • • • • • • • • • . . . • . . . • • • • . • • • • . • • • • • • • • • • • • 2 3 3
C.2.1 Data fork .............................................................233
C.2.2 Resource fork .......................................................233
C .3 File
attributes •••••.••••••••••••.••••••••••••••••••.•••••••••••• 233
C .3 .1 File creation time ...................................................234
C .3 .2 File modification time ..............................................234
C. 3 .3 File backup time ....................................................234
C .4 File allocation ••.••.•.•••••••••••.••••••••••••••••••••••••••••• 23 4
C . 5 Security model ••••.••••.••••••••..••••••••••...•.•.••••••••••. 2 3 4
Appendix D - FSI interface •••••....••.••.••••••••••••••...••••••••.•••••• 23 5
D .1 General Architecture .•.••..•••••..••..•.••••••.•..••.•••. ~- .••• 23 5
D .1.1 File Descriptor Multiplexing ......................................235
D.1.2 Volume Services ....................................................236
D .1.3 Directory IDs ........................................................236
D .1.4 Namespace ..........................................................236
D .1.5 Streruns ..............................................................237
D .1.6 Extended Attributes ................................................237
D .1.7 FSI Routine Classification ........................................238
D.2 PATH ID (FSI_PATHID) ••.•••••.•.•••••••....•.......••.•••• 239
D.2.1 File ID (FSI_FID) ..................................................240
D .3 ROUTINE SUMMARY •.••••.••..••.•••.•••..•.••.••..•••••.. 242
D.3.1 FSLaccess ..........................................................242
D.3.2 FS I_chdir ............................................................243
D.3.3 FS I_fchdir ...........................................................243
D.3.4 FS I_chmod ..........................................................244
D.3.5 FS I_fchmod .........................................................244
D.3.6 FSI_chown ..........................................................244
D.3.7 FSI_fchown .........................................................245
D.3.8 FSI_close ............................................................245
D.3.9 FSl_copyfile ........................................................245
D.3.10 FSI_create ...........................................................246
D.3.11 FSI_delete ...........................................................248
D.3.12 FSI_diridinit ........................................................248
D.3.13 FSI_diridfunc .......................................................249
D.3.14 FSI~ffilesize ........................................................249
D.3.15 FSI_fsync ...........................................................250
D.3.16 FSI_fullpath ......................................................... 250
D.3.17 FSI_getattr ..........................................................250
D.3.18 FSI_fgetattr .........................................................251
D.3.19 FSI_getcomment ...................................................251
D.3.20 FSI_getcmd .........................................................252
D.3.21 FSI_getdents ........................................................252
D.3.22 FSI_getextattr .......................................................253
D.3.23 FSI_getpathid .......................................................254
D.3.24 FSI_lock .............................................................256
D.3.25 FS I_lseek ............................................................256
D.3.26 FSI_mapname ......................................................257
D.3.27 FSI_fmapnrune .....................................................257
D.3.28 FS I_mkdir ...........................................................258
D.3.29 FSI_mpxclose ......................................................258
D.3.30 FSI_needfds ........................................................258
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

D .3 .31
D.3.32
D .3 .33
D.3 .34
D .3 .3 5
D .3 .36
D.3.37
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

FSI_needinodes ....................................................259
FSI_open ............................................................259
FSl_purge ...........................................................260
FSI_read ............................................................ 261
FSI_rename .........................................................261
FSI_rmdir ...........................................................261
FSI_setattr ...........................................................262
FSl_fsetattr ...................................... ~ ...................262
FS I_setcommen t ................................................... 263
FSI_setextattr .......................................................263
FSI_setlognores ....................................................264
FSI_setnotifympx ..................................................265
FS I_shortpath .......................................................265
FSI_stat ..............................................................265
FSI_fstat .............................................................266
FSI_statvfs ..........................................................266
FSI_fstatvfs .........................................................266
FSI_sync ............................................................267
FSI_ftruncate .......................................................267
FSI_tretop ...........................................................267
FSI_unlock ..........................................................268
FSI_unmap ..........................................................268
FSI_utime ...........................................................269
FSl_futime ..........................................................269
FSI_ write ............................................................269

Appendix E - RMS Extent for Macintosh file format •..•...•..••...•..• 2 71
E .1 File Format ••...•.............•.••..••.•...•....•.•..••.•.••..• 2 71
E.1.1
File Semantics ......................................................272
E.1.2 Header ...............................................................272
E .1.2 .1 Allocation ................................................272
E.1.2.2 Stream Descriptors ......................................272
E.1.2.3 Mapping Pointers .......................................272
E.1.3
Data Stream Format ................................................272
E.1.4 Resource Stream Format ..........................................273
E. 2 Extension Structure ........................................... 2 7 3
E .2 .1
Initialization .........................................................273
E .2 .2 RMS support routines .............................................273
E.2.3
Data Structures ......................................................274
E.2.3.1 CXT- Context Block ...................................274
E.2.4 Global Routines ....................................................275
E.2.4.1 EXT_CONNECT .......................................275
E.2.4.2 EXT_GET ...............................................275
E.2.4.3 EXT_PUT ...............................................275
E.2.4.4 EXT_FIND ..............................................276
E.2.4.5 EXT_DISCONNECT ..................................276
E.2.4.6 EXT_DISPLAY .........................................276
E.2.4.7 EXT_MUCK_XABFHC ..............................276
E .3 Restrictions •..••..••...••......•...••.•••....•.•••.•••.••.•.••• 2 7 6
E.3 .1
File writes ...........................................................276
E.3 .2 Buffer usage ........................................................277
E.3 .3 File updates .........................................................277
E.3 .4 Printing Files ........................................................277
E.4 lssues ..•.......•..•...••...•.•.•.•.•...•••.•.•....•••.•..••...• 277
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Appendix F - File System Configuration Parameters ••••••.•••••••••••• 2 7 8
F .1 PFS File System •••••.•••••••••.••.••••.•••••••••••••••••••••• 2 7 8
F .2 ODS2 File System ••••••••••.•••..•••••••••••••••••••••••.••••• 279
F.3 FAT File System •••••..••••••••••••••.•.•••••••••••••••••••.•• 288
F. 4 DEBUG Facility .••.•••.•••.•••••••••••••.••••••••.•.•.••••.•.• 2 91
F •5 Channel Multiplexing ••••••••••••••••••••••••••••••.•••••••.•• 2 91

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

REVISION HISTORY
Michael Evans

0.0

21-Apr-1992

Initial creation

Michael Evans

0.1

3-Aug-1992

Revise structure of document and
add design details

Michael Evans

1.0

19-0ct-1992

Update function descriptions, add
PFS _checksecurity(). Redefine
PFS structures.

Michael Evans

1.1

30-0ct-1992

Add FSLIB_opendesc() and
FSLIB_closedesc(). Update
descriptions.

Michael Evans

1.2

5-Nov-1992

Add FSLIB_fextend(), changed
font size so I can read it!

Michael Evans

2.0

20-Jan-1993

Updated to reflect Base Level 2
release.

Michael Evans

3.0

8-May-1993

Updated to reflect Base Level 3
release. Added PFS_pathfunc(),
PFS _timefunc(), changed return
status codes, eliminated
PFS_errno

Michael Evans

4.0

24-May-1993

Updated to reflect Base Level 4
changes. Added PFS_getrootid(),
PFS _getpathidX() , parameter
descriptions. Updated structure
definitions.

June 9, 1993

Digital Confidential- 3rd Party Restrictions Apply

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S 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.
The following terms are used throughout the document and are presented here to
eliminate confusion which may arise due to conflicting definitions. These defintions 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

Volume

NIA

Finder Info

NIA
NIA
NIA

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.
PPS will honor the following attributes:
Read Only
Delete Inhibit
June 9, 1993

PFS will not allow writes to the file
PFS will not allow the file to be deleted
Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Rename Inhibit
Copy Protect
Directory

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.
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:
HOST
CREATOR
NOS

7 .3 .4

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

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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

obtaining file characterisitics (which may only be imporatant if the file is actually to be
accessed).
PFS provides this function by using two dispatch vectors, the main library dispatch
vector and a subset data path dispatch vector. Libraries which do not need the additional
datapath claim function should leave this field defaulted which will cause PFS to
dispatch thru the main vector.
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_open() function. This routine is called from PFS_open() and may return a
subset data path dispath vector address in the PFS_FID structure.

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 tradeoffhere is that
record formats may need to be checked on every access and an additional
call is placed in the data path.
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_open() 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).

Figure 7-1:
June 9, 1993

File System Structure Overview
Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PATHWORKS
File Interface

··~~

Path/rime
Libraries

Data Cache

......
~~
..I.

.....
....

••
~

File System
Libraries
""""

7 . 4 .1

Top level interface

The top level interface provides argument checking and dispatch functions to the
appropriate FSLIB. 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 FSLIB
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 FSLIB_init routine with its other variants.
This mechanism allows 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 FSLIB for a given path and dispatch FSLIB functions to
handle PFS functions.
June 9, 1993
Digital Confidential - 3rd Party Restrictions Apply
26

PATHWORKS File System

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_ENTstructure 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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

functions for handling various client anomalies 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 theu PFS_readdesc
and PFS_writedesc functions.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PFS, Data Cache and File System Library Interfaces

Figure 7-2:

PFS_open()

PFS_readdesc()
PFS_releasedesc()
FSLIB_opendesc()
PFS_read()
FSLIB_readdesc()
Data Cache
PFS_getcachedesc()
FSLIB_writedesc()
PFS_writedesc()
FSLIB_closedesc()
PFS_write()

PFS_close()

The PFS file access routines and their interaction with data cache functions are briefly
described below:
PFS_open

This function must be issued prior to any cache access. The
function will establish a data cache "handle" for use by cache
access routines. The handle is stored internally and is
referenced by the open file PFS_FID structure.

PFS_read

Read bytes of data and copy the result to the caller's buffer.
The function uses the data cache intrface internally.

PFS_write

Write bytes of data from the caller's buffer. The function
uses the data cache interface internally.

PFS_readesc

Read bytes of data and return a buffer descriptor pointing to
data cache blocks containing the requested data. This is a
direct interface to the data cache. No data is actually
transferred. The data cache blocks are "locked down" to
prevent reuse while the descriptor holder is processing the
data.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PFS_releasedesc

Release a set of cache buffers pointed to by descriptor.

PFS_getcachedesc

Obtain a buffer descriptor pointing to data cache blocks. This
function is used prior to obtaining client write data, thereby
filling the data cache directly. Data bytes prior to the first
byte of the write range will be read from the file. Data bytes
after the last byte of the write range will also be read from
the file (if not after EOF). The most efficient use of the cache
is to always write full cache blocks on cache block
boundaries as this will eliminate the need to fill buffers. The
cache buffers are "locked down" until a write function or a
release function is issued.

PFS_writedesc

Release written cache blocks pointed to by descriptor or (less
efficient) copy bytes from a set of general buffers to the data
cache. Servers should always preallocate cache buffers by
using PFS_getcachedesc() where possible. This eliminates
the need to obtain buffers during the write function and also
eliminates the need to copy data.

PFS_canceldesc

Release descriptors obtained for write with no modification.
This function is used to back out of a write sequence when
errors are detected.

PFS_close

Release the cache file handle. All buffers must be flushed
prior to close or as part of the function.

Descriptor read sequences are as folllows:
PFS_readdesc(fp, size, offset, desc );
PFS_releasedesc(fp, desc);

I* Obtain a set of buffers containng
data and lock down in cache *I
I* Process buffer *I
I* Release the set of buffers *I

Descriptor write sequences are as follows:
PFS_getcachedesc(fp, size, offset, decs);
PFS_writedesc(fp, offset, desc);

/*Obtain a set of buffers containing
valid data outside the write range *I
I* Fill the write range *I
/*Mark the buffers valid and release
them*/

or:
PFS_getcachedesc(fp, size, offset, decs);
PFS_canceldesc(fp, offset, desc);

7 .5

/*Obtain a set of buffers containing
valid data outside the write range *I
I* Fill the write range *I
/*Cancel the write*/

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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

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. PFS itself does not use the contents of these structures. Rather it passes
all requests for information contained in these structures to the file system library. The
file system library needs to provide the mechanisms to guarantee the contents are
current.
The following section define the data structures which are seen outside of PFS. Many if
the fields of these data structures are not intended for direct use by servers. Many fields
are file system specific and will vary in format and/or content between file systems.
These fields are noted in the following descriptions.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

7.S.1

PFS_PATHID

The PFS_PATHID structure is used to hold mapped path information. This structure is
returned by PFS_getpathidO and is used as a file specification for all PFS 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 server may modify the security_mode field of the PFS _PATHID structure to effect
"per root" host security models.

Figure 7-3:

Format of the PFS_PATHID structure
0
4

funcptrs

fullpath[256]

260

shortpath
endtreetop
fsflags

264
268
272

status (PFS _STAT)

511
515

diridptr

fsbuf

reservedl

I security_mode l

fsop

namespace

cp
fsstatus
reserved

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

771
775
779
783

PATHWORK.S File System

Table 7-3:

Contents of the PFS_PATHID structure

Field Name

Description

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.
Resolved native file specification. This
buffer holds the name of the host file or
path which maps to the specified client
path.
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.
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.
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.
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 PFS. It
is maintained by the file system library.
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.
This is a holding buffer for file system
library mapping functions. This buffer is
used to pass information between PFS and
file system libraries.
Identifies the namepsace in which this path
is operating.

fullpath

shortpath

endtreetop

fsflags

status

diridptr

fsbuf

namespace

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-3 (cont):
fsop
security_mode

fsstatus

June 9, 1993

Contents of the PFS_PATHID structure
File system operation when error occured.
This field may be logged by servers but
should not be used otherwise.
Path security mode. Servers may set this
after issuing a PFS_getpathid() function to
set a share specific security mode. PFS
always initializes this field to the global
security mode, established by
PFS_setsecuritymode().
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.
File system error status. This field is file
system specifiec and may be logged by
servers. This field should not be used
otherwise.

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

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.

Figure 7-4:

Format of the PFS_FID structure

back

0
4

funcptrs

forw

12
status (PFS_STAT)

fd
fdinfo

251

stream

259

offset
cache_id

263

255

267
271

refcnt

nompx

275

oflag
mapaddr

279
280

maplen

284

fsflags

288

endtreetop

292

flags

reservedl

security_mode

fsop

namespace

296

300

fsstatus

304

dpfuncptrs

308
312

fullpath[256]

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-4:

Contents of the PFS_FID structure

Field Name

Descr1pbon

forw

Forward link pointer. This field is not
currently used by PFS.
Back link pointer. This field is not currently
used by PFS.
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.
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 PFS.
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.
Data stream identifier. May be
PFS_PRIMARY or PFS_RESOURCE
representing the data or resource streams of
a file.
Current stream offset in file.
32 bit cache handle associated with the file.
This handle must be used for all cache
references.
Number of servers which are referencing
this shared file.
Counter to inhibit multiplex closing of this
file. This field is not used by PFS.
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.
File has manditory locking set.
File has been modified.
File memory map address. This feature is
not supported by PFS.
Length of memory map. See above.
Pointer to file system library flags in
PFS _LIB _ENT structure for the file system
which claimed this file.
This field is not used by PFS.
Namespace in which this file was opened.
File system operation when error occurred.
This field may be logged by servers but
should not be used otherwise.

back
funcptrs

status
fd

fdinfo

stream

offset
cache_id
refcnt
nompx
oflag

flags.mandlock
flags .dirty
mapaddr
maplen
fsflags
endtreetop
namespace
fsop

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-4 (cont):

Contents of the PFS_FID structure

Field Name

Description

security_mode

Path security mode. This field is copied
from the pathid structure when the file is
opened or created.
Claim parameter. This parameter is copied
from the associated PFS _PATHID structure
and is made available to file system libraries
thru this offset.
File system function status. This field may
be logged by servers but should not be used
otherwise.
Datapath dispatch vectors. This vecor is a
subset of the main library dispatch vector
and is used to handle file system specific
data path functions. If this field is zero,
datapath functions will be dispatched thru
the main vector. If this vector is specified, it
completely overrides the main dispatch
vector for datapath functions, i.e. there is
no hierarchy implied or partial replacement
of functions.
Copy of the PFS_PATHID fullpath buffer.

fsstatus
dpfuncptrs

fullpath

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7.5.3

PFS_ATTR

The PFS_ATIR 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.

Format of the PFS_ATTR structure

Figure 7-5:

0
4

mask
dirid

btime
create

12
16

finder_info[32]

attr_bits
parentid

52
56

pro_dos_info[6]
reserved

pro_dos_info

reserved!

reserved

access
modify

76
reserved2[24]

Table 7-5:

Contents of the PFS_ATTR structure

Field Name

Description

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-5 (cont):

Contents of the PFS_ATTR structure

Field Name

Description

dirid

Directory ID associated with a directory
path or file ID when associated with a file
path. This field carries the 32 bit Macintosh
directory or file ID. This field may or may
not have significance for other file services.
Backup time in namespace specific format,
i.e. DOS, MAC
Create time in namespace specific format.
32 bytes of information associated with the
Macintosh Finder. This filed has no
meaning for non Macintosh clients.
File has been archived.
File is not visible to directory list
operations.
File is a system file.
File can not be renamed. See
PFS_rename().
File can not be deleted. See PFS_delete().
File can be copied with atomic copy
function. See PFS_copyfile().
File can not be written. See PFS_open().
File is a Macintosh application.
File can be open by multiple readers. This
bit only has significance if the mac_appl bit
is also set.
File can not be purged. See PFS_purge().
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.
Netware index file. This bit is always 0.
Netware transaction tracking enabled.
Netware read auditing enabled
Netware write audit enabled.
Reserved bits for Netware.
File needs to be backed up. This is a client
specific field, i.e. it has not relationship to
VMS backup attributes of a file.
Parent directory ID. This field caries the 32
bit Macintosh file ID. It may or may not be
applicable to other file services.
Macintosh specific data.
File access time in Unix format.
File modification time in Unix format.

btime
create
finder_info
attr_bits.archive
attr_bits.hidden
attr_bits .issystem
attr_bits.no_rename
attr_bits.no_delete
attr_bits.no_copy
attr_bits.read_only
attr_bits .mac_appl
attr_bits .multi_user
attr_bits .no_purge
attr_bits .exec_only
attr_bits.nw_indexed
attr_bits.nw_transact
attr_bits.nw.:-rd_audit
attr_bits .nw_ wr_audit
attr_bits .nw_reserved
attr_bits.backup_needed
parentid
pro_dos_info
access
modify

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7.5.4

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 defined
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.

Figure 7-6:

Format of the PFS_STAT structure
mask

0
4

stat (struct stat)

gen

stream

p_ino

p_gen

count
dir_cnt

file_cnt

83
91

attrs (PFS_ATTR)

191
file_id_overlay[48]

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-6:

Contents of the PFS_STAT structure

Field Name

Description

mask

Mask indicating the validity of members of
this structure
Contains a 11 struct stat" structure defining
various low level file attributes.
File generation number. This field is
maintained by the file system library and
may or may not be supported.
Data stream associated with this file. This
field may have significance in file systems
which implement serparate files for each
data stream supported. This field is
maintained by the file system library and
may or may not be supported.
Parent INODE. This is a Unix concept and
is only supported by Unix file system
libraries.
Parent generation number. This field is
maintained by the file system library and
may or may not be supported.
Number of files contained in a directory.
This field is intended for export to server to
support the Macintosh offspring count.
This field is not supported for non Unix
based file systems.
Directory offspring. This field is not
supported for non Unix based file systems.
File count. This field is not supported for
non Unix based file·systems.
PFS_ATTR structure.
48 byte file identification buffer. This
buffer is file system specific.

stat
gen
stream

p_ino
p_gen
count

dir_cnt
file_cnt
attr

file_id_overlay

As can be seen from the above descriptions, this structure is of little value outside PFS
with the exception of the PFS_ATTR 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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

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.

Figure 7-7:

Format of the PFS_NAMEID structure

dir

0
4
8

file

filename

ext

ver

parent

node
device

devicelen

nodelen

filelen

dirlen

extlen

filenamelen

parentlen

verlen

namespace

I flag_bits

48
52

path[256]

Table 7-7:

Contents of the PFS_NAMEID structure

Field Name

Description

node

Pointer to the node name in the path buffer.
If the node name is not present or if the
namespace does not support node names,
this field will be NULL.
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.
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.

device

dir

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-7 (cont):

Contents of the PFS_NAMEID structure

Field Name

Description

file
filename
ext

Pointer to the start of the file specification.
Pointer to start of filename component.
Pointer to start of extension component.
· The pointer includes the leading extension
deliminter.
Pointer to the file version number.
This field is obsolete. Use the
PFS_pathfunc() function to extract the
parent specification.
Length of the name name string. This
length includes the trailing node delimiter.
Length of the device string. The length
includes the trailing device delimiter.
Length of the dirctory string. The length
includes the trailing directory delimiter.
Length of the whole file specification,
including extension and version.
Length of the filename string.
Length of the extension string.
Length of the version number.
This field is obsolete. Use the
PFS_pathfunc() function to extract the
parent specification.
This bit will be set if the path is specified as
a directory path. This bit does not indicate
the path actually exists as a directory.
This bit will be set if any wildcard
characters appear in the path.
This bit will be set if any wildcard
characters appear in the file specification
(filename, extension or version).
This bit will be set if any wildcard
characters appear in the path specification
(node, device or directory).
Namespace in which path was parsed.
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.

ver
parent
nodelen
devicelen
dirlen
filelen
filenamelen
extlen
verlen
parentlen
flag_bits.isdir
flag_bits .iswild
flag_bits .iswildfile
flag_bits .iswildpath
namespace
path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .5.6

PFS_CWD

The PFS_CWD structure holds the data associated with the current working directory.

Figure 7-8:

Format of the PFS_CWD structure
0
name[256]

funcptrs

256

fsflags

260
264

security_mode

265
file_id_overlay[48]

Table 7-8:

Contents of the PFS_CWD structure

Field Name

Description

name
funcptrs

Buffer containing the full path string.
Function pointers for file system in which
default exists.
Pointer to file system flags in the
PFS_LIB_ENT structure for the file system
which claimed the default.
Path security mode.
48 byte file identification buffer. The format
of this buffer is file system specific.

fsflags
security_mode
file_id_overlay

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

7 .5. 7

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 PFS_USER structure contains a pointer to an array of host user rights. The rights
are stored in the PFS_RIGHTS structure.

Figure 7-9:

Format of the PFS_RIGHTS structure

1----------------------i_de_n_tifi
__er______________________~10
attributes
_

Table 7-9:

Contents of the PFS_RIGHTS structure

Field Name

Description

identifier
attrributes

32 bit rights identifier.
Rights attributes. This field is not used by
PFS directly.

The PFS_USER structure is obtained via PFS_getuser(). It is the server's
responsibility to map clients to host users and obtain this structure. The PFS_USER
structure is presented to all file system functions which check access or host user
quotas.
The host user name and host user account are returned in this structure for various
accounting funtions.

Figure 7-10:

Format of the PFS_USER structure
rights
uic

0
4

ritlen

8
12

privs
20
usemame[l2]
32
account[9]

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-10:

Contents of the PFS_USER structure

Field Name

Description

rights

Pointer to rights list. This list is an array of
PFS_RIGHTS structures.
Host user identification in uid_t format.
Length of rights list
Quadword privilege mask.
Blank padded host usemame.
Blank padded host account.

uic
ritlen
privs
usemame
account

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .S .8

PFS_LIB_ENT

The PFS_LIB_ENT structure defines the name and capabilities of a file system library.
The library's function dispatch vectors are passed in this structure. This vector provides
the interface to the file system library. The structure is initialized by the file system
when the FSLIB_init function is called (the only external function interface to a file
system library).

Figure 7-11:

Format of the PFS_LIB_ENT structure
fstype

funcptrs

4
8
9

flags

13
flags

18
22

reserved[l2]

Table 7-11:

Contents of the PFS_LIB_ENT structure

Field Name

Description

fstype
funcptrs
flags .unixfs
flags .resource
flags .extattrs
flags .cscreate

Pointer to the name of the library.
Pointer to library dispatch vectors.
Indicates unix file system.
File system support resource forks.
File system support extended attributes.
File system supports case sensitive file
names.
File system is mapped to another file
system.
PFS_STAT elements supported.
PFS_ATTR elements· supported.
File system supports security data.
File system is read only.
Directory paths are not compatible with file
paths and need to be mapped.
File system can propagate NOS security
data on new directory creates.
File system identifier supplied by PFS after
calling FSLIB_init. This identifer must be
used by the file system library to build
unique device identifiers.

flags.mappedfs
flags .statmask
flags.attrmask
flags .security
flags .read_only
flags.mapdirs
flags .propsec
id

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .5 .9

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.

Figure 7-12:

Format of the PFS_IDENT structure

length

dvi
16

fid

did

Table 7-12:
Field Name
length
dvi
fid
did

June 9, 1993

Contents of the PFS_IDENT structure
Description
Length of device name. Limit of 15 bytes.
Device name string. This string is not
counted and is limitedto 15 bytes.
6 byte file identification.
6 byte directory identification.

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .5.10 PFS_ROOTID
The PFS_ROOTID structure is used to hold a translated root specification. This
specification is used as the path bias for all client path translations. This corresponds to
the LanManager "share" or Macintosh "volume". This structure is initialized by the
PFS_getrootid() function and may be used as the root specification for
PFS_getpathidX(). This mechanism optimizes file systems which may claim any path
based on the root specification.

Figure 7-13:

Format of the PFS_ROOTID structure
funcptrs
fsflags

reserved

0
4
security_mode 8

12
16

reserved 1[16]

32
fullpath[256]

Table 7-13:

Contents of the PFS_ROOTID structure

Field Name

Description

funcptrs
fsflags
security_mode

File system library function pointers.
Pointer to file system library flags.
Root security mode. This field may be
modified by the server to effect root specific
security models.
File system claim parameter.
Full translated root specification

cp
fullpath

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

7 .5.11 PFS_EAOPS
The PFS_EAOPS (Extended Attribute Operations) structure is used to specify a set of
OS/2 extended attributes or LanManager security data records. There are five structures
used in the PFS_EAOPS interface. The PFS_EAOPS structure is the top level
structure. It contains pointers to two structures, the PFS_GEALIST (Get Extended
Attributes List) structure and the PFS_FEALIST Found Extended Attributes List)
structure. The PFS_GEALISTstructure contains a pointer to an array of PFS_GEA
(Get Extended Attributes) elements. The PFS_FEALIST structure contains a pointer a
buffer which contains an array of PFS_FEA (Found Extended Attributes) elements as
well as additional space for returned attributes. The arrangement of structures is shown
in the description of PFS_getextattr().

Figure 7-14:

Format of the PFS_EAOPS structure

-------------------g-eali_·_s~---------------------11~
8
I
fealistp

erroffset

Table 7-14:

Contents of the PFS_EAOPS structure

Field Name

Description

gealistp
fealistp
erroffset

Pointer to the PFS_GEALIST structure.
Pointer to the PFS_FEALIST structure.
If an errors in a PFS_EAOPS function, this
field will point to the last successfully
processed entry. The PFS_GEA index and
PFS_FEA index are always the same.

The PFS_FEA structure contains the return attributes. The first region of the
PFS_FEALIST list buffer contains an array of PFS_FEA elements. The elements are
arranged in the same order as the PFS_GEA array when named attributes are requested.
If all attributes are requested, the arrangement of attributes in the PFS_FEALIST list
buffer will be the order in which they are found on the file. This order is not predictable
and may change when attributes are added, modified or deleted.
Each PFS_FEA element contains two pointers into the data region of the
PFS_FEALIST list buffer, one for the attribute name and the other for the attribute
value. Names and values are arbitrary binary strings and are located with a simple
binary comparison. The length of each string is returned in the PFS_FEA element.

Figure 7-15:

Format of the PFS_FEA structure
vallen

June 9, 1993

name

0
4

value

maxlen

namelen

flag

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-15:

Contents of the PFS_FEA structure

Field Name

Description

flag

Attribute flags. This field is not currently
used.
Length of the return attribute name.
Length of the return attribute value.
Pointer to the attribute name buffer.
Pointer to the attribute value buffer.
This field is for internal use only. It is not
currently used.

namelen
vallen
name
value
maxlen

The PFS_FEALIST structure describes the list buffer and contains the total count and
size of data returned. The caller must initialize this structure to define the total size of
the list buffer and how many PFS_FEA structures may be placed in the buffer. The
buffer itself needs no initialization.
The caller must initialize the len field to indicate the total size of the buffer. The count
field must be initialized to the number of PFS _FEA elements which may be placed in
the buffer. The PFS_FEA elements always start at the beginning of the buffer and are
arranged to form a contiguous array.
The space remaining in the buffer (len - count* sizeof(PFS_FEA)) is used as storage
space for attribute names and values.
PFS will return the total number of bytes written to the buffer in totlen and the total
number of PFS_FEA elements used in totcnt.

Figure 7-16:

Table 7-16:

Format of the PFS_FEALIST structure
len

totlen
cnt

totcnt

8
12

list

Contents of the PFS_FEALIST structure

Field Name

Description

len

Total length, in bytes of the buffer pointed
to by the "list" field.
Total length of all buffer space either used

totlen
cnt

~B~etl1ltim

jmctbeskillifm

~trecihtdilmmmto:Hlthtbfiffie:tfusn
~drmf ontPFSiz~¥8Q.~

this field indicates to minimum size of the
buffer to complete the operation.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

Table 7-16 (cont):

Contents of the PFS_FEALIST structure

Field Name

Description

totcnt

Total number of attributes returned in the
buffer. If the function fails with
PFS_BufferTooSmall this field indicates
RuimDin1iJitDmbuffitbamaintrig~ch need
RF&i'.ijiiiililCiients (elements will be

list

The PFS_GEA structure contains an attribfitetnattml~kJmltfmdflhe~a.binary
string of arbitrary length. The caller may build an array of PFS_GEA elements to
perform operations on multiple attributes. The array is passed to PFS thru the
PFS_GEALIST structure list field.

Figure 7-17:

Format of the PFS_GEA structure
0
1

namelen

Table 7-17:

Contents of the PFS_GEA structure

Field Name

Description

namelen
name

Length of the attribute to match
Attribute name buffer specifying the
attribute name to be selected.

The PFS _GEALIST structure defines the attributes to be located for a get operation.
The structure contains the total length of the array (PFS_GEA elements plus attribute
name lengths) and the countofPFS_GEA elements in the array. The base of the array
is passed in the PFS_GEALIST list field.

Figure 7-18:

Format of the PFS_GEALIST structure

1------------------------:_:
______________________
list
Table 7-18:

----11~8
_

Contents of the PFS_GEALIST structure

Field Name

Description

len

Total length, in bytes of the PFS_GEA
array.
Count of elements in the PFS_GEA array.
Pointer to the PFS_GEA array.

cnt
list

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .5.12 PFS_MACSECUR
The PFS_MACSECUR structure is used for Macintosh security operations,
PFS_getsecurity(), PFS_setsecurity() and PFS_checksecurity(). The structure contains
the Macintosh user ID, group ID and permissions allowed for the various Macintosh
security classes. PFS does not interpret the contents of this structure. However, it does
undertand the format and applies the supplied mask such that individual fields may be
modified without a read-modify-write sequence.

Figure 7-19:

mask

Table 7-19:

Format of the PFS_MACSECUR structure
owner_id

group_id

I world_rights l group_rights l owner_rights

Contents of the PFS_MACSECUR structure

Field Name

Description

owner_id
group_id
owner_rights
group_rights

Macintosh file owner ID.
Macintosh owner's group ID.
Access rights for the file owner.
Access rights for the members of the file's
group.
Access rights for all others.
Mask of valid elements for get/set.

world_rights
mask

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 . S .13 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.

Figure 7-20:

Format of the Stat structure

st_nlink

st_mode

0
4
8

st_uid

st_nlink

st_gid

st_uid

st_dev
st_ino

st_rdev

st_fab_mrs

June 9, 1993

st_size

st_atime

st_mtime

st_ctime

st_fab_fsz

stJab_rat

st_fab_rfm

st_rsvd

st_fmt

st_fab_mrs

Digital Confidential - 3rd. Party Restrictions Apply

PATHWORKS File System

Table 7-20:

Contents of the Stat structure

Field Name

Description

st_dev

Longword device identifier. This is
currently defined as a pointer to a 16 byte
structure. This field points to the st_rdev
field.
32 bit file identifier. This field is maintained
by the file system library and is NOT
unique across devices.
Unix file format. PFS sets the S_IFMT
field to indicate the file format. PFS uses
thhe value S_IFDIRto determine if a file is a
directory and assumes all file systems will
set it accordingly. (It is not sufficient to use
the PFS_ATTR directory bit as not all file
services maintain this attribute). The file
protection is converted to Unix format and
stored here.
Unix. This field may be set by file system
libraries but is otherwise unused.
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.
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.
This field contains the device lock name,
currently 16 bytes.
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
limited significance outsize of PFS.
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.
Modification time in Unix format. This is
the host file system modification time. See
above disclaimer.
Creation time in Unix format. This is the
host file system creation time. See above
disclaimer.

st_ino
st_mode

st_nlink
st_uid

st_gid

st_rdev
st_size

st_atime

st_mtime
st_ctime

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

Table 7-20 (cont):

Contents of the Stat structure

Field Name

Description

st_fab_rfm

ODS-2 record format. This field is used by
the ODS2 file system library and has no
significance outside the library.
ODS-2 record attributes. This field is used
by the ODS2 file system library and has no
significance outside the library.
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.
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.
Native file format.

st_fab_rat
st_fab_fsz

st_fab_mrs

st_fmt

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 •5 .14 Dirent 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.

Figure 7-21:

Format of the Dirent structure
0

d_ino
d_reclen

1 d_namelen

d_name
d_namelen+1
file_system_specific

Table 7-21:

Contents of the Dirent structure

Field Name
d_ino

d_reclen
d_namelen
d_name
file_system_specific

June 9, 1993

Description
Opaque quantity. This field contans file
location informaton used by
PFS_dentpathid() to improve directory
search performance.
Length of the entire record, rounded to the
next longword.
Filename length. This field is the byte count
of the filename.
Filename buffer. This field contains the
actual filename in the requested namespace.
File system specific data. This buffer is
used to optimize access to the file contained
in the d_name buffer. The size of this
buffer and format is file system specific.

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7 .5.15 Utimebuf structure
The timbuf structure is used by PFS_utime() and PFS_futime(). It contains the last
access time and last modification time for a file.

Figure 7-22:

Format of the Utimbuf structure

1-----------------------ac_mn_·_e_________________________
modtime
_4

Table 7-22:

7 .6

Contents of the Utimbuf structure

Field Name

Description

actime
modtime

Access time in Unix format.
Modify time in Unix format.

Function error codes

PFS function may return error codes using one of two methods, PFS_errno or as the
return value of a function. The initialization parameter [PFS]RETURN_ERRNO selects
which method will be used.
Standard function return codes are defined below. The codes marked with an asterisk
are only valid when [PFS]RETURN_ERRNO =0. The PFS_errno codes will be
stored in the global PFS_errno (established with PFS_setcontext) if
[PFS]RETURN_ERRNO =0. The PFS_errno codes will be returned as the value of a
function if [PFS]RETURN_ERRNO = 1.
PFS_REVTAL codes:
PFS_SUCCESS

Operation completed normally

PFS_FAILURE *

Operation failed

PFS_FSSTATUS codes:
PFS_EXISTS

Path exists as specified.

PFS_NOEXISTS

Path does noit exist but the parent path does.

PFS_FAILED *

Alternate failure status.

PFS_CHKSTATUS codes:
PFS_ACCESS

Security check access allowed

PFS_NOACCESS

Security check access not allowed.

PFS_CHKFAILED *

Alternate failure status

PFS_ermo codes:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

7. 7

PFS_InvalidParameter

Parameter supplied to function is invalid

PFS_BufferTooSmall

Buffer supplied to fnction is too small for current
operation.

PFS_ResourceData

Source file has resource data and destination file
system does not support resource data.

PFS_ExtendedAttrs

Source file has extended attributes and destination
file system does not support extended attributes.

PFS_NotSupported

Function is not supported in current file system.

PFS _NoStartOffset

No start offset was supplied with function.

PFS_ShrinkFailed

Attempt to truncate a file has failed.

PFS_GrowFailed

Attempt to extend a file has failed.

PFS_NoCwd

No root was specified for a function and no working
directory has been extablished.

PFS_NoSuchStream

Attempted access to a non existant file stream.

PFS_SecurityData

Source file has security data and destination file
system does not support securty data.

PFS_BadPath

Path does not exist.

PFS_BadFile

File does not exist.

PFS_BadFd

An invalid file pointer was supplied.

PFS_FileLocked

Access to specified range is current not allowed due
to a conflicting lock.

PFS _GeneralFailure

Function failure not related to a predefined error
code.

PFS_NoAccess

Access to file or data is not allowed.

PFS_NoMemory

Insufficient memory for current operation.

PFS_DiskFull

Disk is full or exceeded disk quota.

PFS_AccessDenied

Access to a file or data is not allowed.

PFS_ParameterError

An invalid parameter was supplied to a function.

PFS_Actionlnhibited

File attributes prohibit specified operation.

Initialization parameters

PFS initialization parameters are described in Appendix F.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PFS 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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .1 •
8 •2 •

PFS_access *
PFS _faccess *

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
perfor:mance 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, int perms, PFS_USER
*user)
PFS_RETVAL PFS_faccess (PFS_FID *fp, 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().

perms

Unix style permission code. The following bits are defined:

000
001
002
004

File exists
Execute access
Write/Delete access
Read access

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Translations taken from "Programming in VAX-11 C".

Return values:
PFS_SUCCESS
June 9, 1993

Access is allowed
Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PFS_FAILURE

June 9, 1993

No access or invalid path

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 •3 .

PFS_canceldesc *

Description:
PFS_canceldesc is used to cancel a set of cache buffers obtained via
PFS_getcachedesc(). This function is used to complete a cache write sequence
abnormally.
The normal sequence for cache writes in PFS_getcachedesc() followed by a
PFS_writedesc(). If the write data can not be obtained or if there is an error
during the processing of write data the descriptors may be released thru
PFS_canceldesc(). One of the two functions, PFS_writedesc() or
PFS_canceldesc(), must be called after calling PFS_getcachedesc().

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_canceldesc (PFS_FID *fp, struct buffer_descriptor **desc)

Arguments:
fp

Open file pointer for file in which write was initiated.

desc

Address of pointer to cache descriptor list to cancel.

Return values:
PFS_SUCCESS

Descriptors returned to cache

PFS_FAILURE

Invalid file pointer or failure to release descriptors

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.4.
8 .5.

PFS_chdir
PFS_fchdir

Description:
PFS_chdir sets the current working directory. Note that the process structure of
PFS 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 PFS be routed thru the
server to allow these tasks to be completed.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_chdir (PFS_PATHID *pathid, PFS_USER *user)
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.

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Default set

PFS_FAILURE

Invalid pathid or fp

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .6.

PFS_checksecurity

Description:
PFS_checksecurity will traverse the directory structure specified by the pathid
structure and call an action routine with the requested security data at each level.
The action routine determines if the requested access is to be allowed or if
additional path members must be checked.
The action routine is specified as follows (note the only difference is the
interpretation of the security block:
For PFS_LMXSECURE
PFS_CHKSTATUS rtn (PFS_PATHID *pathid, PFS_EAOPS *eaopsp, param)
For PFS_MACSECURE
PFS_CHKSTATUS rtn (PFS_PATHID *pathid, PFS_MACSECUR *eaopsp,
param)
The routine may return one of the following values:
PFS_ACCESS

Access is allowed, no further checks are necessary

PFS_NOACCESS

Access is not allowed, no further checks are necessary

PFS _CONTINUE

Access at this level is allowed, continue with the next level in
the path.

PFS_CHKROOT

Access is allowed at this level, skip all intermediate levels
and check the root directory.

PFS_CHKFAILED

Check function failed. Access is not allowed.

The parameter passed to the action routine is likley a structure pointer which will
hold the requested access, directory level, user ID or any information the server
needs to perform the check.
The PFS_LMXSECURE and PFS_MACSECURE algorithms differ in that
PFS_LMXSECURE space will return failure if all levels have been checked and
access has not been granted. PFS_MACSECURE will return success if all levels
are checked and access has not been denied.

NOTE
To promote the separation of security space and the file system, the
algorithmic difference described above could be specified in a parameter
to the function. This is not deemed necessary at this time.

Synopsis:
#include <pfs .h>
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

PFS_CHKSTATUS PFS_checksecurity (PFS_PATHID *pathid,
PFS_SECURSPACE *securspace, PFS_EAOPS
*eaopsp, PFS_CHKSTATUS (*rtn)(), unsigned param)
PFS_CHKSTATUS PFS_checksecurity (PFS_PATHID *pathid,
PFS_SECURSPACE *securspace, PFS_MACSECUR
*eaopsp, PFS_CHKSTATUS (*rtn)(), unsigned param)

Arguments:
pathid

Resolved pathid pointing to file or directory to be checked.

securspace

Security space. PFS_LMXSECURE and
PFS_MACSECURE are defined.

eaopsp

The eaopsp member points to the security data structure as
defined by PFS_getsecurity(). The structure is either a
PFS_EAOPS structure (LMX security space) or a
PFS_MACSECUR structure (Macintosh security space).

rtn

Action routine to call

param

Parameter to pass to routine

Return values:
PFS_ACCESS

Access allowed

PFS_NOACCESS

Access not allowed

PFS_CHKFAILED

Function failed

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8. 7.
8 .8.

PFS_chmod
PFS_fchmod

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_USER *user)
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

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

8.9.
8.10.

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,
PFS_USER *user)
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

user

Pointer to PFS_USER structure previously obtained with
PFS __getuser().

Return values:
PFS_SUCCESS

Owner changed

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .11.

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_FAILURE

Invalid file pointer

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

8 .12.

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.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.13.

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, PFS_USER *user)

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.

action
June 9, 1993

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
attributes streams and the
source file has either then fail.

Action to be taken if the destination file already exists.
Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

user

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.

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

File copied

PFS_FAILURE

Invalid path, conflicting file systems or copy protect

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.14.

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.
PFS_create accepts the user ID to establish the host owner. This is generally the
mapped host user specified by the PFS _USER parameter. If the owner is not
specifed the default server process owner is used. The group ID may supply
additional information about the owner. This field is not used for VMS based
servers. The owner is only set if the file is actually created. An existing file's
owner will not be modified.
PFS_create accepts the default file protection to be applied to a new file. The file
protection is only set if the file is created. An existing file's protection will not be
modified.

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,
PFS_USER *user)

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:

June 9, 1993

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().

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System .

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

File created

PFS_FAILURE

Invalid path or file exists and PFS_MAKENEW specified

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

8 .1 S.

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 ??] . If no_purge is not set then the file is actually
deleted.

NOTE
The PFS_ATTR no_purge bit is used to support Netware's
SCAV ANGE function. This feature is not currently supported. This
feature is not related to the Macintosh concept of a trash can in which
deleted files are moved to a trash folder. The Macintosh server must
provide this function in terms of PFS_rename.

Synopsis:
#include <pfs .h>
PFS_RETV AL PFS_delete (PFS_PATHID *pathid, PFS_USER *user)

Arguments:
pathid

Resolved pathid structure from PFS _getpathid().

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

File deleted

PFS_FAILURE

No access, file not found

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .16 • PFS_dentpathid *
Description:
PFS_dentpathid converts a directory "struct direntn 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_PATHID *pathid)

Arguments:
fp

Open file pointer to directory to be searched

dirent

Struct dirent from PFS_getdents().

pathid

Resulting PFS_PATHID 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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .1 7.

PFS_didpathid *

Description:
PFS_clidpathid 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_clidpathid (PFS_CWD *clirid, char *path,
PFS_NAMESPACE namespace, PFS_PATHID *pathid)

Arguments:
clirid

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .18.

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

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 argument specifies
the volume.

PFS_DIRID_CLOSE

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

PFS_DIRID_CLEANUP

Close all directory IDs.

root

Volume root directory.

dirid

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.19.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .20. PFS_filesize
8. 21 • 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:
#include <pfs .h>
PFS_RETVAL PFS _filesize (PFS_PATHID *pathid, PFS _DATA_STREAM
stream, off_t *size, PFS_USER *user)
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

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Return size is valid

PFS_FAILURE

Invalid file pointer

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 •2 2 • PFS _freeuser *
Description:
PFS _freeuser releases the structure obtained with PFS_getuser(). This function
must be called when a PFS_USER structure obtained with PFS_getuser() is no
longer needed. The PFS _USER structure is dynamically allocated and PFS uses
its own memory allocation routines. This function provides the only mechanism
to dispose of the PFS _USER structure.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_freeuser (PFS_USER *user)

Arguments:
user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Disposed of PFS_USER structure

PFS_FAILURE

Error in dispose

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .23.

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_FAILURE

Invalid file pointer

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .24.

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

buflen

Length of return buffer

Return values:
PFS_SUCCESS

Path written to buffer

PFS_FAILURE

Invalid file pointer to buffer too small

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.25.
8 .26.

PFS_getattr
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_PATHID *pathid, unsigned long mask,
PFS_ATTR *attrp, PFS_USER *user)
PFS_RETVAL PFS_fgetattr (PFS_FID *fp, unsigned long mask, PFS_ATTR
*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_ATTR structure. This mask has the
exact same format as that in the PFS_ATTR structure.

attrp

Pointer to return attributes structure.

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Attributes updated

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.27.

PFS_getcachedesc *

Description:
PFS_getcachedesc will obtain a set of cache buffer descriptors to be used as
write buffers. The buffers are released to the cache with PFS_writedesc(). The
cache buffers will contain valid data from the cache block start to the offset
specified by the difference between the offset and the relative offset in the cache
block. The same applies to the data in the last block of the descriptor beyond the
write range ..

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

Arguments:
fp

Open file pointer.

nbytes

Size of write range.

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].

Return values:
PFS_SUCCESS

Data read

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.28.

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.

Figure 8-1: Format of the File Comment Buffer

Length

Comment data (maximum length 199 bytes)

NULL

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

Arguments:
pathid

Resolved pathid from PFS_getpathid().

comment

Return buffer for comment.

buflen

Length of return buffer.

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Coment returned

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.29.

PFS_getcwd

Description:
PFS_getcwd returns the current working directory.

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

Arguments:
cwd

Pointer to working directory structure

Return values:
PFS_SUCCESS

Directory returned

PFS_FAILURE

No directory set

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 .30.

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.
The offset argument must be set to zero before the first call to PFS_getdents is
made. PFS_getdents will maintain its current context in this location. The
location may be cleared to reset the directory list. Any other value is undefined
and will cause PFS_getdents to behave unpredictably.
The contents are returned mapped to the namespace supplied. All filenames are
returned in the semantics of the supplied namespace, regadless of whether they
may be legal in that namespace. It is the server's responsibility to filter the
contents of the dirent buffer.

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

Open file pointer for the directory to be enumerated.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8. 31 • PFS_geterrno *
Description:
PFS_geterrno is used to obtain the last error encountered by PFS. The global
location PFS_errno has been replaced by this call to facilitate threaded execution
and to eliminate global locations shared between facilities.
This function is provided for backward compatibility only. PFS may be
configured to return the actual error encountered as the value of each PFS
function. This is the preferred method of error reporting and will become the
only method in future releases.
The use of PFS_geterrno() requires that each thread establish the pointer to its
PFS_errno location via PFS_setcontext(). This must be done on every thread
switch. This is both inefficient and cumbersome for the callers of PFS. This
mechanism will be removed in future releases.

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

Arguments:
None

Return values:
Last error encountered by PFS for the current thread.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8.32.
8.33.

PFS_getextattr
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:

Figure 8-2: Layout of PFS_EAOPS Structures

PFS_EAOPS
gealistp
fealistp
erroffset

PFS_GEALIST

PFS_GEAO

len

namelen

cnt

name

list
PFS_FEA[]
PFS_FEALIST
len
totlen
cnt
totcnt
list

flag
nameIen
vallen
name
value
maxlen
attribute buffer
space (following
array of FEAs)

The PFS_EAOPS structure contains a pointer to the PFS_GEALISTstructure
and the PFS_FEALIST structure. The erroffset member will be written with the
last offset written in the PFS_FEA array if the function fails.
The PFS_GEALIST structure is used to describe names of attributes to be
returned. If all names are to be returned, the pointer should be specified as
PFS_ALLFEAS. The PFS_GEALIST structure contains a pointer to an array of
PFS_GEA elements. Each element of this array is a named attribute. This
structure is read-only to PFS.
The PFS_GEA structure contains a pointer to the name buffer and the length of
the name. Names must be specified explicitly, there is no wildcard matching and
names are matched case sensitive. The array is read-only to PFS.
The PFS_FEALIST structure is used to describe the return attributes array. The
length of the array and the number of elements present is specified in this
structure. The caller must initialize this structure with the total size of the
PFS_FEA buffer and the number of elements in the buffer. The buffer must be
June 9, 1993
Digital Confidential- 3rd Party Restrictions Apply
91

PATHWORKS File System

large enough to hold the number of PFS_FEA elements PLUS additional buffer
space to hold the name and value assigned to each requested attribute. The buffer
space left for names and return values may be calculated as follows:
bytesleft =len - cnt * sizeof(PFS_FEA);
The number of bytes written (or the number of bytes required to complete the
function) will be returned in totallen. The number of matched elements will be
returned in totalcnt. The PFS_FEA buffer should contain the same number of
entries as the PFS_GEA structure. Attributes will be written to the same offset in
the PFS_FEA array as they were requested in the PFS_GEA array. If the
PFS_GEALIST is specified as PFS_ALLFEAS then the PFS_FEA array should
be large enough to hold all expectes attributes. If the buffer is not large enough a
new one may be allocated using the totallen and totalcnt fields returned and the
function may be retried with the larger buffer. Alternatly, the PFS_stat function
may be used to obtain the total byte count of the extended attributes stream. This
function will not return the count of elements.
The PFS_FEA array is written by PFS with the return attributes. It requires no
initialization.

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

Arguments:
pathid

Resolved pathid from PFS_getpathid().

Open file pointer

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].

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Extended attributes written to buffer

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

8 .34.

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 .It>
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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8. 3 5.

PFS_getpathidX *

Description:
PFS_getpathidX resolves a NOS file path given the top of the directory tree, the
NOS path and NOS type. PFS_getpathidX uses the supplied PFS_ROOTID to
locate the file system which handles this path. This allows optimizations for file
system which claim paths based on root specification alone.
PFS_getpathidX calls the following library functions:
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_getpathidX (PFS_ROOTID *rootid, char *path,
PFS_NAMESPACE namespace, PFS_PATH_TYPE
pathtype, PFS_PATHID *pathid)

Arguments:
rootid

Top of directory tree or directory which corresponds to the
volume root. This root is passed in a PFS_ROOTID
struction previously obtained with PFS_getrootid().

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

pathtype

June 9, 1993

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

Type of path to be processed. The following values are
defined:
PFS_FILE_PATH

Path should be found as a file

PFS_DIRECTORY_PATH

Path should be found as a
directory

PFS_ANY_PATH

Path may be found as either.
The search order is always file
first then directory.

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

pathid

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8. 3 6 • PFS_getprintident *
8.37. PFS_fgetprintident *
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 defined in section 7.5.

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

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

Open file pointer.

identp

Pointer to return identification structure.

Returns:
PFS_SUCCESS

Print identification returned

PFS_FAILURE

Insufficient information

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System

8 •3 8 • PFS _getrootid *
Description:
PFS_getrootid will obtain a PFS_ROOTID structure describing the specified
path root. The structure may be used as input to PFS_getpathidX. This
eliminates the need for repetive path claims for file systems which claim paths
based on the root alone.
The PFS_ROOTID structure is defined in section 7.5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_getrootid (char *root, PFS_NAMESPACE namespace,
PFS_ROOTID *rootid)

Arguments:
root

ASCIZ string specifying a native file specification to be used
as the root path.

namespace

Namespace in which this root will operate.The namespace is
used to differentiate basic path types in some file systems.
This may preclude using the same rootid to handle
incompatible namespaces. Currently Macintosh and DOS
paths may not be handled with a common rootid. DOS,
OS/2, VMS and Unix paths may be handled with a common
rootid.

rootid

Return rootid structure.

Returns:
PFS_SUCCESS

Root successfully located.

PFS_FAILURE

Invalid root specification.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System

8 .39.
8 .40.

PFS_getsecurity *
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. This interface does not use the PFS_EAOPS structure.
The buffer supplied will be written with the security data from the Macintosh
ACE.
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.

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

Arguments:
pathid

Resolved pathid structure returned by PFS__getpathid().

Open file pointer

securspace

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

securp

June 9, 1993

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
Digital Confidential - 3rd Party Restrictions Apply

PATHWORK.S File System ·

at offset "ownerlD" and is returned exactly as specified in
the Macintosh ACE. The data is 11 bytes in length.
user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Returned attributes

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

PATHWORKS File System .

8 .41.

PFS_getsecuritymode *

Description:
PFS_getsecuritymode will return the current system security mode. The mode is
one of PFS_HOST_SECURITY, PFS_CREATOR_SECURITY or
PFS_NOS_SECURITY. The system security mode is set by PFS at startup and
may be changed using PFS_setsecuritymode().

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

Arguments:
None

Return values:
System security mode

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

100

PATHWORKS File System

8. 4 2.

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, account and usemame.
It is the callers responsibility to release the memory associated with the

structure.PFS_freeuser() is provided for this purpose. Since PFS uses its own
memory allocation routines PFS_freeuser() must be called to dispose of the
structure when it is no longer needed.

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

Arguments:
usemame

Host usemame for which information is desired

user

Return user structure defining user rights and privileges.

Return values:
PFS_SUCCESS

Obtained user info

PFS_FAILURE

No such user

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

101

PATHWORKS File System

8 .43.

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_LIBRARY: 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_FSLIB .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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

102

PATHWORKS File System

8 .44.

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_WAIT_LOCK dowait, off_t *start)

Arguments:
fp

Open file pointer

type

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

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

offset

Position to start lock.

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.

do wait

The following values are defined:

start

June 9, 1993

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.
Digital Confidential - 3rd Party Restrictions Apply

103

PATHWORKS File System

Return values:
PFS_SUCCESS

Lock set

PFS_FAILURE

Invalid parameters or lock conflict

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

104

PATHWORKS File System

8.45.

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:
PFS_SUCCESS

File position changed

PFS_FAILURE

.Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

105

PATHWORKS File System

8.46.
8.47.

PFS_mapname
PFS_fmapname

Description:
PFS_mapname will translate the last member of a given path to the namespace
specified. The primary purpose of this function is to supply the Macintosh short
name to Macintosh servers.

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:
pathid

Resolved pathid structure from PFS_getpathid()

Open file pointer

namespace

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

106

PATHWORKS File System

8.48.

PFS_mkdir

Description:
PFS_mkdir creates a directory. The host owner is set to that specified as well 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, PFS_USER *user)

Arguments:
pathid

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.

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

Directory created

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

107

PATHWORKS File System

8 .49.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

108

PATHWORKS File System

8 .50.

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:
count

Required number of file descriptors

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

109

PATHWORKS File System

8.51.

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

June 9, 1993

Digital Confidential- 3rd Party Restrictions Apply

110

PATHWORK.S File System

8.52.

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, PFS_USER *user)

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
00010 O_APPEND
01000 O_CREAT
02000 O_TRUNC
200000 O_SHARE

Open the file for read access
only.
Open the file for write access
only.
Open file for both read and
write access.
Open file for append access.
Create stream if it does not
exist
Truncate stream if it exists
Open file for shared access

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.

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

File open

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

111

PATHWORKS File System

8.53.

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 namespace
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

N amespace in which path exists

nameid

Return structure defining the components of the path.

Return values:
PFS_SUCCESS

Path parsed

PFS_FAILURE

fuvalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

112

PATHWORKS File System

8.54.

PFS_pathfunc *

Description:
PFS_pathfunc provides a number of path operations which contain the path
specific knowledge to a set of routines. These routines are collectively called a
Path Library.
PFS_pathfunc is provided to suppliment the path operations which may be
performed directly on the PFS_NAMEID structure. The PFS_NAMEID
structure contains the components of the path and may be used directly to extract
specific components. Path functions which require additional information or
knowledge of the path semantics are provided by PFS_pathfunc().
The PFS_NAMEID structure is defined in section 7.5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_pathfunc (PFS_NAMEID *nameid, PFS_PATH_CMDS
cmd, unsigned p 1, unsigned p2, unsigned p3, unsigned
p4)

Arguments:
nameid

Structure defining the components of the path.

cmd

PFS_PATH_CMD defining the path operation to perform.
The following commands are defined:
PFS_PATH_SPLIT
This function will split a path into two components,
the path to the object and the object. The object may
be a file or directory depending on the path.
p 1·- Path buffer
p2 - Path buffer size
p3 - Object buffer
p4 - Object buffer size
PFS_PATH_PARENT
This function will return the parent path of the
specified path.
p 1 - Parent buffer
p2 - Parent buffer size
PFS_PATH_DIRECTORY
This function will return the path as a directory path.
If the path is ah:eady a directory path it is returned as

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

113

PATHWORKS File System

is. If the path is a file path it is converted to a
directory path using the path semantics of the
namespace specified in the PFS_NAMEID structure.
p 1 - Directory buffer
p2 - Directory buffer size
PFS_PATH_MATCHNAME
PFS_PATH_MATCHPATH
These two functions compare two PFS_NAMEID
structures and return PFS_SUCCESS if the file
component match or entire path match, respectively.
pl - Compare PFS_NAMEID structure
PFS_PATH_MATCHPATTERN
This function will perform a wildcard match using
the wildcard rules of the namespace specified in the
PFS_NAMEID structure. Only the file component of
the PFS_NAMEID structure is compared. The
pattern is specified as an ASCIZ string.
p 1 - Match pattern
PFS_PATH_MVWILD
This function supports the MSDOS move and
rename function. The arguments to the function
supply a match pattern, replace pattern and an output
buffer. If the file component of the PFS_NAMEID
structure matches the match pattern the replace
pattern is used to replace characters in the file
component. The result is written to the output buffer.
If the match fails the function will return
PFS_FAILURE.
p 1 - Match pattern
p2 - Replace pattern
p3 - Output buffer
p4 - Output buffer size
PFS_PATH_EXPANDNAME
This function expands the file component of the
PFS_NAMEID structure to the MSDOS 8.3 blank
padded filename format.
p 1 - Output buffer
p2 - Output buffer size

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

114

PATHWORKS File System

pl-p4

Additional arguments required by specific functions. Unused
arguments should be specified as NULL.

Return values:
PFS_SUCCESS

Path aeration completed successfully

PFS_FAILURE

Path function failed

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

115

PATHWORKS File System

8.SS.

PFS_purge

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

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

Arguments:
pathid

Resolved pathid as returned by PFS_getpathid().

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

File deleted

PFS_FAILURE

Invalid path or no access

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

116

PATHWORKS File System

8.56.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

117

PATHWORKS File System

8.57.

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, i.e. the
caller is given a pointer to cache buffers.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_readdesc (PFS_FID *fp, unsigned int nbytes, off_t offset,
struct buffer_descriptor **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].

Return values:
PFS_SUCCESS

Data read

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

118

PATHWORKS File System

8 .58.

PFS_releasedesc *

Description:
PFS_releasedesc will release the data associated with the descriptors previously
returned by PFS_readdesc().

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_releasedesc (PFS_FID *fp, struct buffer_descriptor
**desc)

Arguments:
fp

Open file pointer

desc

Descriptor pointer returned by PFS_readdesc().

Return values:
PFS_SUCCESS

Data released

PFS_FAILURE

Invalid parameter

June 9, 1993

Digital Confidential - 3rd· Party Restrictions Apply

119

PATHWORKS File System

8. 5 9.

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:

Table 8-1:

Relationship between namespaces

VMS

DOS

Macintosh

If changed

VMS name
If changed
Short name

VMS name
DOS name
If changed

DOS name
Short name

The table shows the effect of a change in one namespace on the names which
will be seen in the other namespaces. The column marked "If changed" indicates
the namespace in which a filename change occurred. The remainder of that row
shows the effect on the filenames in the other namespaces. For example, if a
filename change is made in the DOS namespace, VMS would use the new DOS
name as well as Macintosh.
·

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

Arguments:
oldpathid

Resolved pathid structure for origninal file name.

newpathid

Resolved pathid structure for new file name.

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

File renamed

PFS_FAILURE

Invalid parameters, conflicting file systems or conflicting
namespace

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

120

PATHWORKS File System .

8 .60.

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, PFS_USER *user)

Arguments:
pathid

Resolved pathid structure as returned by
PFS_getpathid().

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

Directory deleted

PFS_FAILURE

Invalid parameter, directory not empty

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

121

PATHWORKS File System

8.61.
8 .62.

PFS_setattr
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_ATTR structure is defined in section 7.5.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_setattr (PFS_PATHID *pathid, PFS_ATTR *attrp,
PFS_USER *user)
PFS_RETVAL PFS_fsetattr (PFS_FID *fp, PFS_ATTR *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

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

Attributes modified

PFS_FAILURE

Invalid paramters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

122

PATHWORKS File System

8 .63.

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_RETV AL PFS_setcomment (PFS_PATHID *pathid, char *comment,
PFS_USER *user)

Arguments:
pathid

Resolved pathid as returned by PFS _getpathid()

comment

Comment block as defined in PFS_getcomment().

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Comment written

PFS_FAILURE

Invalid paramters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

123

PATHWORKS File System

8.64.

PFS_setcontext

Description:
PFS_setcontext establishes the thread context for PFS functions which use
globals for return values. This function establishes the location for PFS_errno,
working directory and the mapped host user.
This function must be called on every thread swithc to insure a stalled PFS
function is restarted in the proper context.

NOTE
This function is soon to be obsolete.

Synopsis:
#include <pfs.h>
void PFS_setcontext (PFS_CONTEXT *context)

Arguments:
context

PFS context block containing the host user, PFS_errno and
errno pointers and the working directory buffer.

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

124

PATHWORK.S File System

8 .65.
8 .66.

PFS_setextattr
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_PATHID *pathid, PFS_EAOPS *eaopsp,
PFS_USER *user)
PFS_RETVAL PFS_setextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid()

Open file pointer.

eaopsp

Pointer to extended attributes structure. The gealist member
of the structure is ignored. The structure is defined in
PFS _getextattr().

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SCCESS

Attributes modified

PFS_FAILURE

Invalid parameters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

125

PATHWORKS File System

8.67.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

126

PATHWORKS File System

8.68.

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) ())

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

127

PATHWORKS File System

8 .69.
8. 7 0.

PFS_setsecurity *
PFS_fsetsecurity *

Description:
PFS_setsecurity associates NOS security data with a file object. The security
data is not interpretted.
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_USER *user)
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:
PFS_LMXSECURE

Lan Manager security space.

PFS_MACSECURE

Macintosh security space.

securp

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 "ownerID" member of
the Macintosh ACE.

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS
June 9, 1993

Data associated
Digital Confidential - 3rd Party Restrictions Apply

128

PATHWORK.S File System

PFS_FAILURE

Invalid parameters or file not writeable

PFS_NotSupported

Security data not supported

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

129

PATHWORKS File System

8. 71 • PFS _setsecuritymode
Description:
PFS_setsecuritymode sets the global server security mode.

Synopsis:
#include <pfs .h>
void PFS_setsecuritymode (PFS_SECURITY_MODE mode)

Arguments:
mode

Security mode to establish it may be one of the following:
PFS_NOS_SECURITY

Never check host security.

PFS_CREATOR_SECURITY
Check security if the
file was not created by the
server.
PFS_HOST_SECURITY

Always check host security.

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

130

PATHWORKS File System

8. 72.

PFS_setuser

Description:
PFS_setuser is called to establish the global default host user for the process.

Synopsis:
#include <pfs .h>
void PFS_setuser (PFS_USER *user)

Arguments:
user

Pointer to PFS_USER structure previously obtained with
PFS __getuser().

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

131

PATHWORKS File System

8. 73.

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

Resolved pathid structure as returned by PFS_getpathid()

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

132

PATHWORKS File System

8. 7 4.

PFS_shutdown

Description:
PFS_shutdown is called to clean up the file system prior to server exit. This
function is optional as the file system is responsible for cleanup on process exit.

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

Arguments:
None

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

133

PATHWORKS File System

8. 7 5 • PFS_stat
8. 7 6. 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_PATHID *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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

134

PATHWORKS File System

8. 77.
8. 7 8.

PFS_statvfs
PFS_fstatvfs

Description:
PFS _statvfs provides information about a mounted file system. The function
will obtain the amount of free space, total space, cluster size and total number of
files allowed on a volume.

NOTE
VMS systems will use the disk quota allocted to a specific user, if such
quotas are established.

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

Arguments:
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.

user

Pointer to PFS_USER structure previously obtained with
PFS _getuser().

Return values:
PFS_SUCCESS

Information obtained

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

135

PATHWORKS File System

8. 79.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

136

PATHWORKS File System

8 .80.

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.
PFS makes no assumptions about the contents of this
pointer.

Return values:
PFS_SUCCESS

Treetop written

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

137

PATHWORKS File System

8.81.

PFS_timefunc

Description:
PFS_timefunc provides operations on time buffers in various formats.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_timefunc (PFS_TIME_CMDS cmd, PFS_TIMESPACE
srctimespace, void *srctime, PFS_TIMESPACE
dsttimespace, void *dsttime)

Arguments:
cmd

Time operation command. The foloowing are currently
defined:
PFS_TIME_CONVERT

srctimespace

Convert the time from the
source format to the
destination format.

Source time space. The following time spaces are defined:
PFS_UNIXTIME

Unsigned count of seconds
since 1-JAN-1970

PFS_DOSTIME

DOS time structure

PFS_MACTIME

Signed count of seconds since
1-JAN-2000

PFS_VMSTIME

Quadword count of 10
nanosecond intervals since
17-NOV-1858

PFS_TEXTTIME

ASCII representation of time
in DD-MMM-YYYY
HH:MM:SS.T format

PFS_NATIVETIME

Platform specific host time

srctime

Source time buffer

dsttimespace

Desitnation time space. The same time spaces are defined as
for srctimespace.

dsttime

Destination time

Return values:
PFS_SUCCESS
June 9, 1993

Time operation complete
Digital Confidential - 3rd Party Restrictions Apply

138

PATHWORKS File System

PFS_FAILURE

June 9, 1993

Failure in operation

Digital Confidential - 3rd Party Restrictions Apply

139

PATHWORKS File System

8. 8 2.

PFS_ftruncate

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 .h>
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

140

PATHWORKS File System

8.83.

PFS_unlock

Description:
PFS_unlock releases a file system byte range lock established by PFS_lockQ.

Synopsis:
#include <pfs .h>
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_FAILURE

Invalid parameters or no range locked

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

141

PATHWORKS File System

8.84.

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

June 9, 1993

Digital Confidential- 3rd Party Restrictions Apply

142

PATHWORKS File System

8.85.
8.86.

PFS_utime
PFS_futime

Description:
PFS_utime sets the file modification time and file access time. The time is
specified in Unix time format. 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, struct utimebuf *timebufp,
PFS_USER *user)
PFS_RETVAL PFS_utime (PFS_FID *fp, struct utimebuf *timebufp)

Arguments:
pathid

Resolved pathid structure as returned by PFS_getpathid().

Open file pointer

timebufp

Time buffer containing two Unix times, the first for access
time and the second for modification time.

user

Pointer to PFS_USER structure previously obtained with
PFS_getuser().

Return values:
PFS_SUCCESS

Time modified

PFS_FAILURE

Invalid parameters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

143

PATHWORKS File System

8.87.

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 NOT truncated at the current offset, rather it is
extended to that position if necessary. If the server is to truncate a file it must use
PFS_truncate.

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.

bytes written

Return count of bytes actually written.

Return values:
PFS_SUCCESS

File written

PFS_FAILURE

Invalid parameters or file not open for write.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

144

PATHWORK.S File System

8 .88.

PFS_writedesc *

Description:
PFS_writedesc will write data to a file by descriptor reference. The descriptor
format is defined in PFS_readdesc(). 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, struct
buffer_descriptor **desc)

Arguments:
fp

Open file pointer

offset

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

desc

Descriptior list pointer.

Return values:
PFS_SUCCESS

File written

PFS_FAILURE

Invalid parameters or file not open for write access.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

145

PATHWORKS File System

FSLIB (File System Library) ROUTINE DESCRIPTIONS

9. 1 •
9 .2.

FSLIB_access *
FSLIB_faccess *

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

146

PATHWORKS File System

9 .3.
9. 4.

FSLIB_chdir
FSLIB _fchdir

Description:
See PFS_chdir().

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

Arguments:
See PFS_chdir().

Return values:
PFS_SUCCESS

Default set

PFS_FAILURE

Invalid pathid or fp

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

147

PATHWORKS File System

9. 5.

FSLIB_checksecurity

Description:
See PFS_checksecurity().

Synopsis:
#include <pfs .h>
PFS_CHKSTATUS FSLIB_checksecurity (PFS_PATHID *pathid,
PFS_SECURSPACE *securspace, PFS_EAOPS
*eaopsp, PFS_CHKSTATUS (*rtn)(), unsigned param)
PFS_CHKSTATUS FSLIB_checksecurity (PFS_PATHID *pathid,
PFS_SECURSPACE *securspace, PFS_MACSECUR
*eaopsp, PFS_CHKSTATUS (*rtn)(), unsigned param)

Arguments:
See PFS_checksecurity().

Return values:
PFS_ACCESS

Access allowed

PFS_NOACCESS

Access not allowed

PFS_CHKFAILED

Function failed

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

148

PATHWORKS File System

9.6.
9. 7.

FSLIB_chmod
FSLIB_fchmod

Description:
See PFS_chmod().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_chmod (PFS_PATHID *pathid, mode_t mode,
PFS_USER *user)
PFS_RETVAL FSLIB_fchmod (PFS_FID *fp, mode_t mode)

Arguments:
See PFS_chmod().

Return values:
PFS_SUCCESS

Protection changed

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

149

PATHWORKS File System

9.8.
9 .9.

FSLIB 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_USER *user)
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

150

PATHWORKS File System

9 .10.

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.

nam.espace

Namespace in which path resides.

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

June 9, 1993

Neither the file nor the parent exist in this library.

Digital Confidential - 3rd Party Restrictions Apply

151

PATHWORK.S File System

9 .11.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

152

PATHWORKS File System

9 .12.

FSLIB_closedesc

Description:
FSLIB_closedesc() closes the open file associated with the data cache. File
system libraries are free to chose how to handle this close function (denpeding
on how they opened the file for data cache access). This function is called
AFTER the main file has been closed. However, file systems are free to keep the
main file open until FSLIB_closedesc() is called.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_closedesc (void *fd)

Arguments:
fd

Pointer assigned by FSLIB_opendesc()

Return values:
PFS_SUCCESS

File closed

PFS_FAILURE

Invalid file pointer

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

153

PATHWORKS File System

9 .13 • FSLIB_convert *
Description:
FSLIB_convert translates a filename from NOS format to native format. This
function is used by PFS_getpathidO to resolve filenames prior to file lookup. If
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.
FSLIB_convert is expected to convert the client name to a native name. This may
involve file system lookups. The function should set the apropriate fields in the
pathid such that FSLIB _lookup can determine that lookups have already been
done.
FSLIB_convert is expected to convert all members of a path with the exception
of the last member. This member may not exist (creates) and may be stored in
pathid.client_name for future use. The function should set the appropriate fields
in the pathid structure such that FSLIB_lookup can determine the file does not
exist.
As can be seen FSLIB_convert and FSLIB_lookup are designed to work
together to process a file path. The partition of functions is left to the library
implementation. However, FSLIB_lookup must be given sufficient information
to determine if a path exists and if the path's parent exists.

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

namespace

Namespace in which path resides.

Return values:
PFS_SUCCESS

Name translated

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

154

PATHWORK.S File System

9 .14.

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,
PFS_USER *user)

Arguments:
See PFS_create().

Return values:
PFS_SUCCESS

File created

PFS_FAILURE

Invalid path or file exists and PFS_MAKENEW specified

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

155

PATHWORKS File System

9 .15.

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 or insuffiecient information to
locate the path.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

156

PATHWORKS File System

9 .16.

FSLIB_didpathid *

Description:
See PFS_didpathid().

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

Arguments:
See PFS_didpathid().

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

157

PATHWORKS File System

9 .17.

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

158

PATHWORK.S File System

9 .18.

FSLIB_diridinit

Description:
See PFS_diridinit().

Synopsis:
#include <pfs .h>
void FSLIB_diridinit (PFS_DIRIDS_MATIER dodirids, unsigned long
*diridptr)

Arguments:
See PFS_diridinit().

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

159

PATHWORKS File System

9 .19.

FSLIB_fextend

Description:
FSLIB_fextend() is called to extend the allocated blocks in a file. This call is
only used when PFS is caching data above the file system. Note that the file
system may be called to position a file at an offset which has not yet been written
due to write back caching. This call notifies the file system of writes to the file.
PFS caches data independent of disk allocation, quotas or any such limitations.
It is the responsibility of the file system to determine if the caller has the requisite
disk allocation necessary to satisfy the pending write.

NOTE
PFS does not keep track of end-of-file. Therefore it is not possible for
PFS to determine if an extension is required and only call this function if
so. Therefore, this function is called for every write to the file. It is the
responsibility of the file system to keep track of end-of-file and extend
the file if the position specified in this call exceeds the end-of-file (or
more precisely, the blocks allocated to the file).

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_fextend (PFS_FID *fp, off_t offset, PFS_USER *user)

Arguments:
fp

Open file pointer.

offset

File position at errd of pending write.

user

Current host user associated with pending write.

Return values:
PFS_SUCCESS

File extended or extension allowed

PFS_FAILURE

File not extended or extension not allowed

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

160

PATHWORKS File System

9 .20.
9 .21.

FSLIB_filesize
FSLIB_ffilesize

Description:
See PFS_ffilesize().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_filesize (PFS_PAHID *pathid, PFS_DATA_STREAM
stream, off_t *size, PFS_USER *user)
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

161

PATHWORKS File System

9 .22.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

162

PATHWORKS File System

9 .23.
9 .24.

FSLIB_getattr
FSLIB_fgetattr

Description:
See PFS _getattr().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_getattr (PFS_PATHID *pathid, unsigned long mask,
PFS_ATIR *attrp, PFS_USER *user)
PFS_RETVAL FSLIB_fgetattr (PFS_FID *fp, unsigned long mask,
PFS_ATIR *attrp)

Arguments:
See PFS _getattr().

Return values:
PFS_SUCCESS

Attributes updated

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

163

PATHWORKS File System

9 .25.

FSLIB_getcomment

Description:
See PFS_getcommentO.

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

Arguments:
See PFS_getcommentQ.

Return values:
PFS_SUCCESS

Coment returned

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

164

PATHWORK.S File System

9. 2 6.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

165

PATHWORKS File System

9 .27. FSLIB_getextattr *
9 •2 8 • FSLIB _fgetextattr *
Description:
See PFS_getextattr().
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. However, the dispatch vector should point to a
routine which will return a failure status.

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

Arguments:
See PFS _getextattr().

Return values:
PFS_SUCCESS

Extended attributes written to buffer

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

166

PATHWORKS File System

9. 2 9 • 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:
pathid

Resolved pathid structure as returned by PFS_getpathid().

identp

Pointer to return identification structure.

Returns:
PFS_SUCCESS

Print identification returned

PFS_FAILURE

Insufficient information

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

167

PATHWORKS File System

9.30. FSLIB_getsecurity *
9. 31 • 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. However, the dispatch vector should point to a
routine which return a failure status.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_getsecurity (PFS_PATHID *pathid, PFS_SECURSPACE
securspace, void *securp, PFS_USER *user)
PFS_RETVAL FSLIB_fgetsecurity (PFS_FID *fp, PFS_SECURSPACE
securspace, void *securp)

Arguments:
See PFS_getsecurity().

Return values:
PFS_SUCCESS

Returned attributes

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

168

PATHWORKS File System

9 .32.

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:
libentp

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

169

PATHWORKS File System

9.33.

FSLIB_Iock

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:
PFS_SUCCESS

Lock set

PFS_FAILURE

Invalid parameters or lock conflict

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

170

PATHWORKS File System

9.34.

FSLIB_lookup *

Description:
FSLIB_lookup will locate the file in the current file system. The file is located
with information left in the pathid structure by FSLIB_convert. The function
must determine if a path exists and if not whether the parent exists.
Further, the function must set the PFS_ST_FID flag if a path exists. This flag is
used by PFS to determine if a pathid structure points to an existing file. This
field must be set even if the FID field is not supported by the file system.
The function must set the PFS_ST_DID flag if the parent path exists. This flag is
used by PFS to determine if the parent path exists. This flag must be set even if
the file system does not support the DID field.

Synopsis:
#include <pfs .h>
PFS_FSTATUS 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_EXISTS

File located

PFS_NOEXIST

File not found, parent exists

PFS_FAILED

File not found, parent not found

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

171

PATHWORKS File System

9 .35.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

172

PATHWORKS File System

9 .36.
9.37.

FSLIB_mapname
FSLIB_fmapname

Description:
See PFS_mapname().

Synopsis:
#include <pfs .h>
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

173

PATHWORKS File System

9.38.

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, PFS_USER *user)

Arguments:
See PFS_mkdir().

Return values:
PFS_SUCCESS

Directory created

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

174

PATHWORK.S File System

9 .39.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

175

PATHWORKS File System

9.40.

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 looks 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

June 9, 1993

, Digital Confidential - 3rd Party Restrictions Apply

176

PATHWORKS File System

9 .41.

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, PFS_USER *user)

Arguments:
See PFS_open().

Return values:
PFS_SUCCESS

File open

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

177

PATHWORKS File System

9 .42.

FSLIB_opendesc

Description:
FSLIB_opendesc() opens a file for access by the global data cache. A file system
may decide to use separate file pointers for the main file open and the data cache
or may use the same file pointer. The global data cache uses a SINGLE file
pointer for all access to a given file, regardless of how many times the file is
actually open. The file pointer the cache will use is determined by this function.
PFS_open() will call the FSLIB_open() function to open a file or map into an
existing open. Following a successful open PFS will call the FSLIB_opendesc()
function. This function will determine if the file is to be cached and if so, will
return a file pointer to be used by the data cache. This file pointer is passed to
FSLIB_readdesc() and FSLIB_writedesc().
PFS_close() will call FSLIB_close() to close the file. After a successful close
PFS_close() will call FSLIB_closedesc() IF this is the only open reference in the
data cache.
The file system library is free to determine how it wishes to handle distributed
file access, either thru the global data cache or on its own. However, PFS
assumes that all files may be accessed in a distributed fashion and will freely do
so.

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_opendesc (PFS_FID *fp, void **fd)

Arguments:
fp

Open file pointer

Return file system specific file pointer

Return values:
PFS_SUCCESS

File open

PFS_FAILURE

Data cache access not allowed

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

178

PATHWORK.S File System

9 .43.
9 .44.

FSLIB_purge
FSLIB_fpurge

Description:
See PFS_purge().
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 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_PATHID *pathid, PFS_USER *user)
PFS_RETVAL FSLIB_fpurge (PFS_FID *fp)

Arguments:
See PFS_purge().

Return values:
PFS_SUCCESS

File deleted

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

179

PATHWORK.S File System

9. 4 5 .

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().

Return values:
PFS_SUCCESS

Bytes read (including none)

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

180

PATHWORKS File System

9. 4 6.

FSLIB_readdesc *

Description:
FSLIB_readdesc() is called to read a portion of the specified file into the
specified descriptor list. The file system should fill the descriptors in the order
specified in the descriptor list and must fill complete buffers before proceeding to
the next descriptor.

Figure 9-1: Format of a Buffer Descriptor

0
4

BDSC_A_UNK
BDSC_L_BCNT
BDSC_A_BUFFER
BDSC_L_OFFSET
BDSC_W'_VALIDBYTES

Table 9-1:

BDSC_R_FLAGS

8
12
16

BDSC_A_PCSSTATE

BDSC_A_PCSSTATESVA

BDSC_A_BUFFERSVA

Contents of a Buffer Descriptor

Field Name

Description

BDSC_A_LINK

Pointer to next buffer descriptor in list. a
NULL link indicates the end of the list.
Count of bytes in the data buffer.
Address of the data buffer.
File offset for start of the data buffer.
Buffer flags. The following flags are
defined:

BDSC_L_BCNT
BDSC_A_BUFFER
BDSC_L_OFFSET
BDSC_R_FLAGS

BDSC_'W_VALIDBYTES
BDSC_A_PCSSTATE
BDSC_A_PCSSTATESVA
BDSC_A_BUFFERSVA

BDSC_M_MODIFY_INTENT
BDSC_M_NO_PREFILL
Return count of validbytes for read
functions.
PCS state longword. This field is private to
PCS.
System virtual address of the PCS state
buffer. This field is private to PCS.
System virtual address of the data buffer.

The buffer descriptor contains the address of the next descriptor or NULL in the
bdsc_a_link member. The FSLIB_readdesc() function should use this pointer to
process the buffer list.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

181

PATHWORKS File System

The bdsc_l_bcnt member specifies the size of the buffer to be filled by the file
system. This buffer is completely filled, up to end of file. The amount of data
written to the buffer is set by the file system in the bdsc_w_validbytes member.
If this field is less than the initial buffer size all remaining buffers in the list
should have zero valid bytes.

NOTE
The flag bdsc_v_modify_intent (contained in the bdsc_r_flags member)
specifies that this read is a back fill of a buffer about to be modified. The
file system may use this flag to optimize filling the buffer with only data
which is not in the modify region (specified by the nbytes and offset
parameters to the function). Note that the bdsc_w_validbytes member
must reflect the modify range in the buffer as well as any data actually
written to the buffer. This optimization is not required but is suggested.
The bdsc_l_offset member specifies the position in the file represented by the
start of this buffer. The position is specified as a zero based byte count relative to
the start of the file.
The remainder of the structure is private to the cluster cache manager.

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

Arguments:
fd

File pointer as returned by FSLIB_opendesc()

nbytes

Number of bytes in modify region or client requested read
range.

offset

Starting offset of modify range or client requested read
range.

desc

Pointer to first descriptor.

Return values:
PFS_SUCCESS

Data read

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

182

PATHWORKS File System

9. 4 7 • FSLIB _rename
Description:
See PFS_rename().

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

Arguments:
See PFS_rename().

Return values:
PFS_SUCCESS

File renamed

PFS_FAILURE

Invalid parameters, conflicting file systems or conflicting
namespace

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

183

PATHWORKS File System

9. 4 8.

FSLIB _rmdir

Description:
See PFS_rmdir().

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

Arguments:
See PFS_rmdir().

Return values:
PFS_SUCCESS

Directory deleted

PFS_FAILURE

Invalid parameter, directory not empty

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

184

PATHWORK.S File System

9 .49.
9 .50.

FSLIB_setattr
FSLIB_fsetattr

Description:
See PFS_setattr().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setattr (PFS_PATHID *pathid, PFS_ATTR *attrp,
PFS_USER *user)
PFS_RETVAL FSLIB_fsetattr (PFS_FID *fp, PFS_ATTR *attrp)

Arguments:
See PFS _setattr().

Return values:
PFS_SUCCESS

Attributes modified

PFS_FAILURE

Invalid paramters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

185

PATHWORKS File System

9.S1.

FSLIB_setcomment

Description:
See PFS_setcommentO.

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

Arguments:
See PFS_setcommentO.

Return values:
PFS_SUCCESS

Comment written

PFS_FAILURE

Invalid paramters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

186

PATHWORKS File System

9 .52.
9 .53.

FSLIB_setextattr *
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_USER *user)
PFS_RETVAL FSLIB_setextattr (PFS_FID *fp, PFS_EAOPS *eaopsp)

Arguments:
See PFS_setextattr().

Return values:
PFS_SUCCESS

Attributes modified

PFS_FAILURE

Invalid parameters or file not writeable

June 9, 1993

Digital Confidential- 3rd.Party Restrictions Apply

187

PATHWORKS File System

9 .S4.
9 .SS.

FSLIB_setsecurity *
FSLIB_fsetsecurity *

Description:
See PFS_setsecurity().
For a description of optional functions see FSLIB_getsecurity().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_setsecurity (PFS_PATIIlD *pathid,
PFS_SECURSPACE securspace, void *securp,
PFS_USER *user)
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

188

PATHWORKS File System

9 .56.
9 .57.

FSLIB_stat
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

189

PATHWORKS File System

9 .58.
9 .59.

FSLIB statvfs

FSLIB~)statvfs

Description:
See PFS_statvfs().

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_statvfs (PFS_PATHID *pathid, statvfs_t *fsbufp,
PFS_USER *user)
PFS_RETV AL FSLIB_fstatvfs (PFS_FID *fp, statvfs_t *fsbufp, PFS_USER
*user)

Arguments:
See PFS_statvfs().

Return values:
PFS_SUCCESS

Information obtained

PFS_FAILURE

Invalid parameters

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

190

PATHWORKS File System

9.60.

FSLIB_sync

Description:
See PFS_sync().

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

Arguments:
None

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

191

PATHWORKS File System

9 .61.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

192

PATHWORKS File System

9.62.

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

193

PATHWORKS File System

9 .63.

FSLIB_unmap

Description:
See PFS_unmap().

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

Arguments:
See PFS_unmap().

Return values:
None

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

194

PATHWORKS File System

9 .64.
9 .65.

FSLIB_utime
FSLIB_futime

Description:
See PFS_utime().

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

Arguments:
See PFS_utime().

Return values:
PFS_SUCCESS

Time modified

PFS_FAILURE

Invalid parameters or file not writeable

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

195

PATHWORKS File System

9.66.

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().

Return values:
PFS_SUCCESS

File written

PFS_FAILURE

Invalid parameters or file not open for write.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

196

PATHWORKS File System

9 .67.

FSLIB_writedesc *

Description:
FSLIB_writedescO write bytes to an open file. The write buffer(s) are specified
by a descriptor list. (See FSLIB _readescO for a description).

Synopsis:
#include <pfs .h>
PFS_RETVAL FSLIB_writedesc (void *fd, PFS_DESC *desc)

Arguments:
fd

Open file pointer as returned by FSLIB_opendescO.

desc

Pointer to first buffer descriptor to be written

Return values:
PFS_SUCCESS

File written

PFS_FAILURE

Invalid parameters or file not open for write access.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

197

PATHWORKS File System

PATHLIB (Path Library) ROUTINE DESCRIPTIONS

10.1

PATHLIB_parse

Description:
PATHLIB_parse will parse the supplied name and fill out the PFS_NAMEID
structure. The function uses the semantics of the library's namespace to break
the path into its components. This is the only function which is allowed to
modify the PFS_NAMEID structure.

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

Arguments:
name

ASCIZ buffer containing the path to be parsed.

namespace

N amespace in wich to parse

nameid

Pointer to a PFS_NAMEID structure to initialize.

Return values:
PFS_SUCCESS

Path parsed

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

198

PATHWORK.S File System

10.2

PATHLIB_split

Description:
PATHLIB_split uses the PFS_NAMEID structure associated with a path to
break the path into directory and file components. The supplied buffers for the
directory and file will be written based on the parsed name. PATHLIB_parse
will have been called prior to this function.

Synopsis:
#include <pfs .h>
PFS_RETVAL PATHLIB_split (PFS_NAMEID *nameid, char *dirbuf, int
dirbuflen, char *filbuf, int filbuflen)

Arguments:
nameid

PFS_NAMEID structure defining path.

dirbuf

Buffer to receive directory component.

dirbuflen

Length of directory buffer.

filbuf

Buffer to receive file component.

filbuflen

Length of file buffer.

Return values:
PFS_SUCCESS

Path split

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

199

PATHWORKS File System

10.3

PATHLIB_parent

Description:
PATHLIB_parent will use the PFS_NAMEID structure supplied to obtain the
parent of a given path. The parent is the directory which contains the path. For
most namespaces the parent path is a subset of the full path. However, for VMS
the parent may be the root directory, [000000], which is not contained in the
specified path.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_parent (PFS_NAMEID *nameid, char *parent, int
parentlen)

Arguments:
nameid

PFS_NAMEID structure for the path for which to obtain the
parent.

parent

Buffer to receive the parent path.

parentlen

Length of the parent buffer.

Return values:
PFS_SUCCESS

Parent obtained

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

200

PATHWORKS File System

10.4

PATHLIB_directory

Description:
PATHLIB_directory will convert the specified file path to its equivalent directory
·path.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_directory (PFS_NAMEID *nameid, char *dirbuf, int
dirbuflen)

Arguments:
nameid

PFS_NAMEID structure for the path to convert to a
directory.

dirbuf

Buffer to receive the directory path.

dirbuflen

Length of the directory buffer.

Return values:
PFS_SUCCESS

Directory obtained

PFS_FAILURE

Invalid path

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

201

PATHWORKS File System

10.S

PATHLIB_matchpath

Description:
PATHLIB_matchpath will compare two full paths and return PFS_SUCCESS if
they are identical. The whole path is compared.

Synopsis:
#include <pfs .h>
PFS_RETVAL PATHLIB_matchpath (PFS_NAMEID *srcpath, PFS_NAMBID
*matchpath)

Arguments:
srcpath

PFS_NAMEID for the source path to compare.

matchpath

PFS_NAMBID for the compare path.

Return values:
PFS_SUCCESS

Paths are identical

PFS_FAILURE

Invalid path or not identical

June 9, 1993

Digital Confidential- 3rd Party Restrictions Apply

202

PATHWORKS File System

10.6

PATHLIB_matchname

Description:
PATHLIB_matchname will compare the file components of two paths and return
PFS_SUCCESS if they are identical.

Synopsis:
#include <pfs .h>
PFS_RETVAL PATHLIB_matchname (PFS_NAMEID *srcpath,
PFS_NAMEID *matchpath)

Arguments:
srcpath

PFS_NAMEID for the path whose file component is to be
matched.

matehpath

PFS_NAMEID for the path whose file component is to be
compared.

Return values:
PFS_SUCCESS

File components are identical

PFS_FAILURE

Invalid path or file components not identical.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

203

PATHWORKS File System

10.7

PATHLIB_matchpattern

Description:
PATHLIB _matchpattern will compare the file component of the specified path
against a wilcard pattern string. The wildcard match rules are namespace
specified as are the wildcard characters.

Synopsis:
#include <pfs .h>
PFS_RETVAL PATHLIB_matchpattern (PFS_NAMEID *srcpath, char
*pattern)

Arguments:
srcpath

PFS_NAMEID for the path whose file component is to be
matched.

pattern

ASCIZ pattern possibly containing wildcard characters to be
used for matching. The match rules are namespace specific
as are the characters allowed in the pattern.

Return values:
PFS_SUCCESS

Path match

PFS_FAILURE

Invalid path or no match

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

204

PATHWORKS File System

10.8

PATHLIB_expandname

Description:
PATHLIB_expandname will expand the file component of a path into its 8.3
blank padded format. This function is useful only in PFS_DOSNAME
namespace.

Synopsis:
#include <pfs .h>
PFS_RETVAL PFS_expandname (PFS_NAMEID *nameid, char *buffer, int
buflen)

Arguments:
nameid

PFS_NAMEID for path whose file component is to be
expanded.

buffer

Buffer to receive the expanded name.

buflen

Length of the supplied buffer.

Return values:
PFS_SUCCESS

Name expanded

PFS_FAILURE

Invalid path or buffer too small

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

205

PATHWORKS File System

10.9

PATHLIB_mvwild

Description:
PATHLIB_mvwild is used to match a file component and replace specified
characters in the file component. The pattern supplied has the same format as for
PATHLIB_matchpattern. The match function is identical to
PATHLIB_matchpattern.
The replacement function will select the character from the source file component
if a wildcard is specified in the replace pattern. If a non wild character is
specified in the replace pattern it will be inserted in the corrosponding position in
the result file buffer.

Synopsis:
#include <pfs .h>
PFS_RETVAL PATHLIB_mvwild (PFS_NAMEID *nameid, char *matchpat,
char *replacepat, char *buffer, int buflen)

Arguments:
nameid

PFS_NAMEID for path whose file component is to be
modified.

matchpat

Match pattern. If the file component does not match this
pattern the function will fail.

replacepat

Replace pattern. The pattern specifies which characters to
copy from the source file component and which to copy
from the pattern. The format of the pattern is namespace
specific.

buffer

Buffer to receive modified file component.

buflen

Length of supplied buffer.

Return values:
PFS_SUCCESS

Matched and replaced

PFS_FAILURE

Invalid path or no match

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

206

PATHWORKS File System

TIMELIB (Time Library) ROUTINE DESCRIPTIONS
Time libraries are provided to handle conversion from one time space to another. The
time libraries may provide direct conversion routines for each time space, however,
only the TIMELIB_fromnativetime() and TIMELIB_tonativetime() function must be
provided. If a library does not support direct conversion the associated vector should be
specified as NULL.
To perform a conversion from one time space to another PFS will locate the source time
space's function dispatch vector and check to see if direct conversions are supported. If
so the function is dispatched to handle the conversion. If the library does not support
direct conversion PFS will use the library's TIMELIB_tonativetime() function to
convert to native time. PFS will then locate the destination time space's library function
dispatch table and use the TIMELIB_fromnativetime() function to convert to the
destination time space.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

207

PATHWORKS File System

11.1

TIMELIB_fromnativetime

Description:
TIMELIB_fromnativetime will convert a native time format to the library's time
space format. The native time format is platform specific. It is currently
implemented as VMS quadword format.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_fromnativetime(void *nativetime, void *time)

Arguments:
nativetime

Pointer to time buffer in native time format

time

Pointer to buffer to receive library's time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

208

PATHWORK.S File System

11.2

TIMELIB_tonativetime

Description:
TIMELIB_tonativetime will convert the library's time space to native time
format. Native time format is platform specific. It is currently implemented VMS
quadword time.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_tonativetime (void *time, void *nativetime)

Arguments:
time

Pointer to time buffer in library's time format

nativetime

Pointer to buffer to receive native time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

209

PATHWORKS File System

11.3

TIMELIB_tounixtime

Description:
TIMELIB_tounixtime will convert from the library's time format to Unix time
format (seconds since 1-JAN-1970). This function is optional. If not supported
it should be specified as NULL in the library's function dispatch vector.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_tounixtime (void *time, void *unixtime)

Arguments:
time

Pointer to time buffer in library's time format

unixtime

Pointer to buffer to receive Unix time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

210

PATHWORKS File System

11.4

TIMELIB_todostime

Description:
TIMELIB_todostime will convert from the library's time format to MSDOS time
format. MSDOS time format is a 32 bit structure in the following format:

Figure 11-1:
31

Format of DOS Time Buffer

27 26
21 20
16 15
Hour
Minute
Second

9 8
Year

5 4

l Month l Day I

MSDOS Time Format
MSDOS time resolution is 2 second intervals and covers the range from 1-JAN1980 to 31-DEC-2107.
This function is optional. If not supported it should be specified as NULL in the
library's function dispatch vector.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_todostime (void *time, void *dostime)

Arguments:
time

Pointer to time buffer in library's time format

dostime

Pointer to buffer to receive MSDOS time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

211

PATHWORKS File System

11.S

TIMELIB_tomactime

Description:
TIMELIB_tomactime will convert from the library's time format to Macintosh
time format (signed seconds since 1-JAN-2000). This function is optional. If not
supported it should be specified as NULL in the library's function dispatch
vector.

Synopsis:
#include <pfs.h>
PFS_RETVAL TIMELIB_tomactime (void *time, void *mactime)

Arguments:
time

Pointer to time buffer in library's time format

mactime

Pointer to buffer to receive Macintosh time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

212

PATHWORKS File System

11.6

TIMELIB_tovmstime

Description:
TIMELIB_tovmstime will convert from the library's time format to VMS time
format (64 bit unsigned count of ten nanosecond intervals since 17-NOV-1858).
This function is optional. If not supported it should be specified as NULL in the
library's function dispatch vector.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_tovmstime (void *time, void *vmstime)

Arguments:
time

Pointer to time buffer in library's time format

vmstime

Pointer to buffer to receive VMS time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

213

PATHWORKS File System

11. 7

TIMELIB_totexttime

Description:
TIMELIB_totexttime will convert from the library's time format to ASCII time
format (dd-mmm-yyyy hh:mm:ss.t). This function is optional. If not supported
it should be specified as NULL in the library's function dispatch vector.

Synopsis:
#include <pfs .h>
PFS_RETVAL TIMELIB_totexttime (void *time, void *texttime)

Arguments:
time

Pointer to time buffer in library's time format

texttime

Pointer to buffer to receive ASCII time format

Return values:
PFS_SUCCESS

Converted

PFS_FAILURE

Invalid time

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

214

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.

12 .1

ODS2 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.

12 .1 .1 Names pace
The ODS2 DOS library uses the following algorithm for mapping DOS filenames to
VMS filenames:

IF not case sensitive THEN convert lowercase to uppercase
ELSE treat lowercase as VMS illegal
IF first character is hyphen (-) treat as VMS illegal
IF character is underscore(_) AND next 3 characters are underscore,hex,hex
THEN treat first underscore as VMS illegal
FOR each VMS illeagal character DO
Insert two underscores (_)
Convert character to hex ASCII code

IF extention EQL "DIR" insert two underscores(_) before "DIR"
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:
FOR each double underscore, hex, hex sequence DO
Remove underscore
Convert pair of hex ASCII codes to character

IF extention EQL "_DIR" remove double underscore
For example, NAME_40._DIR would be converted to NAME® .DIR

NOTE
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

215

PATHWORKS File System

The above algorithm has the undesireable side effect of converting
filenames with double underscores if they are entered by a host user or
found on distribution media. There are plans to alter the mapping
algorithm or condition the translation based on media type.

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

Figure 12-1:

Format of the PATHWORKS DOS ACE
ACE$B_TYPE

ACE$W_FLAGS
ACE$W_FACILITY_FLAGS

PFS$B_SIZE

4
f

DOS$L_FILESIZE

DOS$R_ATTRIBUTES

DOS$Q_MODIFY_TIME

DOS$L_FILESIZE

DOS$Q_MODIFY_TIME

DOS$L_CREATE

DOS$Q_MODIFY_TIME

DOS$L_LASTACCESS

DOS$L_CREATE

DOS$L_LASTMOD

DOS$L_LASTACCESS

DOS$L_LASTMOD

Table 12-1:
~

ACE$W_FACILITY

I PFS$B_VERSION I PFS$B_TYPE

PFS$B_FLAGS

I ACE$B_SIZE

Contents of the PATHWORKS DOS ACE

Field Name

Description

ACE$B_SIZE

The total size of the VMS ACE, including
the 8 byte ACE header plus the sum of all
PATHWORKS sub ACEs.
VMS ACE type. ThePATHWORKS ACE
is identified by ACE type 128
(PWRK$C_PATHWORKS_ACE).
VMS ACE flags. The PATHWORKS ACE
specifies ACE$M_HIDDEN and
ACE$M_NOPROPAGATE.
The VMS facility which owns the ACE.
This field is specified as 1680 (690 hex)
(PWRK$C_FACILITY_CODE).
VMS facility specific flags. This field is not
used by the PATHWORKS ACE.

ACE$B_TYPE
ACE$W_FLAGS
ACE$W_FACILITY
ACE$W_FACILITY_FLAGS

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

216

PATHWORKS File System

Table 12-1 (cont):

Contents of the PATHWORKS DOS ACE

Field Name

Description

PFS$B_SIZE

Sub ACE length. The sub ACE follows the
PFS$B_FLAGS field.This is the length of
the sub ACE plus the longword sub ACE
header.
Sub ACE type. The PATHWORKS DOS
ACE sub type is specified as 4
(PWRK$C_ACE_DOS).
Sub ACE version. This field is not
currently used and must be zero.
Sub ACE flags. This field is not currently
used and must be zero.
DOS attributes word. The bits defined in
this word are:

PFS$B_TYPE
PFS$B_VERSION
PFS$B_FLAGS
DOS$R_ATTRIBUTES

DOSACE$M_READONLY
DOSACE$M_HIDDEN
DOSACE$M_SYSTEM
DOSACE$M_VOLUME
DOSACE$M_DIR
DOSACE$M_ARCIIlVE
DOSACE$M_MULTI (OS/2)
DOSACE$M_EXECONLY (OS/2)
DOS$L_FILESIZE
DOS$Q_MODIFY_TIME
DOS$L_CREATE
DOS$L_LASTACCESS
OOS$L_LASTMOD

Total file data size for files not in stream or
fixed RMS format or non sequential file
orgranizations.
Time at which the file size was calculated.
This field will be zero if the file size field is
not valid.
DOS format create time.
DOS format last access time.
DOS format lat modify time.

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.

12 .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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

217

. PATHWORKS File System

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.

12.1.4 Datapaths
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.

12.1.S 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.
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.

12 .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.

12 .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.

12 .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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

218

PATHWORKS File System

12.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-1 Sms
(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 unique DO
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 ille__g_al characters
June 9, 1993
Digital Confidential- 3rd Party Restrictions Apply

219

PATHWORKS File System

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.

12.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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

220

PATHWORKS File System

Figure 12-2:

Format of the PATHWORKS Macintosh ACE

ACE$B_TYPE

ACE$W_FLAGS
ACE$W_FACILITY_FLAGS

ACE$W_FACILITY

I PFS$B_VERSION I PFS$B_TYPE

PFS$B_FLAGS

1 ACE$B_SIZE
PFS$B_SIZE

0
4
18

12
MAC$T_LONGNAME[32]

MAC$L_PARENTID

MAC$L_FILEID

MAC$W_ATIRIB

MAC$T_FINDERINF0[32]
MAC$W_OFFSPRINGCOUNT

MAC$L_CREATEDATETIME

MAC$L_MODIFYDATETIME

MAC$L_BACKUPDATETIME

100
104

MAC$L_OWNERID

108

MAC$L_GROUPID

MAC$T_PRODOSI MAC$B_WORLDRJ MAC$B_GROUPR MAC$B_OWNERR 112
116
MAC$T_PRODOSINF0[6]
MAC$L_DATAFORKLENGTH

MAC$T_PRODOSI 120

MAC$L_RESFORKLENGTH

MAC$L_DATAFOR 124
MAC$L_RESFORK 128

Table 12-2:

Contents of the PATHWORKS Macintosh ACE

Field Name

Description

ACE$B_SIZE

The total size of the VMS ACE, including
the 8 byte ACE header plus the sum of all
PATHWORKS sub ACEs.
VMS ACE type. The PATHWORKS ACE
is identified by ACE type 128
(PWRK$C_PATHWORKS_ACE).

ACE$B_TYPE

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

221

PATHWORKS File System

Table 12-2 (cont):

Contents of the PATHWORKS Macintosh ACE

Field Name

Description

ACE$W_FLAGS

VMS ACE flags. The PATHWORKS ACE
specifies ACE$M_HIDDEN and
ACE$M_NOPROPAGATE.
The VMS facility which owns the ACE.
This field is specified as 1680 (690 hex)
(PWRK$C_FACILITY_CODE).
VMS facility specific flags. This field is not
used by the PATHWORKS ACE.
Sub ACE length. The sub ACE follows the
PFS$B_FLAGS field.This is the length of
the sub ACE plus the longword sub ACE
header.
Sub ACE type. The PATHWORKS DOS
ACE sub type is specified as 4
(PWRK$C_ACE_DOS).
Sub ACE version. This field is not
currently used and must be zero.
Sub ACE flags. This field is not currently
used and must be zero.
Macintosh long filename.
32 bit Macintosh parent directory ID. This
ID is used for access to the parent folder.
32 bit Macintosh file ID. This ID may be
used for direct access to the file.
Macintosh file/directory attributes. The
following attributes are defined:

ACE$W_FACILITY
ACE$W_FACILITY_FLAGS
PFS$B_SIZE

PFS$B_TYPE
PFS$B_VERSION
PFS$B_FLAGS
MAC$T_LONGNAME
MAC$L_PARENDID
MAC$L FILEID
MAC$W_ATTRIB

MAC$T_FINDERINFO
MAC$W OFFSPRINGCOUNT
MAC$L_CREATEDATETIME
MAC$L_MODIFYDATETIME
MAC$L_BACKUPDATETIME
MAC$L_OWNERID
MAC$L_GROUPID
MAC$B OWNERRIGHTS
MAC$B=GROUPRIGHTS
MAC$B_WORLDRIGHTS

June 9, 1993

MAC$M_INVISIBLE
MAC$M_SYSTEM
MAC$M_BACKUPNEEDED
MAC$M RENAMEINHIBIT
MAC$M})ELETEINHIBIT
MAC$M_WRITEINHIBIT
MAC$M_COPYPROTECT
MAC$M MULTIUSER
32 byte Finder Information.
Count of files contained in this directory
32 bit Macintosh format file creation time
32 bit Macintosh format file modification
time.
32 bit Macintosh backup time.
32 bit Macintosh file owner ID
32 bit Macintosh owner group ID
Access rights for file owner
Access rights for file owner's group
members.
Access rights for others.

Digital Confidential - 3rd Party Restrictions Apply

222

PATHWORKS File System

Table 12-2 (cont):

Contents of the PATHWORKS Macintosh ACE

Field Name

Description

MAC$T_PRODOSINFO
MAC$L_DATAFORKLENGTH
MAC$L_RESFORKLENGTH

6 byte Pro DOS Information
Length of the data fork, in bytes.
Length of the resource fork, in bytes.

The times stored in the ACE are in Macintosh format. The fileID and parentlD 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.

12.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.

12. 2. 4 Datapaths
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. If a
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.

12.2.S 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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

223

PATHWORKS File System

Aggendix A - YMS 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. PFS 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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

224

PATHWORKS File System

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 ACEs.
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 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:
SEQUENTIAL

June 9, 1993

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

Digital Confidential - 3rd Party Restrictions Apply

225

PATHWORKS File System

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.

A .3 .6 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

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.

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 <LF>.

UNDEFINED

No record format.

A •3. 7 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 defines 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).

FTN

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

226

PATHWORKS File System

PRN

A •4

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

File 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
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. 5

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 ,].

WORLD

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

227

PATHWORKS File System

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 of UIC 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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

228

PATHWORK.S 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

MSDOS 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

MS DOS 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

MS DOS 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 bit FATs are used for small volumes (less than
20740 blocks). 16 bit FATs are used for large volumes. The largest volume supported
by FAT is approximately lOM bytes.
June 9, 1993
Digital Confidential- 3rd Party Restrictions Apply
229

PATHWORKS File System

B •S

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 MSDOS client is served by LanManager
the security requirements will be those of LanManager. If the MS DOS client is
supported by AFP the security model will be that of AFP.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

230

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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

231

PATHWORKS File System

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
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 •5

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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

232

PATHWORKS File System

Appendix D - FSI interface
This appendix was written from notes taken during the initial review of the LMU FSI
implementation. The structure and function of the FSI 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 FSI 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 FSI 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_dt() and
FSI_checkvolume() which map to MACUTILS library FSLIB functions
FSLIB_chdir(), FSLIB_fchdir() 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
June 9, 1993
Digital Confidential - 3rd Party Restrictions Apply

233

PATHWORKS File System

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 ermo
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 detennine how many files to
close based on the number of times the function 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,
FSI_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 FSI_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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

234

PATHWORKS File System

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.

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 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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

235

PATHWORKS File System

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
FSI_diridfcn
FSI_diridini
FSI_getcwd
FSI_getdents
FSI_mkdir
FSI_rmdir
File access functions
FSI_access
FSI_close
FSI_copyfile
FSl_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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

236

PATHWORK.S File System

FSI_chmod
FSl_chown
FSI_getattr
FSI_geteas
FSI_getcmnt
FSI_filesize
FSI_setattr
FSI_setcmnt
FSI_seteas
Path functions
FSI_getpathid
FSI_fullpath
FSI_shortpath
FSI_treetop
General support functions
FSI_init
FSI_mapname
FSI_mpxclose
FSI_needfds
FSI_needinodes
FSI_setlognores
FSI_setnotifympx
FSI_stat
FSI_statvfs

D.2

PATH ID (FSI_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.
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.
June 9, 1993

Digital Confidential- 3rd Party Restrictions Apply

237

PATHWORKS File System

End tree top
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 stat() 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 ID (FSI_FID)
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

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

238

PATHWORKS File System

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

File flags
Locking flag and file written flag.
File mapping information
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

239

PATHWORK.S File System

[Need to find 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 FSI_access
Description:
This function will determine if a file may be accessed according to the mode specified.

Synopsis:
FSI_Access (FSI_PATHID *pathid, int perms)

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

D.3.2 FSI_chdir
Description:

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

240

PATHWORKS File System

This function will change the working directory. Modifies global variables FSl_curdir,
FSI_curdirlen.

Synopsis:
FSl_chdir (FSI_PATHID *pathid)

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

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

Synopsis:
FSI_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 FSl_curdir
END
END

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

Synopsis:
FSI_chmod (FSl_PATHID *pathid, mode)

Algorithm:
BEGIN
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

241

PATHWORKS File System

Dispatch FSLIB_chmod (pathid, mode)
END

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

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 FSI_chown
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 FSI_fchown
Description:
This routine will change the owner of the specified file

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

Algorithm:
BEGIN
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

242

PATHWORKS File System

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

D .3 .8 FSI_close
Description:
This function will close a file.

NOTE
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:
FSl_close (FSI_FID *fp)

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

D .3 .9 FSI_copyfile
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:
FSl_copyfile (FSI_PATHID *src, FSl_PATHID *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 dest not supported THEN error
IF dostream attributes AND dest not supported THEN error
Open src primary stream
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

243

PATHWORKS File System

IF dest does not exist THEN BEGIN
Create dest primary stream
Copy file attributes from src

END
ELSE Open dest primary stream
FOR all streams DO BEGIN
Dispatch FSI_lock (src)
Dispatch FSI_lock (dest)
Dispatch FSLIB_ffilesize (src)
FOR all bytes DO BEGIN
Dispatch FSLIB_read (src)
Dispatch FSLIB_write (dest)
END
Dispatch FSI_unlock (src)
Dispatch FSI_unlock (dest)
Dispatch FSI_close (src)
Dispatch FSI_close (dest)
Open next src stream
Open next dest stream

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

D.3.10 FSl_create
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
FSI_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)

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

244

PATHWORKS File System

FSI_create initialires the following fields of the FSI_FID following a successful call to
FSLIB_open (actually done in local routine opencreate):
refcnt (set to 1)
stream (FSI_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 (FSI_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
Use existing FID
END
ELSE BEGIN
Dispatch FSLIB_open (pathid, &pathid->status, O_RDWR I O_CREAT I O_TRUNC, mode,
FSI_PRIMARY, FSI_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 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 THEN Dispatch FSLIB_fchown
Dispatch FSLIB _fstat
IF FSI_PRIMARY THEN pathid->status = fp->status;
END
END
END
END

D .3 .11 FSI_delete
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

245

PATHWORKS File System

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 FSI_diridinit
Description:
This routine will initialize the handling of directory IDs.

Synopsis:
FSI_diridinit (dodirids, diridptr)

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

D.3.13 FSI_diridfunc
Description:
This routine handles directory ID functions, FSI_DIRID_GET, FSI_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:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

246

PATHWORKS File System

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

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

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

Synopsis:
FSI_ffilesize (FSI_FID *fp, size)

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

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

Synopsis:
FSI_fsync (FSI_FID *fp)

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

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

Synopsis:
FSl_fullpath (FSI_FID *fp, pathbuf, pathlen)
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

247

PATHWORKS File System

Algorithm:
BEGIN
Copy fullpath from fp to pathbuf

END
D.3 .17 ·FSI_getattr
Description:
This function will return the requested file attributes and update the FSI_PATHID
structure. Attributes which may be requested are as follows:
FSI_AT_DIRID - Directory ID
FSI_AT_BTIME - Backup time
FSI_AT_CREATE - Creation time
FSI_AT_F_INFO - Finder info
FSI_AT_ARCHIVE - File is archived
FSI_AT_HIDDEN - File is archived
FSI_AT_SYSTEM - File is a·system file
FSI_AT_NOREN - File can not be renamed (can be copied)
FSI_AT_NODEL - File can not be deleted
FSI_AT_NOCOPY - File can not be copied (can be renamed)
FSI_AT_READONLY - File is read only
FSI_AT_NOPURGE - File is deleted on delete
FSI_AT_MACAPPL - File is Macintosh application
FSI_AT_MULTIUSER - File can be opened simultaneously
FSI_AT_EXECONLY - File is execute only
FSI_AT_INDEXED - Netware index file
FSI_AT_TRANS - Netware transation tracking
FSI_AT_RDAUDIT- Netware transaction tracking
FSI_AT_WRAUDIT-Netware transaction tracking

Synopsis:
FSI_getattr (FSI_PATHID *pathid, mask, FSI_ATTR *attrp)

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

END
D. 3 .18 FSI_fgetattr
Description:
This routine will return the requested attributes and update the FSI_FID structure.
Attributes and masks are the same as for FSI_getattr.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

248

PATHWORKS File System

Synopsis:
FSI_fgetattr (FSI_FID *fp, mask, FSI_ATIR *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 FSl_getcomment
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 FSl_getcmd
Description:
This function will return the current working directory.

Synopsis:
FSI_getcwd (cwdptr)

Algorithm:
BEGIN
Set cwdptr to FSI_curdir
END

D.3.21 FSI_getdents
Description:
This function will return directory entry 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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

249

PATHWORK.S File System

FSI_UNIXNAME- Use UNIX format
FSI_DOSNAME - Use DOS format
FSI_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*/
unsigned short d_namlen; /* Length of filename *I
char d_name[MAXNAMLEN+l]; /*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 (FSI_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 FSl_getextattr
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 (FSI_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_EXTATTRS stream
Open or create the stream
Dispatch FSI_lock for whole file containing stream
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

250

PATHWORKS File System

Dispatch FSLIB_ffilesize
IF no stream THEN BEGIN
IF return buffer large enough THENset return buffer to indicate no attributes
Set size of return buffer
END
ELSE BEGIN
Dispatch FSl_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 FSI_unlock
Dispatch FSI_close
END

D .3 .23 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 FSl_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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

251

PATHWORKS 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 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_PATHID *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 FSI_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 FSI_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 FSI_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 FSI_NOEXIST
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

252

PATHWORK.S File System

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 FSI_lock
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:
FSI_lock (FSI_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 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 set end of lock to UNIX limit
Dispatch FSLIB_lock (fp, type, offset, whence, length, dowait, start)
IF NFS not running THEN 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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

253

PATHWORK.S File System

END

D .3 .25 FSI_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 (FSI_FID *fp, offset, whence)

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

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

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

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

D .3 .27 FSI_fmapname
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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

254

PATHWORKS File System

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

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

D. 3. 2 8 FSI_mkdir
Description:
This function will create a directory.

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

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

Algorithm:
BEGIN
IF directory exists THEN error
IF readonly THEN error
Dispatch FSLIB _mk:dir(pathid, mode, dirid)
Dispatch FSLIB_chown(pathid, uid, gid)
Set volume modify time
END

D.3.29 FSI_mpxclose
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:
FSl_mpxclose (FSI_FID *fp)

Algorithm:
BEGIN
IF NOT fp multiplex closed THEN Dispatch FSLIB_mpxclose (fp)
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

255

PATHWORKS File System

END

D .3 .30 FSI_needfds
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 dup() a file descriptor THEN BEGIN
close() 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 FSI_needinodes
Description:
This function will multiplex close a number of files.

NOTE
This routine is primarily for internal FSI use.

Synopsis:
FSI_needinodes(timescalled, FSLIB_ptrs)

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

D .3 .32 FSI_open
Description:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

256

PATHWORKS File System

This function will open a data stream for read or write access.

Synopsis:
FSl_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 THEN 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 THEN start multiplex close
IF too many open files THEN 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 THEN Dispatch FSLIB_fchown (fp, uid, gid)
Dispatch FSLIB_fstat (fp, FSI_ST_USTAT, &fp->status)
IF FSI_PRIMARY THEN pathid->status = fp->status;
END
END
END

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

Synopsis:
FSI_purge (FSI_PATHID *pathid)
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

257

PATHWORKS File System

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 FSI_read
Description:
This function will read data from the file.

Synopsis:
FSI_read (FSl_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 FSI_rename
Description:
This function will rename a file.

Synopsis:
FSl_rename (FSI_PATHID *old,FSI_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
Dispatch FSLIB_rename
IF MAC application THEN update desktop
Set volume modify time
END

D.3.36 FSI_rmdir
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

258

PATHWORKS File System

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:
FSI_rmdir (FSl_PATHID *pathid)

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

D.3.37 FSI_setattr
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 FSI_fsetattr
Description:
This function will set the file's attributes. These attributes are those which the FSI
operates on.

Synopsis:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

259

PATHWORKS File System

FSI_fsetattr (FSl_FID *fp, attrip)

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 .39 FSI_setcomment
Description:
This function will associate a string of up to 199 characters with a file name.

Synopsis:
FSI_setcomment (FSI_PATHID *pathid, string)

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

D .3 .40 FSI_setextattr
Description:
This function will add, delete or modify extended attributes associated with a file. The
GEA list member of the EAOPS 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 (FSI_PATHID *pathid, FSI_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_EXTA'ITRS stream
Open or create the stream
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

260

PATHWORKS File System

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
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 FSI_unlock
Dispatch FSI_close
END

D .3 .41 FSl_setlognores
Description:
This function specifies a routine for the FSI to call when resources have been
exhausted.

Synopsis:
FSI_setlognores (routine)

Algorithm:
BEGIN
Set FSI_LogNoResource to routine
END

D .3 .42 FSI_setnotifympx
Description:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

261

PATHWORKS File System

This function specifies a routine for the FSI to call when multiplexing begins.

Synopsis:
FSI_setnotifympx (routine)

Algorithm:
BEGIN
Set FSl_notifympx to routine
END

D .3 .43 FSI_shortpath
Description:
This function will set the short path element of the FSI_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 (FSI_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 FSI_stat
Description:
This function will return file statistics in the UNIX stat format.

Synopsis:
FSI_stat (FSI_PATHID *pathid, 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
Dispatch FSLIB_stat
IF stream is FSI_PRIMARY THEN copy statbufp to pathid status
END
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

262

PATHWORK.S File System

D .3 .45 FSI_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)
Dispatch FSLIB_stat
IF stream is FSI_PRIMARY THEN copy statbufp to fp status
END

D .3 .46 FSI_statvfs
Description:
This function will return file information in a UNIX statvfs structure.

Synopsis:
FSI_s~tvfs (FSI_PA THID *pathid, statvfsbufp)

Algorithm:
BEGIN
Dispatch FSLIB_statvfs
END

D .3 .4 7 FSI_fstatvfs
Description:
This function will return file information in a UNIX statvfs structure.

Synopsis:
FSI_fstatvfs (FSI_FID *fp, statvfsbufp)

Algorithm:
BEGIN
IF fp multiplex closed THEN Dispatch FSLIB_mpxopen (fp)
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

263

.PATHWORK.S File System

Dispatch FSLIB_fstatvfs
END

D .3 .48 FSI_sync
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 FSI_ftruncate
Description:
This function will truncate a file.

Synopsis:
FSI_ftruncate (FSI_FID *fp, offset)

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

D .3 .5 0 FSl_tretop
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 (FSI_PATHID *pathid, treetop)

Algorithm:
BEGIN
IF treetop in full path THEN set treetop
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

264

PATHWORKS File System

ELSE error
END

D.3.51 FSI_unlock
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:
FSI_unlock (FSI_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 set end of lock to UNIX limit
Dispatch FSLIB_unlock
Allow multiplex closing this file (decrement reason)
END
END

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

Synopsis:
FSl_unmap (FSI_FID *fp)

Algorithm:
BEGIN
Dispatch FSLIB_unmap
END

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

265

PATHWORKS File System

D .3 .53 FSI_utime
Description:
This function will set the modification time of a file.

Synopsis:
FSI_utime (FSl_PATHID *pathid, timebufp)

Algorithm:
BEGIN
Dispatch FSLIB_utime
END

D .3 .54 FSI_futime
Description:
This function will set the modification time of a file.

Synopsis:
FSl_futime (FSI_FID *fp, timebufp)

Algorithm:
BEGIN
Convert fp to pathid
Dispatch FSLIB_utime
END

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

Synopsis:
FSI_write (FSl_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 THEN unlock record
END
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

266

PATHWORK.S 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 first 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 coDntext 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
June 9, 1993
Digital Confidential - 3rd Party Restrictions Apply

267

PATHWORKS File System

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.
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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

268

PATHWORKS File System

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 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.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

269

PATHWORKS File System

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 BOS 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 define 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.
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 turn 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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

270

PATHWORKS File System

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 de-blocking. 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. $TRUNCATE would simply convert the mapping
pointers in the Macintosh file header to FREE pointers.
E.2.4.1 EXT_CONNECT
RMS $CONNECT callout routine.
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 routine.
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.
This routine completely replaces the normal RMS $GET function.
E.2.4.3 EXT_PUT
RMS $PUT callout routine.
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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

271

PATHWORKS File System

RMS $FIND callout routine.
The $FIND callout simply sets the next VBN and BUFPfR 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 routine.
The $DISCONNECT callout writes out the final 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 routine.
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
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 numberofbuffers 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
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

272

PATHWORKS File System

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.
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.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

273

PATHWORK.S File System

Appendix F - File System Confiauration Parameters
This appendix lists the parameters which control the file system. Many parameters are
present for tuning and evaluation of various file system features. The system is
configured to run with default settings and feedback provided by the Configuration
Monitor may change these defaults. Care needs to be taken when modifying these
parameters.

F .1

PFS File System

Name: [PFS] RW_USE_CACHE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables use of the global data cache within PFS. The
parameter should only be cleared for file system testing.

Name: [PFS] TRAP_ACCVIO
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables trapping exception generated by PFS or a file
system library. When set, exceptions are converted to function failures. When
clear, exceptions cause process termination.

Name: [PFS] FILE_SEARCH
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables searching for directories when a file
specification is received from the client. If the parameter is set PFS will look for
a directory of the name specified if a file of that name is not found. If the
parameter is clear PFS will return PFS_NOEXIST if the file is not found.
There have been changes made to the server which may require
this parameter to be set always.

Name: [PFS] STAT_COLLECT
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables collection of PFS run time statistics. These
statistics count the number of functions issued and the amount of time taken by
various functions. This collection is not free and degrades performance less than
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

274

PATHWORKS File System

5%. This parameter should only be enabled for performance tuning related
workloads.

Name: [PFS] INIT_FATAL
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables process exit on initialization failures.

Name: [PFS] COPY_BUFSIZ
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 8192
Minimum: 512
Maximum: 8192
Description:
This parameter controls the size of the buffer used by PFS_copyfile(). The
buffer is allocated from process memory and released prior to function
completion. The buffer controls the size of data reads during copy operations.

Name: [PFS] SECURITY_MODE
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 1
Minimum: 1
Maximum: 3
Description:
This parameter controls the security mode in which PFS operates. Legal values

are:
1 - NOS security
Never check host security.
2 - HOST security
Always check host security.
3 - CREATOR security
Check host security only if the file was not created
by the server.

If an illegal value is specified the parameter is defaulted to NOS security.

F .2

ODS2 File System

Name: [ODS2] CHKPRO_ENABLE
Type: BOOLEAN
Scope: CLUSTER-WIDE
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

275

PATHWORKS File System

Default: 1
Description:
This parameter enables or disables CHKPRO access checking. CHKPRO is
called when the server is running in HOST or CREATOR security mode. The
check may be disabled entirely by setting this parameter to "0".

Name: [ODS2] PATH_CHKPRO_ENABLE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables CHKPRO access checking on the path to a
file. CHKPRO is called when the server is running in HOST or CREATOR
security mode. The check may be disabled entirely by setting this parameter to
"0". Path checking is provided to comply with "the most paranoid of paranoid"
and is not free nor even cheap. With the path cache and FID cache the effect is
reduced, however, it is suggested that this parameter be disabled unless a
specific workload requires it.

Name: [ODS2] DATA_CACHE_ENABLE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables the internal ODS2 data cache. This cache is
used for record de-blocking of read-only files (VFC format) and as a backup to
the global data cache (test mode only). If the cache is disabled the blocks will be
read from disk as necessary.

Name: [ODS2] DIR_CACHE_ENABLE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables the directory cache in ODS2. The directory
cache holds the contents of directories and is used for enumerates.
The directory cache is sychronized with the XQP+ and with the XQP in a
cluster. Standalone systems using the XQP can not use directory caching. This
parameter will be ignored if the XQP+ is not present or if the system is not in a
cluster.

Name: [ODS2] DIR_CACHE_SIZE
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 256
Minimum: 4
Maximum: unlimited
Equation: MAX_CLIENT * SHARES_PER_CLIENT
Description:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

276

PATHWORKS File System

This parameter controls the number of directories which will be cached. Block
are allocated for the directory entries as needed. The parameter
[ODS2]DIR_CACHE_MAX_BLOCKS controls the size of a directory which
may be cached. The total number of blocks allocated to the directory cache is
[ODS2]DIR_CACHE_SIZE * [ODS2]DIR_CACHE_MAX_BLOCKS.

Name: [ODS2] DIR_CACHE_MAX_BLOCKS
Type: Integer
Scope: CLUSTER-WIDE
Default: 32
Minimum: 4
Maximum: 256
Equation: None
This parameter controls the size of the largest directory which may be cached.
Directories larger than this number (in blocks) will be accessed using direct
QIOs.

Name: [ODS2] FID_CACHE_SIZE
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 2048
Minimum: 256
Maximum: unlimited
Equation: MAX_OPEN_FILES * 2.5
Description:
This parameter controls the size of the file header cache, in blocks. The cache
should be large enough to hold the maximum number of concurrently open files
supported X 2 plus enough space for general header caching.

Name: [ODS2] FllB_FID_LOCKING
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables using Fl lB (XQP) locks to track host
modifications to FID cache entries. This feature will only work with the XQP+
or the XQP when in a cluster.

Name: [ODS2] FllB_PATH_LOCKING
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables using the Fl lB (XQP) volume allocation lock
as a means of detecting path modifications. This feature will work with all
configurations· of XQP or XQP+. This parameter should be enabled for host
concurrency.

Name: [ODS2] PATH_CACHE_ENABLE
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

277

PATHWORKS File System

Type: BOOLEAN
Scope: CLUSTER-WIDE

Default: 1
Description:
This parameter enables or disables the ODS2 path cache. The cache holds
recently translated paths and attributes associated with the path. This feature
provides a very high performance gain and should be enabled at all times.

Name: [ODS2] PATH_CACHE_SIZE
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 256
Minimum: 32
Maximum: unlimited
Equation: MAX_CLIENT * SHARES_PER_CLIENT * 4 (average directory depth)
Description:
This parameter controls the size of the path cache, in entries. The path cache is a
process specific cache and is allocated from process memory. The size of the
cache needs to be weighed against path invalidation activity. A general rule may
be 20 X number of clients associated with the process.

Name: [ODS2] OK_TO_LIE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables reading non stream files when they are open
to determine the exact byte count in the file. This is obviously very slow and if
the client can tolerate an estimated count this parameter should be enabled.

Name: [ODS2] CHECK_BINARY
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables scanning the first 256 characters of a newly
created file to determine if it is binary or text. A file is considered binary if 20%
of the first 256 characters are non-printable or if 3 CR/LF pairs are not seen. If a
file is determoned to be binary, its format is converted to FIXED 512. If this
parameter is disabled, all files will be created as STREAM.

Name: [ODS2] FID_TIMER_INTERVAL
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 6
Minimum: 0
Maximum: 65535
Description:

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

278

PATHWORKS File System

This parameter controls the number of interval, in seconds, between FID cache
scanning for expired entries. If this parameter is defined a "0" the mechanism is
disabled. Each entry in the FID cache is given an initial count (see below) which
is decremented each interval. When the count reaches 0 the entry may no longer
be hit and must be fetched from disk.
Open files are aged in a similar fashion. However, they are not invalidated.
Instead any modifications are written back to disk on the next reference
following the expiration of the timer.

Name: [ODS2] FID_TIMER_COUNT
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 5
Minimum: 0
Maximum: 65535
Description:
This parameter controls the number of intervals in which a FID cache entry may
be hit. There is a very high hit rate within a short period of entering a FID cache
entry. The hit rate drops off fairly quickly such that invalidation of 20 seconds or
so does not decrease performance significantly. The tradeoff is long term hit rate
(i.e. subsequence access to the same file). This is a workload specific variable
and is difficult to predict. The short term hit rate is due to the server architecture
and is very predictable.

Name: [ODS2] FID_TIMER_STACK_SIZE
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 4096
Minimum: 1024
Maximum: unlimited
Description:
This parameter controls the size of the stack allocated to the FID cache timer
thread. The stack must be large enough to allow delivery of ASTs.while the
thread is executing.

Name: [ODS2] THREAD_SWITCH_HEADER
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables thread switching on file header access. In
single thread operation there is a nominal performance increase when switching
is disabled. However, this parameter
should be set for all "live" server workloads.

Name: [ODS2] THREAD_SWITCH_DATA
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

279

PATHWORKS File System

This parameter enables or disables thread switching on file data access. In single
thread operation there is a nominal performance increase when switching is
disabled. However, this parameter should be set for all "live" server workloads.

Name: [ODS2] Fl lB_MAX_THREAD
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 8
Minimum: 0
Maximum: 8
Description:
This parameter controls the number of Fl lB (XQP+) threads allocated to the
process. Details of this parameter are not yet known but it is felt the parameter
should be set to its maximum value, 8. Non XQP+ environments ignore this
parameter.

Name: [ODS2] Fl lB_DEFER_WRITE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables Fl lB (XQP+) deferred writes. There is a
significant performance advantage in seting this parameter. It should be set to
"1" for all XQP+ environments. XQP+ environments ignore this parameter.

Name: [ODS2] CASE_SENSITIVE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter controls cacse-sensitive file creates in the ODS2 library. If the
parameter is set all lower case letters in the filename are escaped, i.e. _XX. If
the parameteris not set all lower case letters are converted to uppercase.

Name: [ODS2] EXTEND_QUANTITY
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 32
Minimum: 0
Maximum: 65535
Description:
This parameter controls the number of blocks allocated to a file when it is
extended. There is a tradeoff between the time taken to allocte the blocks and the
number of times a file will need to be extened. The 4.x server has found this
value to be optimal at 80. However, XQP+ studies have shown advantages up to
256 blocks per extend. The overall disk space waste vs file extend time needs to
be considered when setting this parameter. If "0" is specified, the default extend
quantity (set when the volume is initialized ) is used.
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

280

PATHWORKS File System

Name: [ODS2] CREATE_QUANTITY
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 32
Minimum: 0
Maximum: 65535
Description:
This parameter controls the number of blocks allocated to a file when it is
created. There may be a performance advantage in XQP environments when the
initial allocation size is high. However, it has been seen that performance is
seriously degraded when using the XQP+ and modest allocation sizes (64). If
the parameter is set to "0 11 the default extend quantity is used.

Name: [ODS2] STAT_COLLECT
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables collection of ODS2 run time statistics. These
statistics count the number of functions issued and the amount of time taken by
various functions. This collection is not free and degrades performance between
5-10%. This parameter should only be enabled for performance tuning related
workloads.

Name: [ODS2] DEFER_WRITE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables "ganging" of disk writes. When set all writes
in a descriptor list are issued asynchronously. The completion routine for each
buffer decrements the gang count and resumes the thread when 0. If the
parameter is not set each buffer is written serially, allowing thread switch
between based on [ODS2] THREAD_SWITCH_DATA.

Name: [ODS2] TEST_MODE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter is used for file system verification only. It should not be set for
"live" workloads.

Note
This parameter forces all caches to process specific. It may be used for
other internal test purposes as well.

Name: [ODS2] CLUSTER_SYNC
Type: BOOLEAN
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

281

PATHWORKS File System

Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables FID cache cluster wide synchronization. This
parameter may be cleared to increase performance when running a standalone
server in a cluster. By default, cluster synchronization is only performed when
running in a cluster. This synchronization may be disabled with this parameter.
TEST_MODE
0

0
1
1

CLUSTER_SYNC

0
1
0
1

Result
Sync Disabled
Enabled if in cluster
Sync Disabled
Sync Enabled

Name: [ODS2] USE_CHANNEL_MPX
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables ODS2 to use channel multiplexing, aka 4.x. Channel
multiplexing allows more channels to be used that the SYSGEN
CHANNELCNT parameter would otherwise allow. This parameter should be
set for all "live" workloads.

Note
This parameter does not actually enable channel multiplexing but rather
enables ODS2 to use it. Channel multiplexing is controlled with the
[HOST] ENABLE_CHANNEL_MPX parameter. If channel
multiplexing is disabled the calls are vectored to normal system channel
functions. For this reason, ODS2 should always be configured to use
channel multiplexing. This parameter is for debug purposes only.

Name: [ODS2] CHECK_RESOURCE_ID
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables checking the parent directory for ownership
by a resource ID. If enabled the file or directory created will have the resource ID
as the owner if the user specified holds that identifier. If disabled the file or
directory is created with the owner specified.

Name: [ODS2] REPORT_RESOURCE_ID
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables checking the root directory for ownership by
a resource ID. If enabled the volume size is reported as the quota established for
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

282

PATHWORKS File System

the resource, if quotas are enabled and if the user specified holds the resource
identifier. If the above fails or if the parameter is disabled the user's UIC is
checked for quotas and if none set the disk allocation statistics are reported.

Name: [ODS2] GENERATE_OWNER_ACE
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter enables or disables the generation of a protection ACE granting
the creator access to a file owned by a resource. The parameter only has effect if
[ODS2] CHECK_RESOURCE_ID is enabled and if the created file or directory
is determined to be owned by a resource ID. If the parameter is dsiabled, no
ACE is generated.

Name: [ODS2] EXTEND_CONTIG
Type: Boolean
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter controls file extents. When set, extents will be allocated
contiguous-best-try. This reduces fragmentation as well as improving file system
read/write performance.

Name: [ODS2] CREATE_CATHEDRAL
Type: Boolean
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter creates cathedral windows for initial file extents. This allows the
window control block to be set up prior to deferred XQP+ header/directory
writebacks. If file data writes occur during the writeback period they may
proceed if the window control block is initilaized. They
will stall otherwise.

F .3

FAT File System

Name: [FAT] RESOURCE_WAIT_MODE
Type: Boolean
Scope: CLUSTER-WIDE
Default: 1
Description:
This parameter controls the action taken when resources controlled by the FAT
file system are not available. If set the file system will stall until the resources
become available. If clear the file system will fail.

Name: [FAT] DIR_CACHE_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 256
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

283

PATHWORKS File System

Minimum: 64
Maximim: Unlimimited
Description:
This parameter controls the size of the FAT directory cache in blocks.

Name: [FAT] DIR_HASH_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 0
Minimum: 0
Maximim: Unlimited
Description:
This parameter controls the hash table length for the FAT directory cache. If set
to 0 the length is calculated internally.

Name: [FAT] DIR_CACHE_BLOCK_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 2048
Minimum: 512
Maximim: 8192
Description:
This parameters sets the size of the directory cache block in bytes. The cache
block size will be rounded to the next multiple of a disk block.

Name: [FAT] FAT_CACHE_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 256
Minimum: 256
Maximim: Unlimited
Description:
This parameter controls the size of the FAT FAT cache in blocks.

Name: [FAT] FAT_HASH_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 0
Minimum: 0
Maximim: unlimited
Description:
This parameter controls the hash table length for the FAT FAT cache. If set to 0
the length is calculated internally.

Name: [FAT] FAT_CACHE_BLOCK_SIZE
Type: Integer
Scope: CLUSTER-WIDE
Default: 1536
Minimum: 1536
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

284

PATHWORKS File System

Maximim: Unlimited
Description:
This parameter controls the size of the FAT cache block. The value will be
routined to the next multiple of 1536 to insure that 12 bit FATs will never cross
block boundaries.

Name: [FAT] EXTEND_QUANTITY
Type: Integer
Scope: CLUSTER-WIDE
Default: 0
Minimum: 0
Maximim: 65535
Description:
This parameter controls the number of blocks allocated to a file when it is
extended. There is a tradeoff between the time taken to allocte the blocks and the
number of times a file will need to be extened. The 4.x server has found this
value to be optimal at 80. However, XQP+ studies have shown advantages up to
256 blocks per extend. The overall disk space waste vs file extend time needs to
be considered when setting this parameter. If ''0" is specified, the extend
quantity is set to the number of blocks required to satisfy a write request.

Name: [FAT] CREATE_QUANTITY
Type: Integer
Scope: CLUSTER-WIDE
Default: 0
Minimum: 0
Maximim: 65535
Description:
This parameter controls the number of blocks allocated to a file when it is
created. If the parameter is set to 0 the first cluster of a file is allocated when the
file is created.

Name: [FAT] MAX_CONTAINERS
Type: Integer
Scope: CLUSTER-WIDE
Default: 65535
Minimum: 1
Maximim: 65535
Description:
This parameter controls the size of the FAT container registration namespace.

Name: [FAT] DEFER_FAT_WRITES
Type: Boolean
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter controls deferred writes to the File Allocation Table. When set,
writes are performed asynchronously. It is not suggested this option be used,
except in the most performance critical application because there will be a
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

285

PATHWORKS File System

window where FAT writes and directory writes may not be properly sequenced.
If the system crashes during this window there may be directory entries left

pointing to non allocated FAT entries. This may lead to container file corruption.

Name: [FAT] DEFER_DIR_WRITES
Type: Boolean
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter controls directory cache writebacks. If set, the writes will be
done asynchronously. Setting this bit may lead to missing files in the directory if
the system crashes before the directory entry is written. However, no container
file corruption can occur if [FAT] DEFER_FAT_WRITES is not set. The only
possibility is there will be orphan clusters allocated.

Name: [FAT] DEFER_IO_WRITES
Type: Boolean
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter controls writes to normal data blocks in the container file. It is
not currently used.

Name: [FAT] STAT_COLLECT
Type: Boolean
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables collection of file system statistics. It is used for debug
only.

F .4

DEBUG Facility

Name: [DEBUG] LIB_TRACE_MEMORY
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or disables logging of each memory allocation and
release. It should normally be set to "0".

Name: [DEBUG] LIB_TRACK_MEMORY
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 0
Description:
This parameter enables or diables tracking of each memory allocation and
release. Each memory allocation contains an additional header and is queued to
an "inuse" queue along with a string describing the memory and a class of
June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

286

PATHWORK.S File System

allocation. The queue may be displayed to determine if all memory allocated
during a test has been released. This parameter is for test use only and should
normally be set to "0".

F. S

Channel Multiplexing

Name: [HOST] RESERVED_CHANNELS
Type: INTEGER
Scope: CLUSTER-WIDE
Default: 500
Minimum: 10
Maximum: 2047
Description:
This parameter is the mimimum number of channels to reserve for nonmultiplexed use. Typical values would be between 30 and 60 depending on the
number of server specific files which can be open simultaneously, number of
global sections backed by a separate page file, log files, etc. PFS will use the
remainder (SYSGEN param CHANNELCNT - [HOST]
RESERVED_CHANNELS) for multiplexing client file open requests.

Note
This parameter is fixed in the V4 server. Since Hydra has many more
non-multiplexed files than does V4 and the front end server itself is
variable, this count needs to be variable.

Name: [HOST] ENABLE_CHANNEL_MPX
Type: BOOLEAN
Scope: CLUSTER-WIDE
Default: 1
Description:
Enable channel multiplexing. By default, all PW_xxx calls use normal direct IO.
When channel multiplexing is enabled, the call use PATHWORKS extended
channels.

June 9, 1993

Digital Confidential - 3rd Party Restrictions Apply

287

Networks Engineering Services

Ef\ID OF JOB
LKG2P1 ::RANGER::BRADLEY

JOB 431
PFS FUNCTIONAL SPEC BL4

20-APR-1994 17:00
s nt
20-APR-1994 17:00

%DCPS-W-UNDEF, undefined: Name not known - offending command i
%DCPS-E-FLUSHING, Rest of Job (to EOJ) will be ignored

Owner UIC:
Account:

[DQS$SERVER]
TOOTER::

Priority:
Submit queue:
Submitted:
Printer queue:
Printer device:
Started:
Finished:

100
LKG21_04
20-APR-1994 16:04
LKG21_04
4LPS04
20-APR-1994 16:29
20-APR-199417:00

Qualifiers:
Parameters:
Sheets printed:

/FORM=CPS$DEFAULT /FLAG
DATA_TYPE=POSTSCRIPT, PAGE_SIZE=A, SHEET_SIZE=A
146

Digital Equipment Corporation

PrintServer 20 4LPS04

OpenVMS VAX system V5.5-2 DECprint Supervisor V1 .OB