KNOWN FILES: THE INTERNALS OF INSTALL DAVID SCHWAB Demax Software ------------------------------------------------------------------------------- OVERVIEW o Why do we use INSTALL? o What VMS data structures involved? o What happens when you ADD a file in INSTALL? o What other pieces of VMS use the data structures? o Example: a program to read the data structures. ------------------------------------------------------------------------------- WHY DO WE USE INSTALL? o Install a file /OPEN for faster opening by any process o Install an image /HEADER_RES for faster image activation o Install an image /PRIVILEGED so non-privileged users can perform privileged operations o Install an image /SHARED so that code segments can be shared between processes, reducing system memory requirements. o Install an image /ACCOUNTING to activate image level accounting. - When you do any of these things you are entering a file, specifying certain parameters, in the Known Files Database (KFDB). ------------------------------------------------------------------------------- KFPB o Known File Pointer Block (KFPB) is the head of a hierarchy of data structures. o Global location EXE$GL_KNOWN_FILES points to it. o Allocated in paged pool, initialized, and EXE$GL_KNOWN_FILES set when the first known file is created. o Offsets can be found in module $KFPBDEF in SYS$LIBRARY:LIB.MLB. ------------------------------------------------------------------------------ KFPB ------------------------------------------------------------- | KFPB$L_KFDLST | ------------------------------------------------------------- | KFPB$L_KFEHSHTAB | ------------------------------------------------------------- | KFPB$B_SPARE | KFPB$B_TYPE | KFPB$W_SIZE | ------------------------------------------------------------- | KFPB$W_HSHTABLEN | KFPB$W_KFDLSTCNT | ------------------------------------------------------------- ------------------------------------------------------------------------------- KFPB Fields o KFPB$L_KFDLST - points to the first KFD (see below) o KFPB$L_KFEHSHTAB - points to the Known File Hash Table (see below) o KFPB$W_SIZE - size of the KFPB. Will always be KFPB$K_LENGTH (16) o KFPB$B_TYPE - Always holds DYN$C_KFPB (68). Marks this structure as a KFPB o KFPB$B_SPARE - not used o KFPB$W_KFDLSTCNT - Total number of KFEs and KFDs in the KFDB o KFPB$W_HSHTABLEN - The length of the Known File Hash Table in longwords. Currently 128. ------------------------------------------------------------------------------- KFD o Known File Directory (KFD) block holds device, directory and file type information o One per device/directory/file type combination o In linked list, list head KFPB$K_KFDLST in KFPB o Offsets found in $KFDDEF in SYS$LIBRARY:LIB.MLB o Allocated in paged pool in maximum size possibly needed (242 bytes) o Linked list in lexical order on KFD$T_DDTSTR ------------------------------------------------------------------------------- KFD ------------------------------------------------------------- | KFD$L_LINK | ------------------------------------------------------------- | KFD$L_KFELIST | ------------------------------------------------------------- | KFD$B_SPARE | KFD$B_TYPE | KFD$W_SIZE | ------------------------------------------------------------- | KFD$B_DIRLEN | KFD$B_DEVLEN | KFD$W_REFCNT | ------------------------------------------------------------- | KFD$T_DDTSTR |KFD$B_DDTSTRLEN| | ----------------- | | | | ------------------------------------------------------------- ------------------------------------------------------------------------------ KFD Fields o KFD$L_LINK - pointer to next KFD o KFD$L_KFELIST - list head for KFEs associated with this KFD o KFD$W_SIZE - total size used in the KFD. KFD$C_LENGTH (17) plus KFD$B_DDTSTRLEN o KFD$B_TYPE - DYN$C_KFD. Marks this structure as a KFD. o KFD$B_SPARE - not used o KFD$W_REFCNT - number of KFEs in KFE list pointed to by KFD$L_KFELIST o KFD$B_DEVLEN - length of device portion of string stored at KFD$T_DDTSTR o KFD$B_DIRLEN - length of directory portion of string stored at KFD$T_DDTSTR o KFD$B_DDTSTRLEN - length of string stored at KFD$T_DDTSTR o KFD$T_DDTSTR - directory and file type specification for the known files in the KFE list pointed to by KFD$L_KFELIST. May be up to NAM$C_MAXRSS (255) characters in length. ------------------------------------------------------------------------------- KFE o Known File Entry (KFE) describes the rest of the information o One per known file o KFEs associated with a given KFD are in a linked list, with list head at KFD$L_KFELIST in the KFD o Offsets found in $KFEDEF in SYS$LIBRARY:LIB.MLB o The KFE list headed in a KFD is maintained in lexical order on KFE$T_FILNAM. o Allocated in paged pool. Only the space required (KFE$W_SIZE) is allocated. ------------------------------------------------------------------------------- KFE ------------------------------------------------------------- | KFE$L_HSHLNK | ------------------------------------------------------------- | KFE$L_KFELINK | ------------------------------------------------------------- | KFE$B_HSHIDX | KFE$B_TYPE | KFE$W_SIZE | ------------------------------------------------------------- | KFE$L_KFD | ------------------------------------------------------------- | KFE$W_GBLSECCNT | KFE$W_FLAGS | ------------------------------------------------------------- | KFE$L_USECNT | ------------------------------------------------------------- | KFE$L_WCB | | KFE$W_FID_SEQ | KFE$W_FID_NUM | ------------------------------------------------------------- | KFE$L_IMGHDR | | | KFE$W_FID_RVN | ------------------------------------------------------------- | KFE$Q_PROCPRIV | | | ------------------------------------------------------------- | KFE$W_AMECOD | (unused) | KFE$B_MATCHCTL| ------------------------------------------------------------- | KFE$L_IDENT | ------------------------------------------------------------- | KFE$L_ORB | ------------------------------------------------------------- |KFE$T_FILNAM |KFE$B_FILNAMLEN| KFE$W_SHRCNT | | | | | ------------------------------------------------------------- ------------------------------------------------------------------------------- KFE Fields o KFE$L_HSHLNK - Pointer to next KFE with the same hash value o KFE$L_KFELINK - Pointer to next KFE which shares the same KFD. o KFE$W_SIZE - Total size of KFE. KFE$C_LENGTH (55) plus the value stored in KFE$B_FILNAMLEN. o KFE$B_TYPE - DYN$C_KFE. Marks this structure as a KFE o KFE$B_HSHIDX - The index for this KFE in the KFE hash table o KFE$L_KFD - a pointer to the KFD for this KFE. o KFE$W_FLAGS - Option flags for this KFE. The following bits are used: KFE$V_PROTECT (0) - Installed /PROTECT KFE$V_LIM (1) - Known file is a shareable image KFE$V_PROCPRIV (2) - Installed /PRIVILEGE KFE$V_OPEN (3) - Installed /OPEN KFE$V_HDRRES (4) - Installed /HEADER_RESIDENT KFE$V_SHARED (5) - Installed /SHARED KFE$V_SHMIDENT (6) - Global section name has a shared memory ident. Only for old style shared memory. KFE$V_COMPATMOD (7) - Known file is a compatibility mode image KFE$V_NOPURGE (8) - Installed /NOPURGE KFE$V_ACCOUNT (9) - Image accounting enabled for this known file. KFE$V_WRITEABLE (10) - Installed /WRITE KFE$V_EXEONLY (11) - Installed /EXECUTE_ONLY o KFE$W_GBLSECCNT - For shared images, number of global sections that are mapped for the image o KFE$L_USECNT - The number of users of this image since it was installed. o KFE$L_WCB - Address of the Window Control Block for the KFE (Only if installed /OPEN) o KFE$L_IMGHDR - Pointer to the Known File Resident Header (KFRH) block for this image (See below) (Only if installed /HEADER_RES) o KFE$W_FID_NUM\ o KFE$W_FID_SEQ > The File ID if the image is not installed /OPEN o KFE$W_FID_RVN/ o KFE$Q_PROCPRIV - Quadword privilege mask specifying the privileges with which the image is installed. o KFE$B_MATCHCTL - match control information for global sections, sup- plied when the image was linked. o KFE$B_AMECOD - If a compatibility mode image, indicates which AME (Application Migration Executive) would be used. In fact, the RSX AME is the only one ever supported. o KFE$L_IDENT - For a shared image, generally the IHD$L_IDENT field from the image header. If it's a shareable image and match control is 0, then this is also 0. Also, if there is a shared memory ident, then further convolutions are necessary. o KFE$L_ORB - An ORB is an Object Rights Block, but VMS doesn't seem to use them o KFE$W_SHRCNT - For shared images, the number of processes using it. It is always at least one (Since the system has it open) The image activator updates this to the Reference Count field of the WCB. o KFE$W_FILNAMLEN - The length of KFE$T_FILNAM o KFE$T_FILNAM - Name portion of the Known File filename. ------------------------------------------------------------------------------ KFE Hash Table o Created when the KFPB is created. o Currently has 128 entries. o Hashing function: Add all characters of file name together, mask with hex 7F so the result is between 0 and 128. o Hash table entries either 0 or pointer to a KFE. o Multiple KFEs sharing a hash value are linked on KFE$L_HSHLNK o Within hash list, KFEs maintained in lexicographic order. o Provides means of finding a KFE given the filename without having to scan entire KFDB. ------------------------------------------------------------------------------ KFRH o Known File Resident Header (KFRH) blocks describe resident header for /HEADER_RES images o Also has image section descriptors for each image section for /SHARED imaged o Allocated in paged pool. o Pointed to by KFE$L_IMGHDR o Offsets found in $KFRHDEF in SYS$LIBRARY:LIB.MLB ------------------------------------------------------------------------------ KFRH ------------------------------------------------------------- | KFRH$L_BUFEND | ------------------------------------------------------------- | | KFRH$W_ALIAS | ------------------------------------------------------------- | KFRH$B_HDRVER| KFRH$B_TYPE | KFRH$W_SIZE | ------------------------------------------------------------- | KFRH$T_IHD | | | | | ------------------------------------------------------------- ------------------------------------------------------------------------------ KFRH Fields o KFRH$L_BUFEND - address of end of file header data o KFRH$W_ALIAS - image type. Determines whether native mode, compatibility mode, or a CLI. o KFRH$W_SIZE - total size of structure o KFRH$B_TYPE - DYN$C_KFRH o KFRH$B_HDRVER - header version o KFRH$T_IHD - the image header data. ------------------------------------------------------------------------------ What INSTALL does to ADD a known file (See VMS source listing INSCREATE.LIS in the INSTAL directory) 0. The file is opened. 1. A new KFE is initialized in local memory for the image. 2. KFE$W_FLAGS bits set depending on install options. 3. If /PRIVILEGE, privilege mask is moved into KFE. 4. If no KFD exists for the file's directory, one is initialized for it in local memory. KFE$L_KFD field is set. 5. If /PRIV, /HEADER, or /EXE, system version in image header checked against current system version, if linked against SYS.STB. 6. If /PRIV or /EXE, make sure image not linked with traceback. 7. If not /OPEN, stuff the FID into the three FID words. 8. If /OPEN and this is a shareable image, set the LIM flag. 9. If /HEADER, image header major and minor ids are checked. 10. If /SHARED, set KFE$B_MATCHCTL, KFE$L_IDENT. 11. If /HEADER, allocate virtual memory and copy the header into it. If /HEADER and /SHARED, concatenate each ISD to stored header. If /SHARED, create global sections for the images private sections. 12. If /HEADER, allocate KFRH in paged pool. It is filled in and the stored header and ISDs are copied to it. The temporary copies in virtual memory are deallocated. KFE$L_IMGHDR is set to point to KFRH$T_IHD. 13. If /OPEN, KFE$W_SHRCNT is initialized to 1 and KFE$L_WCB is filled in. The WCB$W_REFCNT field is incremented so that the file will remain open when INSTAL exits. 14. Now allocate a real KFE in paged pool. Copy one we have built to it. Create KFPB and allocate KFE Hash Table if not already done. Insert KFE in hash structure. Increment KFPB$W_KFDLSTCNT. 15. If not yet a permanent KFD for this KFE, allocate one in paged pool and copy temporary one we built above, inserting it in KFD list, incrementing KFPB$W_KFDLSTCNT. Set KFE$L_KFD. 16. KFD$W_REFCNT is incremented 17. KFE is now inserted in the KFD's KFE list. ------------------------------------------------------------------------------- Other modules that reference KFDB o DISMOUNT - checks for installed files on a disk to be dismounted. o RMS - when opening a file, scans KFE hash table to search for file if an explicit version number is not given. If found and the user is allowed to open the file, the KFE address is put in the FAB$L_CTX field of the FAB. o IMAGE ACTIVATOR - will use the stored header and image section descriptors if available, as well as several of the flags in the KFE. Increments KFE$L_USECNT. Sets KFE$W_SHRCNT if appropriate.