09/20/87 hcs_ To obtain information on a particular entry point use the "ep" request Entry points in hcs_: (List is generated by the help command) :Entry: add_acl_entries: 05/12/82 hcs_$add_acl_entries Function: adds specified access modes to the access control list (ACL) of the specified segment. If an access name already appears on the ACL of the segment, its mode is changed to the one specified by the call. Syntax: declare hcs_$add_acl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(35)); call hcs_$add_acl_entries (dir_name, entryname, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) acl_ptr points to a user-filled segment_acl_array structure (see "Notes" below). (Input) acl_count contains the number of ACL entries in the segment_acl_array structure (see "Notes" below). (Input) code is a storage system status code. (Output) Notes: The segment_acl_array structure should be declared as follows. dcl segment_acl_array (acl_count) aligned like segment_acl_entry; The segment_acl_entry structure is declared in the include file acl_structures.incl.pl1. :Entry: add_dir_acl_entries: 05/12/82 hcs_$add_dir_acl_entries Function: adds specified directory access modes to the access control list (ACL) of the specified directory. If an access name already appears on the ACL of the directory, its mode is changed to the one specified by the call. Syntax: declare hcs_$add_dir_acl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(35)); call hcs_$add_dir_acl_entries (dir_name, entryname, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-filled dir_acl_array structure (see "Notes" below). (Input) acl_count contains the number of ACL entries in the dir_acl_array structure (see "Notes" below). (Input) code is a storage system status code. (Output) Notes: The dir_acl_array structure should be declared as follows. dcl dir_acl_array (acl_count) aligned like dir_acl_entry; The dir_acl_entry structure is declared in the include file acl_structures.incl.pl1. :Entry: add_dir_inacl_entries: 03/08/82 hcs_$add_dir_inacl_entries Function: adds specified directory access modes to the initial access control list (initial ACL) for new directories created for the specified ring within the specified directory. If an access name already appears on the initial ACL of the directory, its mode is changed to the one specified by the call. Syntax: declare hcs_$add_dir_inacl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$add_dir_inacl_entries (dir_name, entryname, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-filled dir_acl structure described in the hcs_$add_dir_acl_entries entry point. (Input) acl_count contains the number of initial ACL entries in the dir_acl structure. (Input) ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) :Entry: add_inacl_entries: 03/08/82 hcs_$add_inacl_entries Function: adds specified access modes to the initial access control list (initial ACL) for new segments created for the specified ring within the specified directory. If an access name already appears on the initial ACL of the segment, its mode is changed to the one specified by the call. Syntax: declare hcs_$add_inacl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$add_inacl_entries (dir_name, entryname, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-filled segment_acl structure described in the hcs_$add_acl_entries entry point. (Input) acl_count contains the number of initial ACL entries in the segment_acl structure. (Input) ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If code is returned as error_table_$argerr, then the erroneous initial ACL entries in segment_acl have status_code set to an appropriate error code. No processing is performed in this instance. :Entry: append_branch: 03/08/82 hcs_$append_branch Function: creates a segment in the specified directory, initializes the access control list (ACL) of the segment by adding *.SysDaemon.* with a mode of rw and adding the initial ACL for segments found in the containing directory, and adds the user to the ACL of the segment with the mode specified. ACLs and initial ACLs are described under "Access Control" in the Reference Manual. Syntax: declare hcs_$append_branch entry (char(*), char(*), fixed bin(5), fixed bin(35)); call hcs_$append_branch (dir_name, entryname, mode, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) mode is the user's access mode. See the hcs_$append_branchx entry point for values of the access mode argument. (Input) code is a storage system status code. (Output) Access required: Append permission on the containing directory is required to add a segment to that directory. Notes: A number of attributes of the segment are set to default values as follows: 1. Ring brackets are set to the user's current validation level. 2. The User_id of the ACL entry specifying the given mode is set to the Person_id and Project_id of the user, with the instance tag set to an asterisk (*). 3. The copy switch in the branch is set to 0. 4. The bit count is set to 0. The hcs_$append_branchx entry point creates a storage system entry with values other than the defaults listed above. :Entry: append_branchx: 05/12/82 hcs_$append_branchx Function: creates either a subdirectory or a segment in a specified directory. If a subdirectory is created, then the access control list (ACL) of the subdirectory is initialized by adding *.SysDaemon.* with a mode of sma and adding the initial ACL for directories that is stored in the containing directory; otherwise the ACL of the segment is initialized by adding *.SysDaemon.* with a mode of rw and adding the initial ACL for segments. The input User_id and mode are then merged to form an ACL entry that is added to the ACL of the subdirectory or segment. Syntax: declare hcs_$append_branchx entry (char(*), char(*), fixed bin(5), (3) fixed bin(3), char(*), fixed bin(1), fixed bin(1), fixed bin(24), fixed bin(35)); call hcs_$append_branchx (dir_name, entryname, mode, rings, user_id, dir_sw, copy_sw, bit_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment or subdirectory. (Input) mode is the user's access mode (see "Notes" below). (Input) rings is a three-element array that specifies the ring brackets of the new segment or subdirectory. (Input) If a subdirectory is to be created, the third element is ignored. See "Intraprocess Access Control" in the Reference Manual. user_id is an access control name of the form Person_id.Project_id.tag. (Input) dir_sw is the branch's directory switch. (Input) 1 if a directory is being created 0 if a segment is being created copy_sw is the value of the copy switch to be placed in the branch. (Input) See "Entry Attributes" in the Reference Manual for an explanation of the copy switch. bit_count is the segment length (in bits). (Input) code is a storage system status code. (Output) Access required: Append permission is required on the containing directory to add an entry to that directory. Notes: The mode argument is a fixed binary number where the desired mode is encoded with one access mode specified by each bit. For segments the modes are: read the 8-bit is 1 (i.e., 01000b) execute the 4-bit is 1 (i.e., 00100b) write the 2-bit is 1 (i.e., 00010b) For directories, the modes are: status the 8-bit is 1 (i.e., 01000b) modify the 2-bit is 1 (i.e., 00010b) append the 1-bit is 1 (i.e., 00001b) If modify permission is given for a directory, then status must also be given; i.e., 01010b. The unused bits are reserved for unimplemented attributes and must be zero. For example, rw access is 01010b in binary form. :Entry: append_link: 03/08/82 hcs_$append_link Function: is provided to create a link in the storage system directory hierarchy to some other directory entry in the hierarchy. For a definition of links see "Glossary of Multics Terms" in the Reference Manual. Syntax: declare hcs_$append_link entry (char(*), char(*), char(*), fixed bin(35)); call hcs_$append_link (dir_name, entryname, path, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the link. (Input) path is the pathname of the directory entry to which the entryname argument points. (Input) The pathname may be a maximum of 168 characters. code is a storage system status code. (Output) Access required: Append permission is required in the directory in which the link is being created. Notes: The entry pointed to by the link need not exist at the time the link is created. The hcs_$append_branch and hcs_$append_branchx entry points can be used to create a segment or directory entry in the storage system hierarchy. :Entry: hcs_change_bc: 04/05/83 hcs_$change_bc Function: provides an indivisible method of changing the bitcount of a segment. It is an indivisible operation in that only one process can perform it at a time; thus, if several processes try to change the bitcount, each one will get a different output. This can be used when several processes must write into a segment; if they use the change_bc entrypoint to determine where to write, they will never overwrite each others data, and they will also never have to explicitly manipulate locks. Syntax: declare hcs_$change_bc entry (char(*), char(*), fixed bin (24), fixed bin(24), fixed bin(24), fixed bin (35)); call hcs_$change_bc (dir_name, entryname, change, old_bc, new_bc, code); Arguments: dir_name is the pathname of the directory containing the segment. (Input) entryname is the entryname of the segment. (Input) change is the amount by which the bitcount will be changed. (Input) old_bc is the bitcount before the change was applied. (Output) new_bc is the bitcount after the change was applied. (Output) code is a storage system status code. (Output) Notes: The user must have write access to the segment, but need not have modify permission on the containing directory. The hcs_$change_bc_seg entrypoint performs the same function, but it takes a pointer to the segment rather than the pathname. :Entry: change_bc_seg: 04/05/83 hcs_$change_bc_seg Function: provides an indivisible method of changing the bitcount of a segment. It is an indivisible operation in that only one process can perform it at a time; thus,, if several processes try to change the bitcount, each one will get a different output. This can be used when several processes must write into a segment; if they use the change_bc_seg entrypoint to determine where to write, they will never overwrite each others data, and they will also never have to explicitly manipulate locks. Syntax: declare hcs_$change_bc_seg entry (pointer, fixed bin(24), fixed bin(24), fixed bin(24), fixed bin (35)); call hcs_$change_bc_seg (seg_ptr, change, old_bc, new_bc, code); Arguments: seg_ptr is a pointer to the segment whose bitcount is to be changed. (Input) change is the amount by which the bitcount will be changed. (Input) old_bc is the bitcount before the change was applied. (Output) new_bc is the bitcount after the change was applied. (Output) code is a storage system status code. (Output) Notes: The user must have write access to the segment, but need not have modify permission on the containing directory. The hcs_$change_bc entrypoint performs the same function, but it takes the pathname of the segment rather than a pointer to it. :Entry: chname_file: 03/08/82 hcs_$chname_file Function: changes the entryname on a specified storage system entry. If an already existing name (an old name) is specified, it is deleted from the entry; if a new name is specified, it is added. Thus, if only an old name is specified, the effect is to delete a name; if only a new name is specified, the effect is to add a name; and if both are specified, the effect is to rename the entry. Syntax: declare hcs_$chname_file entry (char(*), char(*), char(*), char(*), fixed bin(35)); call hcs_$chname_file (dir_name, entryname, oldname, newname, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment, directory, multisegment file, or link. (Input) oldname is the name to be deleted from the entry. (Input) It can be a null character string ("") in which case no name is deleted. If oldname is null, then newname must not be null. newname is the name to be added to the entry. (Input) It must not already exist in the directory on this or another entry. It can be a null character string ("") in which case no name is added. If it is null, then oldname must not be the only name on the entry. code is a storage system status code. (Output) It can have the values: error_table_$nonamerr attempting to delete the only name of a directory entry error_table_$namedup attempting to add a name that exists on another entry error_table_$segnamedup attempting to add a name that already exists on this entry Access required: The user must have modify permission on the directory containing the entry whose name is to be changed. Notes: The hcs_$chname_seg entry point performs a similar function using a pointer to a segment instead of its pathname. :Entry: chname_seg: 03/08/82 hcs_$chname_seg Function: changes an entryname on a segment, if a pointer to the segment is given. If an already existing name (an old name) is specified, it is deleted from the entry; if a new name is specified, it is added. Thus, if only an old name is specified, the effect is to delete a name; if only a new name is specified, the effect is to add a name; and if both are specified, the effect is to rename the entry. Syntax: declare hcs_$chname_seg entry (ptr, char(*), char(*), fixed bin(35)); call hcs_$chname_seg (seg_ptr, oldname, newname, code); Arguments: seg_ptr is a pointer to the segment whose name is to be changed. (Input) oldname is the name to be deleted from the entry. (Input) It can be a null character string ("") in which case no name is to be deleted. If oldname is null, then newname must not be null. newname is the name to be added to the entry. (Input) It must not already exist in the directory on this or another entry. It can be a null character string ("") in which case no name is added. If it is null, then oldname must not be the only name on the entry. code is a storage system status code. (Output) It can have the values: error_table_$nonamerr attempting to delete the only name of a directory entry error_table_$namedup attempting to add a name that exists on another entry error_table_$segnamedup attempting to add a name that already exists on this entry Access required: The user must have modify permission on the directory containing the segment whose name is to be changed. Notes: The hcs_$chname_file entry point performs the same function if the pathname of the segment is given instead of a pointer. :Entry: create_branch_: 03/06/85 hcs_$create_branch_ Function: This entry point creates either a subdirectory or a segment in the specified directory. (This entry point is an extended and more general form of the hcs_$append_branchx entry point.) If a subdirectory is created, then the access control list (ACL) of the subdirectory is initiated by copying the initial ACL for directories that is stored in the specified directory; otherwise, the ACL of the segment is initiated by copying the initial ACL for segments. The access_name and mode items from the create_branch_info structure (see "Notes" below) are then added to the ACL of the created subdirectory or segment. Syntax: declare hcs_$create_branch_ entry (char(*), char(*), ptr, fixed bin(35)); call hcs_$create_branch_ (dir_name, entryname, info_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment or subdirectory to be created. (Input) info_ptr is a pointer to the information structure described below. (Input) code is a storage system status code. (Output) Notes: The user must have append permission on the containing directory to add an entry to that directory. The info_ptr pointer points to the create_branch_info structure (found in the include file, create_branch_info.incl.pl1). :Entry: del_dir_tree: 03/08/82 hcs_$del_dir_tree Function: given the pathname of a containing directory and the entryname of a subdirectory, deletes the contents of the subdirectory from the storage system hierarchy. All segments, links, and directories inferior to that subdirectory are deleted, including the contents of any inferior directories. The subdirectory is not itself deleted. For information on the deletion of directories, see the description of the hcs_$delentry_file entry point. Syntax: declare hcs_$del_dir_tree entry (char(*), char(*), fixed bin(35)); call hcs_$del_dir_tree (dir_name, entryname, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) code is a storage system status code. (Output) Access required: The user must have status and modify permission on the subdirectory and the safety switch must be off in that directory. If the user does not have status and modify permission on inferior directories, access is automatically set and processing continues. Notes: If an entry in an inferior directory gives the user access only in a ring lower than his validation level, that entry is not deleted and no further processing is done on the subtree. For information about rings, see "Intraprocess Access Control" in the Reference Manual. :Entry: delentry_file: 03/08/82 hcs_$delentry_file Function: given a directory name and an entryname, deletes the given entry from its containing directory. This entry may be a segment, a directory, or a link. If the entry is a segment, the contents of the segment are truncated first. If the entry specifies a directory that contains entries, the code error_table_$fulldir is returned and hcs_$del_dir_tree must be called to remove the contents of the directory. Generally, programmers should use the delete_ subroutine rather than this entry point in order to ensure that their address space is properly cleaned up. Syntax: declare hcs_$delentry_file entry (char(*), char(*), fixed bin(35)); call hcs_$delentry_file (dir_name, entryname, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment, directory, or link. (Input) code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. If the entryname argument specifies a segment or directory (but not a link), the safety switch of the entry must be off. Notes: The hcs_$delentry_seg entry point performs the same function on a segment, given a pointer to the segment instead of the pathname. :Entry: delentry_seg: 03/08/82 hcs_$delentry_seg Function: given a pointer to a segment, deletes the corresponding entry from its containing directory. The contents of the segment are truncated first. Generally, programmers should use the delete_ subroutine rather than this entry point in order to ensure that their address space is properly cleaned up. Syntax: declare hcs_$delentry_seg entry (ptr, fixed bin(35)); call hcs_$delentry_seg (seg_ptr, code); Arguments: seg_ptr is the pointer to the segment to be deleted. (Input) code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. The safety switch of the segment must be off. Notes: The hcs_$delentry_file entry point performs the same function, given the pathname of the segment instead of the pointer. :Entry: delete_acl_entries: 03/08/82 hcs_$delete_acl_entries Function: deletes specified entries from an access control list (ACL) for a segment. Syntax: declare hcs_$delete_acl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(35)); call hcs_$delete_acl_entries (dir_name, entryname, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) acl_ptr points to a user-filled delete_acl structure (see "Notes" below). (Input) acl_count is the number of ACL entries in the delete_acl structure (see "Notes" below). (Input) code is a storage system status code. (Output) Notes: The delete_acl structure is declared as follows. dcl 1 delete_acl (acl_count) aligned based (acl_ptr), 2 access_name char(32), 2 status_code fixed bin(35); access_name is the access name (in the form of Person_id.Project_id.tag) that identifies the ACL entry to be deleted. status_code is a storage system status code for this ACL entry only. If an access name cannot be matched to a name already on the ACL of the segment, then the status_code for that ACL entry in the delete_acl structure is set to error_table_$user_not_found. Processing continues to the end of the delete_acl structure and code is returned as 0. :Entry: delete_dir_acl_entries: 03/08/82 hcs_$delete_dir_acl_entries Function: is used to delete specified entries from an access control list (ACL) for a directory. Syntax: declare hcs_$delete_dir_acl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(35)); call hcs_$delete_dir_acl_entries (dir_name, entryname, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-filled delete_acl structure described in the hcs_$delete_acl_entries entry point. (Input) acl_count is the number of ACL entries in the delete_acl structure. (Input) code is a storage system status code (see "Notes" below). (Output) Notes: If code is returned as error_table_$argerr, then the erroneous ACL entries in the delete_acl structure have status_code set to an appropriate error code. No processing is performed. If an access name cannot be matched to a name already on the ACL of the segment, then the status_code for that ACL entry in the delete_acl structure is set to error_table_$user_not_found. Processing continues to the end of the delete_acl structure and code is returned as 0. :Entry: delete_dir_inacl_entries: 03/08/82 hcs_$delete_dir_inacl_entries Function: is used to delete specified entries from an initial access control list (initial ACL) for new directories created for the specified ring within the specified directory. Syntax: declare hcs_$delete_dir_inacl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$delete_dir_inacl_entries (dir_name, entryname, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to the user-filled delete_acl structure as described in the hcs_$delete_acl_entries entry point. (Input) acl_count is the number of initial ACL entries in the delete_acl structure. (Input) ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If code is returned as error_table_$argerr, then the erroneous initial ACL entries in the delete_acl structure have status_code set to an appropriate error code. No processing is performed in this instance. If an access_name in the delete_acl structure cannot be matched to one existing on the initial ACL, then the status_code of that initial ACL entry in the delete_acl structure is set to error_table_$user_not_found. Processing continues to the end of the delete_acl structure and code is returned as 0. :Entry: delete_inacl_entries: 03/08/82 hcs_$delete_inacl_entries Function: deletes specified entries from an initial access control list (initial ACL) for new segments created for the specified ring within the specified directory. Syntax: declare hcs_$delete_inacl_entries entry (char(*), char(*), ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$delete_inacl_entries (dir_name, entryname, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to the user-filled delete_acl structure as described in the hcs_$delete_acl_entries entry point. (Input) acl_count contains the number of initial ACL entries in the delete_acl structure. (Input) ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If code is returned as error_table_$argerr, then the erroneous initial ACL entries in the delete_acl structure have status_code set to an appropriate error code. No processing is performed in this instance. If an access_name in the delete_acl structure cannot be matched to one existing on the initial ACL, then the status_code of that initial ACL entry in the delete_acl structure is set to error_table_$user_not_found. Processing continues to the end of the delete_acl structure and code is returned as 0. :Entry: force_write: 03/08/82 hcs_$force_write Function: causes the supervisor to force modified pages out of main memory. Syntax: declare hcs_$force_write entry (ptr, bit(36), fixed bin(35); call hcs_$force_write (segp, flags, code); Arguments: segp is a pointer to the segment whose modified pages are to be written. (Input) flags specify a set of options. (Input) Currently, only one option is defined. The force_write_flags structure defined in force_write_flags.incl.pl1 defines the options. code is a standard status code. (Output) See "Notes" below. Notes: Use of this entry point may introduce substantial real time delay into execution, since the caller must wait for the movement of the disk; other usage of the system, meanwhile, may cause further delay. This entry point protects data against an unrecoverable main memory crash. On systems with bulk store paging devices, this subroutine may flush pages to the bulk store, which is recoverable in case of main memory crashes, rather than to the disk. This entry point returns the following non-zero status codes. If the segment is an inner ring segment, error_table_$bad_ring_brackets is returned. If the user does not have write access to the segment, error_table_$moderr is returned. If the segment is not known, not active, or a hardcore segment, then error_table_$invalidsegno is returned. Because the user has no control over whether or not the segment is active, error_table_$invalidsegno should not be treated as an error. :Entry: fs_get_mode: 03/08/82 hcs_$fs_get_mode Function: returns the access mode of the user on a specified segment at the current validation level. For a discussion of access modes, see "Access Control" in the Reference Manual. Syntax: declare hcs_$fs_get_mode entry (ptr, fixed bin(5), fixed bin(35)); call hcs_$fs_get_mode (seg_ptr, mode, code); Arguments: seg_ptr is a pointer to the segment whose access mode is to be returned. (Input) mode is the access mode returned. See the description of the hcs_$append_branchx entry point for the values of the mode argument. (Output) code is a storage system status code. (Output) Notes: The mode and ring brackets for the segment in the user's address space are used in combination with the user's current validation level to determine the mode the user would have if he accessed this segment. For a discussion of ring brackets and validation level, see "Intraprocess Access Control" in the Reference Manual. :Entry: fs_get_access_modes: 01/21/83 hcs_$fs_get_access_modes Function: returns the access mode and the extended access mode of the user on a specified segment at the current validation level. For a discussion of access modes, see "Access Control" in the Reference Manual. Syntax: declare hcs_$fs_get_access_modes entry (ptr, bit (36) aligned, bit (36) aligned, fixed bin (35)); call hcs_$fs_get_access_modes (seg_ptr, modes, ex_modes, code); Arguments: seg_ptr is a pointer to the segment whose access mode is to be returned. (Input) modes is the returned access mode. See the description of the hcs_$append_branchx entry point for the values of the mode argument. (Output) ex_modes is the returned extended access mode. (Output) code is a storage system status code. (Output) Notes: The mode and ring brackets for the segment in the user's address space are used in combination with the user's current validation level to determine the mode the user would have if he accessed this segment. For a discussion of ring brackets and validation level, see "Intraprocess Access Control" in the Reference Manual. :Entry: fs_get_path_name: 03/08/82 hcs_$fs_get_path_name Function: given a pointer to a segment, returns a pathname for the segment, with the directory and entryname portions of the pathname separated. The entryname returned is the primary name on the entry. Syntax: declare hcs_$fs_get_path_name entry (ptr, char(*), fixed bin, char(*), fixed bin(35)); call hcs_$fs_get_path_name (seg_ptr, dir_name, ldn, entryname, code); Arguments: seg_ptr is a pointer to the segment. (Input) dir_name is the pathname of the containing directory. (Output) The length of dir_name should be 168 characters. ldn is the number of nonblank characters in dir_name. (Output) entryname is the primary entryname of the segment. (Output) The length of entryname should be 32 characters. code is a storage system status code. (Output) :Entry: fs_get_ref_name: 03/08/82 hcs_$fs_get_ref_name Function: returns a specified (i.e., first, second, etc.) reference name for a specified segment. See "Constructing and Interpreting Names" in the Reference Manual. Syntax: declare hcs_$fs_get_ref_name entry (ptr, fixed bin, char(*), fixed bin(35)); call hcs_$fs_get_ref_name (seg_ptr, count, ref_name, code); Arguments: seg_ptr is a pointer to the segment whose reference name is sought. (Input) count specifies which reference name is to be returned, where 1 is the name by which the segment has most recently been made known, 2 is the next most recent name, etc. (Input) ref_name is the desired reference name. (Output) code is a storage system status code. (Output) Notes: If the count argument is larger than the total number of names, the name which the segment was originally made known is returned and code is set to error_table_$refname_count_too_big. :Entry: fs_get_seg_ptr: 03/08/82 hcs_$fs_get_seg_ptr Function:, given a reference name of a segment, returns a pointer to the base of the segment. For a discussion of reference names, see "Constructing and Interpreting Names" in the Reference Manual. Syntax: declare hcs_$fs_get_seg_ptr entry (char(*), ptr, fixed bin(35)); call hcs_$fs_get_seg_ptr (ref_name, seg_ptr, code); Arguments: ref_name is the reference name of a segment for which a pointer is to be returned. (Input) seg_ptr is a pointer to the base of the segment. (Output) code is a storage system status code. (Output) Notes: If the reference name is accessible from the user's current validation level, seg_ptr is returned pointing to the segment; otherwise, it is null. For more information on rings and validation levels refer to "Intraprocess Access Control" in the Reference Manual. :Entry: fs_move_file: 03/08/82 hcs_$fs_move_file Function: moves the data associated with one segment in the storage system hierarchy to another segment given the pathnames of the segments in question. The old segment remains, but with a zero length. Syntax: declare hcs_$fs_move_file entry (char(*), char(*), fixed bin(2), char(*), char(*), fixed bin(35)); call hcs_$fs_move_file (from_dir, from_entry, at_sw, to_dir, to_entry, code); Arguments: from_dir is the pathname of the directory in which from_entry resides. (Input) from_entry is the entryname of the segment from which data is to be moved. (Input) at_sw is a 2-bit append/truncate switch. (Input) append (first bit): 0 if to_entry does not exist, the code error_table_$noentry is returned. 1 if to_entry does not exist, it is created. truncate (second bit): 0 if to_entry is not a zero-length segment, the code error_table_$clnzero is returned. 1 if to_entry is not a zero-length segment, it is truncated before moving. to_dir is the pathname of the directory in which to_entry resides. (Input) to_entry is the entryname of the segment to which data is to be moved. (Input) code is a storage system status code. (Output) See "Notes" below. Notes: The hcs_$fs_move_seg entry point performs the same function given pointers to the segments in question instead of pathnames. The code error_table_$no_move is returned if-- 1. Either to_entry or from_entry is not a segment. 2. The user does not have rw access to to_entry. 3. The user does not have read access to from_entry. 4. The max_length of to_entry is less than the length of from_entry. 5. There is not enough quota in to_dir to perform the move. :Entry: fs_move_seg: 03/08/82 hcs_$fs_move_seg Function: moves the data associated with one segment in the hierarchy to another segment, given pointers to the segments in question. The old segment remains, but with a zero length. Syntax: declare hcs_$fs_move_seg entry (ptr, ptr, fixed bin(1), fixed bin(35)); call hcs_$fs_move_seg (from_ptr, to_ptr, trun_sw, code); Arguments: from_ptr is a pointer to the segment from which data is to be moved. (Input) to_ptr is a pointer to the target segment. (Input) trun_sw indicates whether the segment specified by to_ptr is to be truncated (if it is not already zero length) before performing the move. (Input) 0 returns code error_table_$clnzero if the segment is not already zero length 1 truncates the segment before moving code is a storage system status code. (Output) It can have the value error_table_$no_move or error_table_$clnzero. Notes: The hcs_$fs_move_file entry point performs the same function given the pathnames of the segments instead of the pointers. :Entry: get_access_class_seg: 03/08/82 hcs_$get_access_class_seg Function: given a pointer, returns the access class of that pointer's corresponding segment. For information on access classes, see "Nondiscretionary Access Control" in the Reference Manual. Syntax: declare hcs_$get_access_class_seg entry (ptr, bit(72) aligned, fixed bin(35)); call hcs_$get_access_class_seg (seg_ptr, access_class, code); Arguments: seg_ptr is the pointer to the segment. (Input) access_class is the access class of the segment. (Output) code is a storage system status code. (Output) :Entry: get_access_class: 03/08/82 hcs_$get_access_class Function: returns the access class of a segment or directory in the storage hierarchy. For information on access classes, see "Nondiscretionary Access Control" in the Reference Manual. Syntax: declare hcs_$get_access_class entry (char(*), char(*), bit(72) aligned, fixed bin(35)); call hcs_$get_access_class (dir_name, entryname, access_class, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment or directory. (Input) access_class is the access class of the segment or directory. (Output) code is a storage system status code. (Output) Access required: The user must have status permission on the directory (the dir_name argument) or nonnull access to the entry (the entryname argument). Notes: If the value of entryname is null, dir_name is assumed to be a full pathname. :Entry: get_author: 03/08/82 hcs_$get_author Function: returns the author of a segment, directory, multisegment file, or link. Syntax: declare hcs_$get_author entry (char(*), char(*), fixed bin(1), char(*), fixed bin(35)); call hcs_$get_author (dir_name, entryname, chase, author, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment, directory, multisegment file, or link. (Input) chase if entryname refers to a link, this flag indicates whether to return the author of the link or the author of the segment, directory, or multisegment file to which the link points. (Input) 0 return link author 1 return segment, directory, or multisegment file author author is the author of the segment, directory, multisegment file, or link in the form of Person_id.Project_id.tag with a maximum length of 32 characters. (Output) An error is not detected if the string, author, is too short to hold the author. code is a storage system status code. (Output) Access required: The user must have status permission on the containing directory. :Entry: get_bc_author: 03/08/82 hcs_$get_bc_author Function: returns the bit count author of a segment or directory. The bit count author is the name of the user who last set the bit count of the segment or directory. Syntax: declare hcs_$get_bc_author entry (char(*), char(*), char(*), fixed bin(35)); call hcs_$get_bc_author (dir_name, entryname, bc_author, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment or directory. (Input) bc_author is the bit count author of the segment or directory in the form of Person_id.Project_id.tag with a maximum length of 32 characters. (Output) An error is not detected if the string, bc_author, is too short to hold the bit count author. code is a storage system status code. (Output) Access required: The user must have status permission on the containing directory. :Entry: get_dir_ring_brackets: 03/08/82 hcs_$get_dir_ring_brackets Function: given the pathname of a containing directory and the entryname of a subdirectory, returns the value of that subdirectory's ring brackets. Ring brackets are discussed in "Intraprocess Access Control" in the Reference Manual. Syntax: declare hcs_$get_dir_ring_brackets entry (char(*), char(*), (2) fixed bin(3), fixed bin(35)); call hcs_$get_dir_ring_brackets (dir_name, entryname, drb, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the subdirectory. (Input) drb is a two-element array that contains the directory's ring brackets. (Output) The first element contains the level required for modify and append permission; the second element contains the level required for status permission. code is a storage system status code. (Output) Access required: The user must have status permission on the containing directory. :Entry: get_exponent_control: 03/08/82 hcs_$get_exponent_control Function: returns the current settings of the flags that control the system's handling of exponent overflow and underflow conditions. For more information on exponent control see the description of hcs_$set_exponent_control. Syntax: declare hcs_$get_exponent_control entry (bit(1) aligned, bit(1) aligned, float bin(63)); call hcs_$get_exponent_control (restart_underflow, restart_overflow, overflow_value); Arguments: restart_underflow is "1"b if underflows are currently being automatically restarted, and "0"b otherwise. (Output) restart_overflow is "1"b if overflows are currently being automatically restarted, and "0"b otherwise. (Output) overflow_value is the value used for the result of the computation in the case of overflow. (Output) :Entry: get_ips_mask: 03/08/82 hcs_$get_ips_mask Function: returns the value of the current ips mask. Syntax: declare hcs_$get_ips_mask entry (bit(36) aligned); call hcs_$get_ips_mask (old_mask); Arguments: old_mask is the current value of the ips mask. (Output) Notes: A "1"b in any position in the mask means that the corresponding ips interrupt is enabled. The thirty-sixth (rightmost) bit of old_mask does not correspond to an interrupt, but is used as a control bit, giving a positive indication that a particular masking or unmasking operation has taken place. No ips interrupts can occur in the time interval between the requested mask modification and the returning of the old_mask, with the control bit set appropriately. Entry points used at the beginning of a critical section of code, to disable some or all ips interrupts, return a value of "1"b for the control bit, while those that are used at the end of a critical section of code, to re-enable those interrupts, return a value of "0"b for the control bit. Thus, a condition handler can interpret a value of "1"b in the control bit as meaning that execution was in a critical section of code, and the ips mask has been modified. See "Notes" in the description of the hcs_$set_automatic_ips_mask entry point for information about the state of the ips mask immediately after an ips interrupt occurs. The control bit in the mask returned by this entry point is always "0"b. :Entry: get_link_target: 03/06/85 hcs_$get_link_target Function: This entry point returns the pathname of the ultimate target of a link if the ultimate target exists, or what that pathname would be if the target did exist. Syntax: declare hcs_$get_link_target entry (char(*), char(*), char(*), char(*), fixed bin(35)); call hcs_$get_link_target (dir_name, entryname, link_dir_name, link_entryname, code); Arguments: dir_name is the directory name containing the link. (Input) entryname is the entryname of the link for which target information is desired. (Input) link_dir_name is the directory name of the link target with a maximum length of 168 characters. (Output) link_entryname is the entryname of the link target with a maximum length of 32 characters. (Output) code is a standard status code. (Output) Notes: This entry chases the link to its ultimate target. The ultimate target of a link must be a directory or segment, which may or may not exist. If the immediate target of a link is another link, the chasing of links continues toward the ultimate target directory or segment until it is encountered or found to be nonexistent. If the ultimate target of the link exists, the user must either have nonnull permission on the directory containing the target or nonnull access to the target itself in order to determine its pathname. If appropriate access exists, the code is zero, and link_dir_name and link_entryname are set. If not, an error code is returned, and the link_dir_name and link_entryname are returned as blank. If the ultimate target does not exist, the target pathname of the last link encountered while chasing links will be returned if the user has nonnull permission on the directory that would have contained that target pathname. In this case, the returned code is error_table_$noentry, and the link_dir_name and link_entryname are set. In all other cases, an error code is returned to indicate the lack of access, and link_dir_name and link_entryname are returned as blanks. :Entry: get_max_length: 03/08/82 hcs_$get_max_length Function:, given a directory name and entryname, returns the maximum length (in words) of the segment. Syntax: declare hcs_$get_max_length entry (char(*), char(*), fixed bin(19), fixed bin(35)); call hcs_$get_max_length (dir_name, entryname, max_length, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) max_length is the maximum length of the segment in words. (Output) code is a storage system status code. (Output) Access required: The user must have status permission on the directory containing the segment or nonnull access to the segment. :Entry: get_max_length_seg: 03/08/82 hcs_$get_max_length_seg Function:, given a pointer to a segment, returns the maximum length (in words) of the segment. Syntax: declare hcs_$get_max_length_seg entry (ptr, fixed bin(19), fixed bin(35)); call hcs_$get_max_length_seg (seg_ptr, max_length, code); Arguments: seg_ptr is a pointer to the segment whose maximum length is to be returned. (Input) max_length is the maximum length of the segment in words. (Output) code is a storage system status code. (Output) Access required: The user must have status permission on the directory containing the segment or nonnull access to the segment. :Entry: get_page_trace: 03/08/82 hcs_$get_page_trace Function: returns information about recent paging activity. Syntax: declare hcs_$get_page_trace entry (ptr); call hcs_$get_page_trace (data_ptr); Arguments: data_ptr is a pointer to a user data space where return information is stored. (Input) Notes: The format of the data structure returned by hcs_$get_page_trace is described below. The amount of data returned cannot be known in advance other than that there are less than 1024 words returned. dcl 1 trace aligned based(tp) 2 next_available bit(18) aligned, 2 size bit(18) aligned, 2 time fixed bin(71), 2 pad1 fixed bin(35), 2 index bit(17), 2 pad2 fixed bin(71), (512 refer(divide (trace.size,2,17,0))), 3 info bit(36) aligned, 3 type bit(6) unaligned 3 pageno bit(12) unaligned, 3 time_delta bit(18) unaligned; Structure elements; next_available is a relative pointer (relative to the first trace entry) to the next entry to be used in the trace list. size is the number of words in the trace array and, hence, twice the number of entries in the array. time is the real-time clock reading at the time the last trace entry was entered in the list. pad1 is unused. index is a relative pointer to the first trace entry entered in the last quantum. Thus, all events traced in the last quantum can be determined by scanning from trace.index to trace.next_available (minus 1) with the obvious check for wrap-around. pad2 is unused. info is information about the particular trace entry. type specifies what kind of a trace entry it is. The following types are currently defined: 0 page fault 2 segment fault begin 3 segment fault end 4 linkage fault begin 5 linkage fault end 6 bound fault begin 7 bound fault end 8 signaller event 9 restarted signal 10 reschedule 11 user marker 12 interrupt pageno is the page number associated with the fault. Certain trace entries do not fill in this field. time_delta is the amount of real time elapsed between the time this entry was entered and the previous entry was entered. The time value is in units of 64 microseconds. :Entry: get_process_usage: 03/08/82 hcs_$get_process_usage Function: returns information on system resource usage by the requesting process. Syntax: declare hcs_$get_process_usage entry (ptr, fixed bin (35)); call hcs_$get_process_usage (process_usage_pointer, code); Arguments: process_usage_pointer is a pointer to the structure declared in process_usage.incl.pl1 (Input) code is a standard status code. (Output) :Entry: get_procs_required: 08/10/87 hcs_$get_procs_required Function: returns the per-process CPUs required. Syntax: declare hcs_$get_procs_required entry (bit (8) aligned, bit (1) aligned, fixed bin (35)); call hcs_$get_procs_required (procs_required, default_sw, code); Arguments: procs_required is the set of processors required. (Output) default_sw is "1"b if the set of processors required is the system default, otherwise "0"b. (Output) code is a standard system error code. (Output) Access required: This operation requires rw permission on >sc1>admin_acs>set_proc_required.acs. :Entry: get_ring_brackets: 03/08/82 hcs_$get_ring_brackets Function: given the directory name and entryname of a segment, returns the value of that segment's ring brackets. Syntax: declare hcs_$get_ring_brackets entry (char(*), char(*), (3) fixed bin(3), fixed bin(35)); call hcs_$get_ring_brackets (dir_name, entryname, rb, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) rb is a three-element array that contains the segment's ring brackets. (Output) Ring brackets and validation levels are discussed in "Intraprocess Access Control" in the Reference Manual. code is a storage system status code. (Output) Access required: The user must have status permission on the containing directory. :Entry: get_safety_sw: 03/08/82 hcs_$get_safety_sw Function:, given a directory name and an entryname, returns the value of the safety switch of a directory or a segment. Syntax: declare hcs_$get_safety_sw entry (char(*), char(*), bit(1), fixed bin(35)); call hcs_$get_safety_sw entry (dir_name, entryname, safety_sw, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory or segment. (Input) safety_sw is the value of the safety switch. (Output) "0"b the segment or directory can be deleted "1"b the segment or directory cannot be deleted code is a storage system status code. (Output) Access required: The user must have status permission on the containing directory or nonnull access to the directory or segment. :Entry: get_safety_sw_seg: 03/08/82 hcs_$get_safety_sw_seg Function: given a pointer to the segment, returns the value of the safety switch of a segment. Syntax: declare hcs_$get_safety_sw_seg entry (ptr, bit(1), fixed bin(35)); call hcs_$get_safety_sw_seg (seg_ptr, safety_sw, code); Arguments: seg_ptr is a pointer to the segment whose safety switch is to be examined. (Input) safety_sw is the value of the segment safety switch. (Output) "0"b the segment can be deleted "1"b the segment cannot be deleted code is a storage system status code. (Output) Access required: The user must have status permission on the directory containing the segment or must have nonnull access to the segment. :Entry: get_search_rules: 03/08/82 hcs_$get_search_rules Function: returns the search rules currently in use in the caller's process. Syntax: declare hcs_$get_search_rules entry (ptr); call hcs_$get_search_rules (search_rules_ptr); Arguments: search_rules_ptr is a pointer to a user-supplied search rules structure. (Input) See "Notes" below. Notes: The structure pointed to by search_rules_ptr is declared as follows: dcl 1 search_rules aligned, 2 number fixed bin, 2 names (21) char(168) aligned; number is the number of search rules in the array. names are the names of the search rules. They can be absolute pathnames of directories or keywords. (See the hcs_$initiate_search_rules entry point for a detailed description of the search rules.) :Entry: get_system_search_rules: 03/08/82 hcs_$get_system_search_rules Function: provides the user with the values of the site-defined search rule keywords accepted by hcs_$initiate_search_rules. Syntax: declare hcs_$get_system_search_rules entry (ptr, fixed bin(35)); call hcs_$get_system_search_rules (search_rules_ptr, code); Arguments: search_rules_ptr is a pointer to the structure described in "Notes" below. (Input) code is a storage system status code. (Output) Notes: The structure pointed to by search_rules_ptr is declared as follows: dcl 1 drules based aligned, 2 ntags fixed bin, 2 nrules fixed bin, 2 tags (10), 3 name char(32), 3 flag bit(36), 2 rules (50), 3 name char(168), 3 flag bit(36); Structure elements; ntags is the number of tags. nrules is the number of rules. tags is an array of keywords. tags.name is the keyword. tags.flag is a bit field with one bit on. rules is an array of directory names. rules.name is the absolute pathname of the directory. rules.flag is a bit field with bits on for every tag that selects this directory. :Entry: get_uid_file: 03/31/83 hcs_$get_uid_file Function: returns the unique identifier of a storage system entry. If the input arguments refer to a link, the uid of the target will be returned. Syntax: declare hcs_$get_uid_file entry (char(*), char(*), bit(36) aligned, fixed bin(35)); call hcs_$get_uid_file (dir_name, entry_name, uid, code); Arguments: dir_name is the name of the directory containing the entry. (Input) entry_name is the name of the entry whose unique identifier is to be returned. (Input) uid is the unique identifier of the entry. (Output) code is a standard storage system status code. (Output) :Entry: get_uid_seg: 05/17/82 hcs_$get_uid_seg Function: Given a pointer to a segment, returns the unique identifier associated with the segment. Syntax: declare hcs_$get_uid_seg entry (ptr, bit(36) aligned, fixed bin(35)); call hcs_$get_uid_seg (seg_ptr, unique_id, code); Arguments: seg_ptr is a pointer to the segment whose unique identifier is to be determined. (Input) unique_id is the unique identifier associated with the segment. (Output) code is a standard storage system status code. (Output) :Entry: get_user_access_modes: 01/21/83 hcs_$get_user_access_modes Function: returns the effective access mode and extended access mode of a user to a branch, given the pathname of the branch, the name of the user, and the validation level (ring number) of the user. (For a description of this mode, see "Effective Access" in the Reference Manual.) Syntax: declare hcs_$get_user_access_modes entry (char(*), char(*), char(*), fixed bin, bit (36) aligned, bit (36) aligned, fixed bin(35)); call hcs_$get_user_access_modes (dir_name, entryname, user_id, ring, mode, ex_mode, code); Arguments: dir_name is the directory name of the branch. (Input) entryname is the entry name of the branch. (Input) user_id is the access name of the user in the form Person_id.Project_id_.tag. (Input) This is limited to 32 characters. If null, the access name of the calling process is used. ring is the validation level that is to be used in computing effective access. (Input) It must be a value between 0 and 7 inclusive, or -1. If the ring value is -1, a default value of the validation level of the calling process is used. This default should be used in all cases except those in which a different ring's access is explicitly required. mode is the effective access mode of the user to the branch (see "Notes" below). (Output) ex_mode is the extended access mode of the user to the branch. (Output) code is a standard status code. (Output) Access required: The user must have status permission on the containing directory, unless the access name supplied is that of the calling process or null. Notes: The include file access_mode_values.incl.pl1 defines mnemonics for the different values of mode. Extended access modes are defined by the subsystem owning the branch. :Entry: get_user_access_modes_ptr: 03/05/85 hcs_$get_user_access_modes_ptr Function: This entry point returns the effective access mode and extended access mode of a user to a segment, given a pointer to the segment, the name of the user, and the validation level (ring number) of the user. Syntax: declare hcs_$get_user_access_modes_ptr entry (pointer, fixed bin, bit (36) aligned, bit (36) aligned, fixed bin (35)); call hcs_$get_user_access_modes_ptr (segment_ptr, user_id, ring, mode, ex_mode, code); Arguments: segment_ptr is a pointer to the segment for which access will be returned (Input) user_id is the access name fo the user in the form Person_id.Project_id.tag. (Input) This is limited to 32 characters. If null, the access name of the calling process is used. ring is the validation level that is to be used in computing effective access. (Input) It must be a value between 0 and 7 inclusive, or -1. If the ring value is -1, a default value of the validation level of the calling process is used. This default should be used in all cases except those in which a different ring's access is explicitly required. mode is the effective access mode of the user to the branch (see "Notes" below). (Output) ex_mode is the extended access mode of the user to the branch. (Output) code is a standard status code. (Output) Access required: The user must have status permission on the containing directoy, unless the access name supplied is that of the calling process or null. Notes: The include file access_mode_values.incl.pl1 defines mnemonics for the different values of mode. Extended access modes are defined by the subsystem owning the branch. :Entry: get_user_effmode: 03/08/82 hcs_$get_user_effmode Function: returns the effective access mode of a user to a branch, given the pathname of the branch, the name of the user, and the validation level (ring number) of the user. (For a description of this mode, see "Effective Access" in the Reference Manual.) Syntax: declare hcs_$get_user_effmode entry (char(*), char(*), char(*), fixed bin, fixed bin(5), fixed bin(35)); call hcs_$get_user_effmode (dir_name, entryname, user_id, ring, mode, code); Arguments: dir_name is the directory name of the branch. (Input) entryname is the entry name of the branch. (Input) user_id is the access name of the user in the form Person_id.Project_id_.tag. (Input) This is limited to 32 characters. If null, the access name of the calling process is used. ring is the validation level that is to be used in computing effective access. (Input) It must be a value between 0 and 7 inclusive, or -1. If the ring value is -1, a default value of the validation level of the calling process is used. This default should be used in all cases except those in which a different ring's access is explicitly required. mode is the effective access mode of the user to the branch (see "Notes" below). (Output) code is a standard status code. (Output) Access required: The user must have status permission on the containing directory, unless the access name supplied is that of the calling process or null. Notes: The mode argument is a fixed binary number where the desired mode is encoded with one access mode specified by each bit. The modes for segments are: read the 8-bit is 1 (i.e., 01000b) execute the 4-bit is 1 (i.e., 00100b) write the 2-bit is 1 (i.e., 00010b) The modes for directories are: status the 8-bit is 1 (i.e., 01000b) modify the 2-bit is 1 (i.e., 00010b) append the 1-bit is 1 (i.e., 00001b) The unused bits are reserved for unimplemented attributes and must be 0. For example, rw access is 01010b in binary form, and 10 in decimal form. The access_mode_values.incl.pl1 include file defines mnemonics for these values. :Entry: history_regs_get: 03/08/82 hcs_$history_regs_get Function: returns the current state of the per-process history register switch, pds$save_history_regs. Syntax: declare hcs_$history_regs_get entry (bit (1) aligned); call hcs_$history_regs_get (current_state); Arguments: current_state is the current state of the per-process switch. (Output) A "1"b equals on, and a "0"b equals off. :Entry: history_regs_set: 03/08/82 hcs_$history_regs_set Function: controls the state of the per-process switch, pds$save_history_regs. If this per-process switch is set on ("1"b), then history registers of the processor that a process was executing on at the time of a signalable fault (e.g., illegal_procedure) are stored by the fault module (fim) and copied into the signallers stack frame (return_to_ring_0_). If the per-process switch is set off, and the per-system switch (wired_hardcore_data$global_hregs) is off, then the history register block in the signaller stack frame is set to all zeros. Syntax: declare hcs_$history_regs_set entry (bit (1) aligned); call hcs_$history_regs_set (desired_state); Arguments: desired_state is the desired state of the per-process switch. (Input) A "1"b equals on, and a "0"b equals off. :Entry: initiate: 03/08/82 hcs_$initiate Function: given a pathname and a reference name, makes known the segment defined by the pathname, initiates the given reference name, and increments the count of initiated reference names for the segment. Syntax: declare hcs_$initiate entry (char(*), char(*), char(*), fixed bin(1), fixed bin(2), ptr, fixed bin(35)); call hcs_$initiate (dir_name, entryname, ref_name, seg_sw, copy_ctl_sw, seg_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) ref_name is the reference name. (Input) If it is zero length, the segment is initiated with a null reference name. seg_sw is the reserved segment switch. (Input) 0 if no segment number has been reserved 1 if a segment number was reserved copy_ctl_sw is obsolete, and should be set to zero. (Input) seg_ptr is a pointer to the segment. 1 if seg_sw is on (Input) 0 if seg_sw is off (Output) code is a storage system status code. (Output) Access required: The user must have nonnull access on the segment (the entryname argument) in order to make it known. Notes: If a segment is concurrently initiated more than a system-defined number of times, the usage count of the segment is said to be in an overflowed condition, and further initiations do not affect the usage count. This affects the use of the hcs_$terminate_noname and hcs_$terminate_name entry points. If the reserved segment switch is on, then the segment pointer is input and the segment is made known with that segment number. In this case, the user supplies the initial segment number. If the reserved segment switch is off, a segment number is assigned and returned as a pointer. If entryname cannot be made known, a null pointer is returned for seg_ptr and the returned value of code indicates the reason for failure. Thus, the usual way to test whether the call was successful is to check the pointer, not the code, since the code may be nonzero even if the segment was successfully initiated. If entryname is already known to the user's process, code is returned as error_table_$segknown and the seg_ptr argument contains a nonnull pointer to entryname. If ref_name has already been initiated in the current ring, the code is returned as error_table_$namedup. The seg_ptr argument contains a valid pointer to the segment being initiated. If entryname is not already known, and no problems are encountered, seg_ptr contains a valid pointer and code is 0. :Entry: initiate_count: 03/08/82 hcs_$initiate_count Function: given a pathname and a reference name, causes the segment defined by the pathname to be made known and the given reference name initiated. A segment number is assigned and returned as a pointer and the bit count of the segment is returned. Syntax: declare hcs_$initiate_count entry (char(*), char(*), char(*), fixed bin(24), fixed bin(2), ptr, fixed bin(35)); call hcs_$initiate_count (dir_name, entryname, ref_name, bit_count, copy_ctl_sw, seg_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) ref_name is the reference name. (Input) If it is zero length, the segment is initiated with a null reference name. bit_count is the bit count of the segment. (Output) copy_ctl_sw is obsolete, and should be set to zero. (Input) seg_ptr is a pointer to the segment. (Output) code is a storage system status code. (Output) Notes: The user must have nonnull access on the segment (the entryname argument) in order to make it known. If entryname cannot be made known, a null pointer is returned for seg_ptr and the returned value of code indicates the reason for failure. Thus, the usual way to test whether the call was successful is to check the pointer, not the code, since the code may be nonzero even if the segment was successfully initiated. If entryname is already known to the user's process, code is returned as error_table_$segknown and the seg_ptr argument contains a nonnull pointer to entryname. If entryname is not already known, and no problems are encountered, seg_ptr contains a valid pointer and code is 0. If ref_name has already been initiated in the current ring, the code is returned as error_table_$namedup. The seg_ptr argument contains a valid pointer to the segment being initiated. If the seg_ptr argument contains a nonnull pointer, the bit_count argument is set to the bit count of the segment to which seg_ptr points. :Entry: initiate_search_rules: 03/08/82 hcs_$initiate_search_rules Function: provides the user with a subroutine interface for specifying the search rules that he wants to use in his process. The search rules remain in effect until this entry point is called with a different set of rules or the process is terminated. (For a description of the set_search_rules command, type "help ssr".) Syntax: declare hcs_$initiate_search_rules entry (ptr, fixed bin(35)); call hcs_$initiate_search_rules (search_rules_ptr, code); Arguments: search_rules_ptr is a pointer to a structure containing the new search rules. (Input) See "Notes" below. code is a storage system status code. (Output) It can be one of the following: error_table_$badstring (not a pathname or keyword) error_table_$notadir error_table_$too_many_sr Additional codes can be returned from other procedures that are called by hcs_$initiate_search_rules. Notes: The structure pointed to by search_rules_ptr is declared as follows: dcl 1 search_rules aligned, 2 number fixed bin, 2 names (21) char(168) aligned; number is the number of search rules contained in the array. The current maximum number of search rules the user can define is 21. names are the names of the search rules. They can be absolute pathnames of directories or keywords. See "List of keywords" below. List of keywords: initiated_segments search for the already initiated segments. referencing_dir search the containing directory of the segment making the reference. working_dir search the working directory. process_dir search the process directory. home_dir search the home directory. set_search_directories insert the directories following this keyword into the default search rules after working_dir, and make the result the current search rules. When used, it must be the first search rule specified and the only keyword used. site-defined keywords may also be specified. These keywords may expand into one or more directory pathnames. The keyword, default, is always defined to be the site's default search rules. For the values of the site-defined keywords, the user may call the hcs_$get_system_search_rules entry point. :Entry: list_acl: 03/08/82 hcs_$list_acl Function: is used either to list the entire access control list (ACL) of a segment or to return the access modes of specified ACL entries. Syntax: declare hcs_$list_acl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, fixed bin(35)); call hcs_$list_acl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) area_ptr points to an area in which the list of ACL entries, which make up the entire ACL of the segment, is allocated. (Input) If area_ptr is null, then the user wants access modes for certain ACL entries; these will be specified by the structure pointed to by acl_ptr. area_ret_ptr points to the start of the allocated list of ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an ACL structure, segment_acl, into which mode information is placed for the access names specified in that same structure. (Input) The segment_acl structure is described in the hcs_$add_acl_entries entry point. acl_count is the number of entries in the ACL structure. (Input or Output) Input is the number of entries in the ACL structure identified by acl_ptr. Output is the number of entries in the segment_acl structure allocated in the area pointed to by area_ptr, if area_ptr is not null. code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than for all access names on a segment), then each ACL entry in the segment_acl structure either has status_code set to 0 and contains the segment's mode or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: list_dir_acl: 03/08/82 hcs_$list_dir_acl Function: is used either to list the entire access control list (ACL) of a directory or to return the access modes for specified entries. Syntax: declare hcs_$list_dir_acl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, fixed bin(35)); call hcs_$list_dir_acl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, acl_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) area_ptr points to an area in which the list of ACL entries, which make up the entire ACL of the directory, is allocated. (Input) If area_ptr is null, then the user wants access modes for certain ACL entries; these will be specified by the structure pointed to by acl_ptr. area_ret_ptr points to the start of the allocated list of ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an ACL structure, dir_acl, into which mode information is placed for the access names specified in that same structure. (Input) The dir_acl structure is described in the hcs_$add_dir_acl_entries entry point. acl_count is the number of entries in the ACL structure. (Input or Output) Input is the number of entries in the ACL structure identified by acl_ptr. Output is the number of entries in the dir_acl structure allocated in the area pointed to by area_ptr, if area_ptr is not null. code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than for all access names on a directory), then each ACL entry in the dir_acl structure either has status_code set to 0 and contains the mode of the directory or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: list_dir_inacl: 09/26/86 hcs_$list_dir_inacl Function: is used either to list the entire initial access control list (initial ACL) for new directories created for the specified ring within the specified directory or to return the access modes for specified initial ACL entries. Syntax: declare hcs_$list_dir_inacl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$list_dir_inacl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) area_ptr points to an area into which the list of initial ACL entries, which makes up the entire initial ACL of the directory, is allocated. (Input) If area_ptr is null, then the user wants access modes for certain initial ACL entries; these will be specified by the structure pointed to by acl_ptr. area_ret_ptr points to the start of the allocated list of initial ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an initial ACL structure, dir_acl, into which mode information is placed for the access names specified in that same structure. (Input) The dir_acl structure is described in the hcs_$add_dir_inacl_entries entry point. acl_count (Input) is the number of entries in the initial ACL structure. (Output) is the number of entries in the dir_acl structure allocated in the area pointed to by area_ptr, if area_ptr is not null. ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than obtaining modes for all access names on the initial ACL), then each initial ACL entry in the dir_acl structure either has status_code set to 0 and contains the directory's mode or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: list_inacl: 09/26/86 hcs_$list_inacl Function: is used either to list the entire initial access control list (initial ACL) for new segments created for the specified ring within the specified directory or to return the access modes for specified initial ACL entries. Syntax: declare hcs_$list_inacl entry (char(*), char(*), ptr, ptr, ptr, fixed bin, fixed bin(3), fixed bin(35)); call hcs_$list_inacl (dir_name, entryname, area_ptr, area_ret_ptr, acl_ptr, acl_count, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) area_ptr points to an area into which the list of initial ACL entries, which makes up the entire initial ACL of the directory, is allocated. (Input) If area_ptr is null, then the user wants access modes for certain initial ACL entries; these will be specified by the structure pointed to by acl_ptr. area_ret_ptr points to the start of the allocated list of initial ACL entries. (Output) acl_ptr if area_ptr is null, then acl_ptr points to an initial ACL structure, segment_acl, into which mode information is to be placed for the access names specified in that same structure. (Input) The segment_acl structure is described in the hcs_$add_inacl_entries entry point. acl_count (Input) is the number of entries in the initial ACL structure. (Output) is the number of entries in the segment_acl structure allocated in the area pointed to by area_ptr, if area_ptr is not null. ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If acl_ptr is used to obtain modes for specified access names (rather than obtaining modes for all access names on the initial ACL), then each initial ACL entry in the segment_acl structure either has status_code set to 0 and contains the segment's mode or has status_code set to error_table_$user_not_found and contains a mode of 0. :Entry: make_entry: 03/08/82 hcs_$make_entry Function: when given a reference name and an entry point name, returns the value of a specified entry point. If the reference name has not yet been initiated, the search rules are used to find a segment with a name the same as the reference name. The segment is made known and the reference name initiated. Use hcs_$make_ptr to have a pointer returned. Syntax: declare hcs_$make_entry entry (ptr, char(*), char(*), entry, fixed bin(35)); call hcs_$make_entry (ref_ptr, entryname, entry_point_name, entry_point, code); Arguments: ref_ptr is a pointer to the segment that is considered the referencing procedure (see "Notes" below). (Input) entryname is the entryname or reference name of the segment. (Input) entry_point_name is the name of the entry point to be located. (Input) entry_point is the value of the segment entry point specified by entryname and entry_point_name. (Output) code is a storage system status code. (Output) Notes: The directory in which the segment pointed to by ref_ptr is located is used as the referencing directory for the standard search rules. If ref_ptr is null, then the standard search rule specifying the referencing directory is skipped. See "Search Rules" in the Reference Manual. Normally ref_ptr is null. The entryname and entry_point_name arguments are nonvarying character strings with a length of up to 32 characters. They need not be aligned and can be blank padded. If a null string is given for the entry_point_name argument, then an entry value referring to the base of the segment is returned. In any case, the segment identified by entryname is made known to the process with the entryname argument initiated as a reference name. If an error is encountered upon return, the entry_point_ptr argument is null and an error code is given. :Entry: make_ptr: 03/08/82 hcs_$make_ptr Function: when given a reference name and an entry point name, returns a pointer to a specified entry point. If the reference name has not yet been initiated, the search rules are used to find a segment with a name the same as the reference name. The segment is made known and the reference name initiated. Use hcs_$make_entry to have entry values returned. Syntax: declare hcs_$make_ptr entry (ptr, char(*), char(*), ptr, fixed bin(35)); call hcs_$make_ptr (ref_ptr, entryname, entry_point_name, entry_point_ptr, code); Arguments: ref_ptr is a pointer to the segment that is considered the referencing procedure. (Input) See "Notes" below. entryname is the entryname of the segment. (Input) entry_point_name is the name of the entry point to be located. (Input) entry_point_ptr is the pointer to the segment entry point specified by entryname and entry_point_name. (Output) code is a storage system status code. (Output) Notes: The directory in which the segment pointed to by ref_ptr is located is used as the referencing directory for the standard search rules. If ref_ptr is null, then the standard search rule specifying the referencing directory is skipped. For a discussion of standard search rules, refer to "Search Rules," in the Reference Manual. Normally ref_ptr is null. The entryname and entry_point_name arguments are nonvarying character strings with a length of up to 32 characters. They need not be aligned and can be blank padded. If a null string is given for the entry_point_name argument, then a pointer to the base of the segment is returned. In any case, the segment identified by entryname is made known to the process with the entryname argument initiated as a reference name. If an error is encountered upon return, the entry_point_ptr argument is null and an error code is given. :Entry: make_seg: 03/08/82 hcs_$make_seg Function: creates a segment with a specified entryname in a specified directory. Once the segment is created, it is made known to the process and a pointer to the segment is returned to the caller. If the segment already exists or is already known, a nonzero code is returned; however, a pointer to the segment is still returned. Syntax: declare hcs_$make_seg entry (char(*), char(*), char(*), fixed bin(5), ptr, fixed bin(35)); call hcs_$make_seg (dir_name, entryname, ref_name, mode, seg_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) ref_name is the desired reference name or a null character string (""). (Input) mode specifies the mode for this user. (Input) See "Notes" in the description of hcs_$append_branchx for more information on modes. seg_ptr is a pointer to the created segment. (Output) code is a storage system status code. (Output) It may be one of the following: error_table_$namedup if the specified segment already exists or the specified reference name has already been initiated error_table_$segknown if the specified segment is already known Notes: If dir_name is null, the process directory is used. If the entryname is null, a unique name is generated. The segment is made known and ref_name is initiated. See also "Constructing and Interpreting Names" in the Reference Manual. If the segment cannot be created or made known, a null pointer is returned for seg_ptr and the returned value of code indicates the reason for failure. Thus, the usual way to test whether the call was successful is to check the pointer, not the code, since the code may be nonzero even if the segment was successfully initiated. :Entry: mask_ips: 03/08/82 hcs_$mask_ips Function: masks on, or enables, the specified ips interrupts. This entry point can be used at the end of a critical section of code, to re-enable specified ips interrupts and turn off the control bit (see "Notes"). Syntax: declare hcs_$mask_ips entry (bit(36) aligned, bit(36) aligned); call hcs_$mask_ips (mask, old_mask); Arguments: mask is a word containing a "1"b for each ips interrupt that is to be enabled. (Input) See "Notes". old_mask is the former value of the ips mask, with a control bit of "0"b. (Output) Notes: The create_ips_mask_ subroutine can be used to create a mask, given a set of ips names. The thirty-sixth (rightmost) bit of old_mask does not correspond to an interrupt, but is used as a control bit, giving a positive indication that a particular masking or unmasking operation has taken place. No ips interrupts can occur in the time interval between the requested mask modification and the returning of the old_mask, with the control bit set appropriately. Entry points used at the beginning of a critical section of code, to disable some or all ips interrupts, return a value of "1"b for the control bit, while those that are used at the end of a critical section of code, to re-enable those interrupts, return a value of "0"b for the control bit. Thus, a condition handler can interpret a value of "1"b in the control bit as meaning that execution was in a critical section of code, and the ips mask has been modified. See "Notes" in the description of the hcs_$set_automatic_ips_mask entry point for information about the state of the ips mask immediately after an ips interrupt occurs. :Entry: quota_move: 03/08/82 hcs_$quota_move Function: moves all or part of a quota between two directories, one of which is immediately inferior to the other. Syntax: declare hcs_$quota_move entry (char(*), char(*), fixed bin(18), fixed bin(35)); call hcs_$quota_move (dir_name, entryname, quota_change, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) quota_change is the number of records of secondary storage quota to be moved between the superior directory and the inferior directory. (Input) (See "Notes" below.) code is a storage system status code. (Output) Access required: The user must have modify permission on both directories. Notes: After the quota change, the remaining quota in each directory must be greater than the number of records used in that directory. The quota_change argument can be either a positive or negative number. If it is positive, the quota is moved from dir_name to entryname. If it is negative, the move is from entryname to dir_name. If the change results in zero quota left on entryname, that directory is assumed to no longer contain a terminal quota and all of its used records are reflected up to the used records on dir_name. It is a restriction that no quota in any of the directories superior to entryname can be modified from a nonzero value to a zero value by this subroutine. :Entry: quota_read: 03/08/82 hcs_$quota_read Function: returns the segment record quota and accounting information for a directory. Syntax: declare hcs_$quota_read entry (char(*), fixed bin(18), fixed bin(71), bit(36) aligned, bit(36), fixed bin(1), fixed bin(18), fixed bin(35)); call hcs_$quota_read (dir_name, quota, trp, tup, sons_lvid, tacc_sw, used, code); Arguments: dir_name is the pathname of the directory for which quota information is desired. (Input) quota is the segment record quota in the directory. (Output) trp is the time-record product (trp) charged to the directory. (Output) This double-precision number is in units of record-seconds. tup is the time, expressed in storage system time format (the high-order 36 bits of the 52-bit time returned by the clock_ subroutine) that the trp was last updated. (Output) sons_lvid is the logical volume ID for segments contained in this directory. (Output) tacc_sw is the terminal account switch. (Output) The setting of this switch determines how charges are made. 1 records are charged against the quota in this directory 0 records are charged against the quota in the first superior directory with a terminal account used is the number of records used by segments in this directory and by segments in nonterminal inferior directories. (Output) code is a storage system status code. (Output) Notes: If the directory contains a nonterminal account, the quota, trp, and tup are all zero. The variable specified by used, however, is kept up-to-date and represents the number of records in this directory and inferior, nonterminal directories. :Entry: release_segment_numbers: 03/03/83 hcs_$release_segment_numbers Function: releases reserved segment numbers which are not associated with segments. Syntax: declare hcs_$release_segment_numbers entry (fixed bin, fixed bin,, fixed bin(35)); call hcs_$release_segment_numbers (first_segno, block_size, code); Arguments: first_segno is the first segment number of the reserved block. (Input) block_size is the number os segment numbers to be released. (Input) code is error_table_$invalidsegno if any portion of the segment number range is an invalid segment number. It is error_table_$segknown if any of the segment numbers is known. (Output) Notes: This entry should be used in the cleanup handler of programs which reserve segment number blocks using hcs_$reserve_segment_numbers. If code is non-zero, no segment numbers were released. For example, suppose that a program reserves a block of ten segment numbers and a cleanup condition occurs after only four of these segment numbers have been used in calls to hcs_$initiate. The cleanup handler should call hcs_$release_segment_numbers for the last six segments of the block and then individually terminate the first four segments. :Entry: replace_acl: 03/08/82 hcs_$replace_acl Function: replaces an entire access control list (ACL) for a segment with a user-provided ACL, and can optionally add an entry for *.SysDaemon.* with mode rw to the new ACL. Syntax: declare hcs_$replace_acl entry (char(*), char(*), ptr, fixed bin, bit(1), fixed bin(35)); call hcs_$replace_acl (dir_name, entryname, acl_ptr, acl_count, no_sysdaemon_sw, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) acl_ptr points to the user supplied segment_acl structure that is to replace the current ACL. (Input) The segment_acl structure is described in the hcs_$add_acl_entries entry point. acl_count is the number of entries in the segment_acl structure. (Input) no_sysdaemon_sw is a switch that indicates whether an rw *.SysDaemon.* entry is to be put on the ACL of the segment after the existing ACL has been deleted and before the user-supplied segment_acl entries are added. (Input) "0"b adds rw *.SysDaemon.* entry "1"b replaces the existing ACL with only the user-supplied segment_acl code is a storage system status code. (Output) Notes: If acl_count is zero, then the existing ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the segment_acl entries is performed top to bottom, allowing later entries to overwrite previous ones if the access_name in the segment_acl structure is identical. If the segment is a gate (see "Intraprocess Access Control" in the Programmer's Reference Manual) and if the validation level is greater than ring 1, access is restricted to the same project as that of the user or to the SysDaemon project. If the replacement ACL is in error, then no processing is performed and the code error_table_$invalid_project_for_gate is returned. :Entry: replace_dir_acl: 09/26/86 hcs_$replace_dir_acl Function: replaces an entire access control list (ACL) for a directory with a user-provided ACL, and can optionally add an entry for *.SysDaemon.* with mode sma to the new ACL. Syntax: declare hcs_$replace_dir_acl entry (char(*), char(*), ptr, fixed bin, bit(1), fixed bin(35)); call hcs_$replace_dir_acl (dir_name, entryname, acl_ptr, acl_count, no_sysdaemon_sw, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-supplied dir_acl structure that is to replace the current ACL. (Input) The dir_acl structure is described in the hcs_$add_dir_acl_entries entry point. acl_count contains the number of entries in the dir_acl structure. (Input) no_sysdaemon_sw is a switch that indicates whether the sma *.SysDaemon.* entry is put on the ACL of the directory after the existing ACL of the directory has been deleted and before the user-supplied dir_acl entries are added. (Input) "0"b adds sma *.SysDaemon.* entry "1"b replaces the existing ACL with only the user-supplied dir_acl code is a storage system status code. (Output) Notes: If acl_count is zero, then the existing ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the dir_acl entries is performed top to bottom, allowing later entries to overwrite previous ones if the access_name in the dir_acl structure is identical. If the replacement ACL is in error, no processing is performed for that ACL entry in the dir_acl structure and the subroutine returns the code error_table_$nam_err or error_table_$invalid_ascii, whichever is appropriate. :Entry: reserve_segment_numbers: 03/03/83 hcs_$reserve_segment_numbers Function: This entry point allows a user to reserve a block of contiguous segment numbers. Syntax: declare hcs_$reserve_segment_numbers entry (fixed bin, fixed bin, fixed bin(35)); call hcs_$reserve_segment_numbers (block_size, first_segno, code); Arguments: block_size is the number of segments in the segment number group. (Input) first_segno is the number of the first segment in the group assigned. (Output) code is 0 if the allocation succeeded. It is error_table_$nrmkst if there is no group of block_size contiguous segment numbers available. (Output) Notes: This entry removes the contiguous segment number group from the available free segment numbers. The assigned segment numbers are available only by using hcs_$initiate and specifying a reserved segment number. See also the description of hcs_$release_segment_numbers. :Entry: reset_ips_mask: 03/08/82 hcs_$reset_ips_mask Function: replaces the entire ips mask with a specified mask, and returns the previous value of the mask with a control bit of "0"b. It can be used at the end of a critical section of code to restore the mask to its former value. See "Notes" in the description of the hcs_$get_ips_mask entry point for a discussion of the control bit. Syntax: declare hcs_$reset_ips_mask entry (bit(36) aligned, bit(36) aligned); call hcs_$reset_ips_mask (mask, old_mask); Arguments: mask is the new ips mask, to replace the current one. (Input) A "1" bit in a mask position enables the corresponding ips interrupt. old_mask is the former value of the ips mask, with a control bit of "0"b. (Output) Notes: This entry point can be used at the end of a critical section of code to undo the mask changes made by the hcs_$set_ips_mask entry point. The old_mask returned by the latter entry point should be used as the value of the new mask set by this entry point. :Entry: replace_dir_inacl: 09/26/86 hcs_$replace_dir_inacl Function: This entry point replaces an entire initial access control list (initial ACL) for new directories created for the specified ring within a specified directory with a user-provided initial ACL, and can optionally add an entry for *.SysDaemon.* with mode sma to the new initial ACL. Syntax: declare hcs_$replace_dir_inacl entry (char(*), char(*), ptr, fixed bin, bit(1), fixed bin(3), fixed bin(35)); call hcs_$replace_dir_inacl (dir_name, entryname, acl_ptr, acl_count, no_sysdaemon_sw, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to a user-supplied dir_acl_array structure that is to replace the current initial ACL. The dir_acl_array structure is discussed in the description of hcs_$add_dir_inacl_entries. (Input) acl_count contains the number of entries in the dir_acl_array structure. (Input) no_sysdaemon_sw is a switch that indicates whether the sma *.SysDaemon.* entry is put on the initial ACL after the existing initial ACL is deleted and before the user-supplied dir_acl_array entries are added. (Input) "0"b adds sma *.SysDaemon.* entry "1"b replaces the existing initial ACL with only the user-supplied dir_acl_array ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If acl_count is zero, then the existing initial ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the dir_acl_array entries is performed top to bottom, allowing later entries to overwrite previous ones if the access_name in the dir_acl_array structure is identical. :Entry: replace_inacl: 09/26/86 hcs_$replace_inacl Function: replaces an entire initial access control list (initial ACL) for new segments created for the specified ring within a specified directory with a user-provided initial ACL, and can optionally add an entry for *.SysDaemon.* with mode rw to the new initial ACL. Syntax: declare hcs_$replace_inacl entry (char(*), char(*), ptr, fixed bin, bit(1), fixed bin(3), fixed bin(35)); call hcs_$replace_inacl (dir_name, entryname, acl_ptr, acl_count, no_sysdaemon_sw, ring, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the directory. (Input) acl_ptr points to the user-supplied segment_acl structure that is to replace the current initial ACL. The segment_acl structure is described in the hcs_$add_inacl_entries entry point. (Input) acl_count contains the number of entries in the segment_acl structure. (Input) no_sysdaemon_sw is a switch that indicates whether the rw *.SysDaemon.* entry is to be put on the initial ACL after the existing initial ACL is deleted and before the user-supplied segment_acl entries are added. (Input) "0"b adds rw *.SysDaemon.* entry "1"b replaces the existing initial ACL with only the user-supplied segment_acl ring is the ring number of the initial ACL. (Input) code is a storage system status code. (Output) Notes: If acl_count is zero, then the existing initial ACL is deleted and only the action indicated (if any) by the no_sysdaemon_sw switch is performed. If acl_count is greater than zero, processing of the segment_acl entries is performed top to bottom, allowing later entries to overwrite previous ones if the access_name in the segment_acl structure is identical. :Entry: set_256K_switch: 03/03/83 hcs_$set_256K_switch Function: This entry point sets the per-process switch which controls whether or not segments of maximum length 256K (262144 words) can be used. The standard maximum length for a segment, defined as sys_info$max_seg_size, is 261120 words. The only supported use of 256K segments is for Fortran Very Large Arrays. Syntax: declare hcs_$set_256K_switch entry (bit(2) aligned, bit(2) aligned, fixed bin(35)); call hcs_$set_256K_switch (new_switch, old_switch, code); Arguments: new_switch is the new control value. If it is "11"b, the process may use 256K segments. If it is "10"b, the process may not use such segments. (Input) old_switch is the previous value of the switch. (Output) code is 0 if the operation was performed. It is error_table_$action_not_performed if the caller's validation level is larger than the initial ring of the process or if new_switch is not "10"b or "11"b. Notes: If the switch has the value "10"b, an attempt to connect to a segment having a maximum length greater than sys_info$max_seg_size words will cause a seg_fault_error, with error code error_table_$big_seg. The error occurs when the process attempts to reference the contents of the segment, not when the segment is made known using hcs_$initiate. :Entry: set_automatic_ips_mask: 03/08/82 hcs_$set_automatic_ips_mask Function: replaces the entire automatic ips mask with a supplied value, and returns the previous value of the automatic ips mask with a control bit of "1"b. Syntax: declare hcs_$set_automatic_ips_mask entry (bit(36) aligned, bit(36) aligned); call hcs_$set_automatic_ips_mask (mask, old_mask); Arguments: mask is the new value to replace the automatic ips mask. (Input) old_mask is the former value of the automatic ips mask, with a control bit of "1"b. (Output) Notes: The create_ips_mask_ subroutine can be used to create a mask, given a set of ips names. The automatic ips mask controls the state of the ips mask at the time that an ips signal handler is called. The interpretation of the bits in the automatic ips mask is quite different from that of the bits in the ips mask. When an ips interrupt occurs, if the bit corresponding to that interrupt is on in the automatic ips mask, then automatic ips masking takes place -- i.e., all ips interrupts are temporarily masked off, as described below. If the bit is off, then the ips mask is not changed. If automatic ips masking is to take place for a given ips interrupt, then the current value of the ips mask is saved in the machine conditions, with its control bit on, and the ips mask is set to all zero bits, thus disabling all ips interrupts. This happens before the handler for the interrupt is called. When an ips interrupt handler returns, if the control bit in the saved ips mask is on, then the current ips mask is replaced by the saved one. It follows from this that the handler for an ips interrupt for which automatic ips masking is in effect can not make a permanent change to the ips mask unless it also modifies the machine conditions, turning off the control bit in the saved ips mask. :Entry: set_bc: 03/08/82 hcs_$set_bc Function: sets the bit count of a specified segment. It also sets the bit count author of that segment to be the user who called it. Syntax: declare hcs_$set_bc entry (char(*), char(*), fixed bin(24), fixed bin(35)); call hcs_$set_bc (dir_name, entryname, bit_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) bit_count is the new bit count of the segment. (Input) code is a storage system status code. (Output) Access required: The user must have write access on the segment, but does not need modify permission on the containing directory. Notes: The hcs_$set_bc_seg entry point performs the same function, when a pointer to the segment is provided instead of the pathname. :Entry: set_bc_seg: 03/08/82 hcs_$set_bc_seg Function: given a pointer to the segment, sets the bit count of a segment in the storage system. It also sets that bit count author of the segment to be the user who called it. Syntax: declare hcs_$set_bc_seg entry (ptr, fixed bin(24), fixed bin(35)); call hcs_$set_bc_seg (seg_ptr, bit_count, code); Arguments: seg_ptr is a pointer to the segment whose bit count is to be changed. (Input) bit_count is the new bit count of the segment. (Input) code is a storage system status code. (Output) Access required: The user must have write access on the segment, but does not need modify permission on the containing directory. Notes: The hcs_$set_bc entry point performs the same function, when provided with a pathname of a segment rather than a pointer. :Entry: set_dir_ring_brackets: 03/08/82 hcs_$set_dir_ring_brackets Function: given the pathname of the containing directory and the entryname of the subdirectory, sets the subdirectory's ring brackets. Syntax: declare hcs_$set_dir_ring_brackets entry (char(*), char(*), (2) fixed bin(3), fixed bin(35)); call hcs_$set_dir_ring_brackets (dir_name, entryname, drb, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the subdirectory. (Input) drb is a two-element array specifying the ring brackets of the directory. (Input) The first element contains the level required for modify and append permission; the second element contains the level required for status permission. code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. Also, the validation level must be less than or equal to both the present value of the first ring bracket and the new value of the first ring bracket that the user wishes set. Ring brackets and validation levels are discussed in "Intraprocess Access Control" in the Reference Manual. :Entry: set_entry_bound: 03/08/82 hcs_$set_entry_bound Function: given a directory name and an entryname, sets the entry point bound of a segment. The entry point bound attribute provides a way of limiting which locations of a segment may be targets of a call. This entry point allows the caller to enable or disable a hardware check of calls to a given segment from other segments. If the mechanism is enabled, all calls to the segment must be made to an entry point whose offset is less than the entry point bound. In practice, this attribute is most effective when all of the entry points are located at the base of the segment. In this case, the entry point bound is the number of callable words. Syntax: declare hcs_$set_entry_bound entry (char(*), char(*), fixed bin(14), fixed bin(35)); call hcs_$set_entry_bound (dir_name, entryname, entry_bound, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) entry_bound is the new value in words for the entry point bound of the segment. (Input) If the value of entry_bound is 0, then the mechanism is disabled. code is a storage system status code. (Output) It can be: error_table_$argerr if an attempt is made to set the entry point bound of a segment greater than the system maximum of 16383. Access required: The user must have modify permission on the containing directory. Notes: A directory cannot have its entry point bound changed. The hcs_$set_entry_bound_seg entry point can be used when a pointer to the segment is given, rather than a pathname. :Entry: set_entry_bound_seg: 03/08/82 hcs_$set_entry_bound_seg Function: given a pointer to a segment, sets the entry point bound of the segment. The entry point bound attribute provides a way of limiting which locations of a segment may be targets of a call. This entry point allows the caller to enable or disable a hardware check of calls to a given segment from other segments. If the mechanism is enabled, all calls to the segment must be made to an entry point whose offset is less than the entry point bound. In practice, this attribute is most effective when all of the entry points are located at the base of the segment. In this case, the entry point bound is the number of callable words. Syntax: declare hcs_$set_entry_bound_seg entry (ptr, fixed bin(14), fixed bin(35)); call hcs_$set_entry_bound_seg (seg_ptr, entry_bound, code); Arguments: seg_ptr is a pointer to the segment whose entry point bound is to be changed. (Input) entry_bound is the new value in words for the entry point bound of the segment. (Input) If the value of entry_bound is 0, then the mechanism is disabled. code is a storage system status code. (Output) (See "Notes" below.) Notes: A directory cannot have its entry point bound changed. The user must have modify permission on the containing directory. If an attempt is made to set the entry point bound of a segment to greater than the system maximum of 16383, code is set to error_table_$argerr. The hcs_$set_entry_bound entry point can be used when a pathname of the segment is given, rather than a pointer. :Entry: set_exponent_control: 03/08/82 hcs_$set_exponent_control Function: changes the current settings of the flags that control the system's handling of exponent overflow and underflow conditions. Syntax: declare hcs_$set_exponent_control entry (bit(1) aligned, bit(1) aligned, float bin(63), fixed bin (35)); call hcs_$set_exponent_control (restart_underflow, restart_overflow, overflow_value, code); Arguments: restart_underflow is "1"b if underflows should be automatically restarted, and "0"b otherwise. (Input) restart_overflow is "1"b if overflows should be automatically restarted, and "0"b otherwise. (Input) overflow_value is the value used for the result of the computation in the case of overflow. (Input) code is a standard status code. (Output) Notes: When either of the two flags are set to zero, the corresponding error condition causes the appropriate fault condition to be signalled. If a flag is set to one, then the computation resulting in the error is automatically restarted. In the case of underflow its result is set to zero. In the case of positive overflow, its value is set to the value specified in overflow_value. In the case of negative overflow, the negative of overflow_value is used. The default value is the largest representable positive number, available as Default_exponent_control_overflow_value in the include file exponent_control.incl.pl1. This subroutine affects only the system's handling of exponent overflow and underflow when the overflow condition or the underflow condition is raised. In certain cases, the error condition is raised instead; this subroutine does not affect the system's handling of such cases. In programs not written in PL/I, the exponent_control_ subroutine should be used in place of hcs_$set_exponent_control. :Entry: set_ips_mask: 03/08/82 hcs_$set_ips_mask Function: replaces the entire ips mask with a supplied value, and returns the previous value of the mask with a control bit of "1"b. It can be used at the beginning of a critical section of code, to disable one or more ips interrupts, and turn on the control bit to indicate that some interrupts are disabled. See "Notes" in the description of the hcs_$get_ips_mask entry point for a discussion of the control bit. Syntax: declare hcs_$set_ips_mask entry (bit(36) aligned, bit(36) aligned); call hcs_$set_ips_mask (mask, old_mask); Arguments: mask is the new value to replace the ips mask. (Input) A "1" bit in each mask position enables the corresponding ips interrupt. old_mask is the former value of the ips mask, with a control bit of "1"b. (Output) Notes: The create_ips_mask_ subroutine can be used to create a mask, given a set of ips names. The hcs_$reset_ips_mask entry point can be used at the end of a critical section of code to undo the mask changes made by this entry point, by setting the mask to the old_mask value returned by this entry point. :Entry: set_max_length: 03/08/82 hcs_$set_max_length Function: given a directory name, sets the maximum length (in words) of a segment. Syntax: declare hcs_$set_max_length entry (char(*), char(*), fixed bin(19), fixed bin(35)); call hcs_$set_max_length (dir_name, entryname, max_length, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) max_length is the new value in words for the maximum length of the segment. (Input) code is a storage system status code. (Output) It can be: error_table_$argerr if an attempt is made to set the maximum length of a segment to greater than the system maximum, sys_info$max_seg_size. error_table_$invalid_max_length if an attempt is made to set the maximum length of a segment to less than its current length. Access required: The user must have modify permission on the containing directory. Notes: A directory cannot have its maximum length changed. The maximum length of a segment is accurate to units of 1024 words, and if max_length is not a multiple of 1024 words, it is set to the next multiple of 1024 words. The hcs_$set_max_length_seg entry point can be used when the pointer to the segment is given, rather than a pathname. :Entry: set_max_length_seg: 03/08/82 hcs_$set_max_length_seg Function: given the pointer to the segment, sets the maximum length (in words) of a segment. Syntax: declare hcs_$set_max_length_seg entry (ptr, fixed bin(19), fixed bin(35)); call hcs_$set_max_length_seg (seg_ptr, max_length, code); Arguments: seg_ptr is the pointer to the segment whose maximum length is to be changed. (Input) max_length is the new value in words for the maximum length of the segment. (Input) code is a storage system status code. (Output) It can be: error_table_$argerr if an attempt is made to set the maximum length of a segment to greater than the system maximum, sys_info$max_seg_size. error_table_$invalid_max_length if an attempt is made to set the maximum length of a segment to less than its current length. Access required: The user must have modify permission on the containing directory. Notes: A directory cannot have its maximum length changed. The maximum length of a segment is accurate to units of 1024 words, and if max_length is not a multiple of 1024 words, it is set to the next multiple of 1024 words. The hcs_$set_max_length entry point can be used when a pathname of the segment is given, rather than the pointer. :Entry: set_procs_required: 01/16/87 hcs_$set_procs_required Function: sets the per-process CPUs required. Syntax: declare hcs_$set_procs_required entry (bit (8) aligned, fixed bin (35)); call hcs_$set_procs_required (procs_required, code); Arguments: procs_required is the set of processors required. If "0"b, the system default set of CPUs is assumed. (Input) code is a standard system error code. (Output) Access required: This operation requires rw permission on >sc1>admin_acs>set_proc_required.acs. :Entry: set_ring_brackets: 03/08/82 hcs_$set_ring_brackets Function: given the directory name and entryname of a nondirectory segment, sets the segment's ring brackets. Syntax: declare hcs_$set_ring_brackets entry (char(*), char(*), (3) fixed bin(3), fixed bin(35)); call hcs_$set_ring_brackets (dir_name, entryname, rb, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) rb is a three-element array specifying the ring brackets of the segment; see "Notes" below. (Input) code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. Also, the validation level must be less than or equal to both the present value of the first ring bracket and the new value of the first ring bracket that the user wishes set. Notes: Ring brackets must be ordered as rb1 <= rb2 <= rb3 Ring brackets and validation levels are discussed in "Intraprocess Access Control" in the Reference Manual. :Entry: set_safety_sw: 03/08/82 hcs_$set_safety_sw Function: allows the safety switch associated with a segment or directory to be changed. The segment is designated by a directory name and an entryname. See "Segment, Directory, and Link Attributes" in the Reference Manual for a description of the safety switch. Syntax: declare hcs_$set_safety_sw entry (char(*), char(*), bit(1), fixed bin(35)); call hcs_$set_safety_sw (dir_name, entryname, safety_sw, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment or directory. (Input) safety_sw is the new value of the safety switch. (Input) "0"b if the segment can be deleted "1"b if the segment cannot be deleted code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. Notes: The hcs_$set_safety_sw_seg entry point can be used when the pointer to the segment is given, rather than a pathname. :Entry: set_safety_sw_seg: 03/08/82 hcs_$set_safety_sw_seg Function: given a pointer to a segment, sets the safety switch of the segment. See "Segment, Directory, and Link Attributes" in the Reference Manual for a description of the safety switch. Syntax: declare hcs_$set_safety_sw_seg entry (ptr, bit(1), fixed bin(35)); call hcs_$set_safety_sw_seg (seg_ptr, safety_sw, code); Arguments: seg_ptr is the pointer to the segment. (Input) safety_sw is the new value of the safety switch. (Input) "0"b if the segment can be deleted "1"b if the segment cannot be deleted code is a storage system status code. (Output) Access required: The user must have modify permission on the containing directory. Notes: The hcs_$set_safety_sw entry point can be used when a pathname of the segment is given, rather than the pointer. :Entry: star_: 03/08/82 hcs_$star_ Function: is the star convention handler for the storage system. (See "Constructing and Interpreting Names" in the Reference Manual.) It is called with a directory name and an entryname that is a star name (contains asterisks or question marks). The directory is searched for all entries that match the given entryname. Information about these entries is returned in a structure. If the entryname is **, information on all entries in the directory is returned. The hcs_$star_ entry point returns the storage system type and all names that match the given entryname. Syntax: declare hcs_$star_ entry (char(*), char(*), fixed bin(2), ptr, fixed bin, ptr, ptr, fixed bin(35)); call hcs_$star_ (dir_name, star_name, star_select_sw, area_ptr, star_entry_count, star_entry_ptr, star_names_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) star_name is the entryname that can contain asterisks or question marks. (Input) star_select_sw indicates what information is to be returned. (Input) It can be: star_LINKS_ONLY (=1) information is returned about link entries only star_BRANCHES_ONLY (=2) information is returned about segment and directory entries only star_ALL_ENTRIES (=3) information is returned about segment, directory, and link entries. area_ptr is a pointer to the area in which information is to be returned. (Input) If the pointer is null, star_entry_count is set to the total number of entries in the directory that match star_name. star_entry_count is a count of the number of entries that match the entryname. (Output) star_entry_ptr is a pointer to the allocated structure in which information on each entry is returned. (Output) See "Notes" below. This data structure is declared in star_structures.incl.pl1. star_names_ptr is a pointer to the allocated array of all the entrynames in this directory that match star_name. (Output) See "Notes" below. code is a storage system status code. (Output) It can be: error_table_$nomatch if no match with star_name was found in the directory. error_table_$badstar if star_name contained illegal syntax with respect to the star convention. error_table_$notalloc if the user did not provide enough space in the area to return all requested information. In this case, the total number of entries will be returned, to provide an estimate of space required. Access required: Status permission is required on the directory to be searched. Notes: If area_ptr is null, star_entry_count is set to the total number of entries in the directory that match star_name. The setting of star_select_sw determines whether star_entry_count is the total number of link entries, the total number of segment and directory entries, or the total number of all entries. If area_ptr is not null, the entry information structure and the name array are allocated in the user-supplied area. A program using star_structures.incl.pl1 should declare addr, binary, and sum to be builtin. The arguments star_entry_count, star_entry_ptr, and star_names_ptr are declared in the include file along with named constants for the value of star_select_sw and the storage system type. One of the named constants for star_select_sw can be passed as an argument to hcs_$star_ along with star_entry_count, star_entry_ptr and star_names_ptr. :Entry: star_list_: 03/08/82 hcs_$star_list_ Function: returns more information about the selected entries, such as the mode and records used for segments and directories and link pathnames for links. This entry point obtains the records used and the date of last modification and last use from the VTOC, and is, therefore, more expensive to use than the hcs_$star_dir_list_ entry point. Syntax: declare hcs_$star_list_ entry (char(*), char(*), fixed bin(3), ptr, fixed bin, fixed bin, ptr, ptr, fixed bin(35)); call hcs_$star_list_ (dir_name, star_name, star_select_sw, area_ptr, star_branch_count, star_link_count, star_list_branch__ptr, star_list_names_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) star_name is the entryname that can contain asterisks or question marks. (Input) star_select_sw indicates what information is to be returned. (Input) All of the following are declared in star_structures.incl.pl1: star_LINKS_ONLY (=1) star_BRANCHES_ONLY (=2) star_ALL_ENTRIES (=3) star_LINKS_ONLY_WITH_LINK_PATHS (=5) star_ALL_ENTRIES_WITH_LINK_PATHS (=7) area_ptr is a pointer to the area in which information is to be returned. (Input) If the pointer is null, star_branch_count and star_link_count are set to the total number of selected entries. See "Notes" below. star_branch_count is a count of the number of segments and directories that match star_name. (Output) star_link_count is a count of the number of links that match star_name. (Output) star_list_branch_ptr is a pointer to the allocated structure in which information on each entry is returned. (Output) The star_list_branch structure is used if the entry is a segment or a directory. The star_links structure is used if the entry is a link. Both are declared in star_structures.incl.pl1. star_list_names_ptr is a pointer to the allocated array in which selected entrynames and pathnames associated with link entries are stored. (Output) The star_list_names structure is the array of names. It is declared in star_structures.incl.pl1. code is a storage system status code. (Output) It can be: error_table_$nomatch if no match with star_name was found in the directory. error_table_$badstar if star_name contained illegal syntax with respect to the star convention. error_table_$notalloc if the user did not provide enough space in the area to return all requested information. In this case, the total number of entries will be returned, to provide an estimate of space required. Notes: If the system is unable to access the VTOC entry for a branch, values of zero are returned for records used, date_time_contents_modified, and date_time_used, and no error code is returned. Callers of this entry point should interpret zeros for all three of these values as an error indication, rather than as valid data. A program using star_structures.incl.pl1 should declare addr, binary and sum to be builtin. The star_branch_count, star_entry_ptr, star_link_count, star_linkx, star_list_names_ptr and star_select_sw variables are declared in the include file along with named constants for the value of star_select_sw and the storage system type. To use the structures in the include file, first assign to star_select_sw the proper named constant and then pass star_select_sw as an argument to hcs_$star_list_ along with star_branch_count, star_link_count, star_list_branch_ptr, and star_list_names_ptr. The star_link_pathname based variable is used to get the pathname associated with link star_linkx in the star_links array. It is declared in star_structures.incl.pl1. To get the link pathname associated with a link, assign to star_linkx the index of the link in star_links. Star_link_pathname will then be link pathname. :Entry: star_dir_list_: 03/06/85 hcs_$star_dir_list_ Function: This entry point returns information about the selected entries, such as the mode and bit count for branches, and link pathnames for links. It returns only information kept in directory branches, and does not access the VTOC entries for branches. This entry point is more efficient than the hcs_$star_list_ entry point. Syntax: declare hcs_$star_dir_list_ entry (char(*), char(*), fixed bin(2), ptr, fixed bin, fixed bin, ptr, ptr, fixed bin(35)); call hcs_$star_dir_list_ (dir_name, star_name, star_select_sw, area_ptr, star_branch_count, star_link_count, star_list_branch_ptr, star_list_names_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) star_name is the entryname that can contain asterisks or question marks. (Input) star_select_sw indicates what information is to be returned. (Input) It can be: star_LINKS_ONLY (=1) information is returned about link entries only. star_BRANCHES_ONLY (=2) information is returned about segment and directory entries only. star_ALL_ENTRIES (=3) information is returned about segment, directory, and link entries. star_LINKS_ONLY_WITH_LINK_PATHS (=5) information is returned about link entries only, including the pathname associated with each link entry. star_ALL_ENTRIES_WITH_LINK_PATHS (=7) information is returned about segment, directory, and link entries, including the pathname associated with each link entry. area_ptr is a pointer to the area in which information is to be returned. If the pointer is null, star_branch_count and star_link_count are set to the total number of selected entries. See "Notes" below. (Input) star_branch_count is a count of the number of segments and directories that match the entryname. (Output) star_link_count is a count of the number of links that match the entryname. (Output) star_list_branch_ptr is a pointer to the allocated structure in which information on each entry is returned. (Output) star_list_names_ptr is a pointer to the allocated array in which selected entrynames and pathnames associated with link entries are stored. (Output) code is a storage system status code. See "Status Codes" above in the description of hcs_$star_ entry point. (Output) Notes: The names star_LINKS_ONLY through STAR_ALL_ENTRIES_WITH_LINK_PATHS are declared in star_structures.incl.pl1. The star_LINKS_ONLY, star_BRANCHES_ONLY, and star_ALL_ENTRIES are declared fixed bin (2) for compatability with hcs_$star and the star_LINKS_ONLY_WITH_LINK_PATHS and star_ALL_ENTRIES_WITH_LINK_PATHS are declared as fixed bin (3). If area_ptr is null, star_branch_count and star_link_count may be set. If information on segments and directories is requested, star_branch_count is set to the total number of segments and directories that match star_name. If information on links is requested, star_link_count is the total number of links that match star_name. If area_ptr is not null, an array of entry information structures and the names array, as described in the hcs_$star_ entry point above, are allocated in the user-supplied area. Each element in the structure array may be either of the structures described below (the star_links structure for links or the star_list_branch structure for segments and directories). The correct structure is indicated by the type item, the first item in both structures. If the system is unable to access the VTOC entry for a branch, values of zero are returned for records used, date_time_contents_modified, and date_time_used, and no error code is returned. Callers of this entry point should interpret zeros for all three of these values as an error indication, rather than as valid data. The star_links structure described for hcs_$star_list is used if the entry is a link. :Entry: status_long: 05/12/82 hcs_$status_long Function: returns most user-accessible information about a specified entry. Syntax: declare hcs_$status_long entry (char(*), char(*), fixed bin(1), ptr, ptr, fixed bin(35)); call hcs_$status_long (dir_name, entryname, chase_sw, status_ptr, status_area_ptr, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment, directory, or link. (Input) chase_sw indicates whether the information returned is about a link or about the entry to which the link points. (Input) 0 returns link information 1 returns information about the entry to which the link points status_ptr is a pointer to the structure in which information is returned. (Input) status_area_ptr is a pointer to the area in which names are returned. (Input) If the pointer is null, no names are returned. If the entry is a link, it points to the status_link structure. If the entry is a segment, directory, or multisegment file, it points to the status_branch structure. Both are defined in status_structures.incl.pl1. code is a storage system status code. (Output) Access required: The user must have either status permission on the containing directory or nonnull access to the object to obtain complete information. Entrynames, however, are not returned unless the user has status permission on the containing directory. Notes: For compatability with older programs, if entryname is given as a null string, status is returned on the directory given as dir_name. :Entry: status_minf: 03/08/82 hcs_$status_minf Function: returns the bit count and entry type given the name of a directory and an entry. Status permission on the directory or nonnull access on the entry is required to use this entry point. Syntax: declare hcs_$status_minf entry (char(*), char(*), fixed bin(1), fixed bin(2), fixed bin(24), fixed bin(35)); call hcs_$status_minf (dir_name, entryname, chase_sw, type, bit_count, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment, directory, or link. (Input) chase_sw indicates whether the information returned is about a link or about the entry to which the link points. (Input) 0 returns link information 1 returns information about the entry to which the link points type specifies the type of entry. (Output) It can be: 0 link 1 segment 2 directory bit_count is the bit count. (Output) code is a storage system status code. (Output) :Entry: status_mins: 03/08/82 hcs_$status_mins Function: returns the bit count and entry type given a pointer to the segment. Status permission on the directory or nonnull access to the segment is required to use this entry point. Syntax: declare hcs_$status_mins entry (ptr, fixed bin(2), fixed bin(24), fixed bin(35)); call hcs_$status_mins (seg_ptr, type, bit_count, code); Arguments: seg_ptr points to the segment about which information is desired. (Input) type specifies the type of entry. (Output) It can be: 0 link 1 segment 2 directory bit_count is the bit count. (Output) code is a storage system status code. (Output) :Entry: terminate_noname: 03/08/82 hcs_$terminate_noname Function: terminates a null reference name from the specified segment and decrements a count of initiated reference names for the segment. Syntax: declare hcs_$terminate_noname entry (ptr, fixed bin(35)); call hcs_$terminate_noname (seg_ptr, code); Arguments: seg_ptr is a pointer to the segment. (Input/Output) code is a storage system status code. (Output) Notes: If a segment is concurrently initiated more than a system-defined number of times, the usage count of the segment is said to be in an overflowed condition. Under such circumstances, the hcs_$terminate_noname entry point does not reduce the usage count, but leaves the segment in the overflowed state. To terminate the segment, hcs_$terminate_file or hcs_$terminate_seg should be used. If the hcs_$terminate_noname entry point reduces the count of initiated reference names of the segment to zero, the segment is removed from the address space of the process (made unknown). This entry point is used to clean up after making a segment known and initiating a single null reference name; see also the hcs_$initiate, hcs_$initiate_count, and hcs_$make_seg entry points. For a discussion of reference names, see "Constructing and Interpreting Names" in the Reference Manual. The hcs_$terminate_name entry point terminates a specified nonnull reference name; hcs_$terminate_file and hcs_$terminate_seg entry points terminate all reference names of a segment and make the segment unknown, given its pathname or segment number, respectively. :Entry: terminate_file: 03/08/82 hcs_$terminate_file Function: given the pathname of a segment, terminates all the reference names of that segment and then removes the segment from the address space of the process (makes the segment unknown). For a discussion of reference names, see "Constructing and Interpreting Names" in the Reference Manual. Syntax: declare hcs_$terminate_file entry (char(*), char(*), fixed bin(1), fixed bin(35)); call hcs_$terminate_file (dir_name, entryname, seg_sw, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) seg_sw is the reserved segment switch. (Input) 1 saves segment number in the reserved segment list 0 does not save segment number code is a storage system status code. (Output) Notes: The hcs_$terminate_seg entry point performs the same operation given a pointer to a segment instead of a pathname; the hcs_$terminate_name and hcs_$terminate_noname entry points terminate a single reference name. The term_ subroutine performs the same operation as the hcs_$terminate_file entry point, but, in addition, causes links to the entry's linkage section to be unsnapped. Use of the term_ subroutine is recommended. The reference names that are removed are those for which the ring level associated with the name is greater than or equal to the validation level of the process. If any reference names exist that are associated with a ring level less than the validation level of the process, the segment is not made unknown and the code is returned as error_table_$bad_ring_brackets. For a discussion of rings, refer to "Intraprocess Access Control" in the Reference Manual. :Entry: terminate_name: 03/08/82 hcs_$terminate_name Function: terminates one reference name from a segment and decrements a count of initiated reference names for the segment. Syntax: declare hcs_$terminate_name entry (char(*), fixed bin(35)); call hcs_$terminate_name (ref_name, code); Arguments: ref_name is the reference name to be terminated. (Input) code is a storage system status code. (Output) Notes: If a segment is concurrently initiated more than a system-defined number of times, the usage count of the segment is said to be in an overflowed condition. Under such circumstances, the hcs_$terminate_name entry point does not reduce the usage count, but leaves the segment in the overflowed state. To terminate the segment, hcs_$terminate_file or hcs_$terminate_seg should be used. If the hcs_$terminate_name entry point reduces the count of initiated reference names for that segment to zero, the segment is removed from the address space of the process (made unknown). For a discussion of reference names, see "Constructing and Interpreting Names" in the Reference Manual. The hcs_$terminate_noname entry point terminates a null reference name from a specified segment; the hcs_$terminate_file and hcs_$terminate_seg entry points terminate all reference names of a segment and make the segment unknown, given its pathname or segment number, respectively. The term_$single_refname entry point (see the description of the term_ subroutine) performs the same operation as the hcs_$terminate_name entry point, unsnapping links as well. Use of the term_ subroutine is recommended. :Entry: terminate_seg: 03/08/82 hcs_$terminate_seg Function: given a pointer to a segment in the current process, terminates all the reference names of that segment and then removes the segment from the address space of the process (makes it unknown). For a discussion of reference names, see the "Constructing and Interpreting Names" in the Reference Manual. Syntax: declare hcs_$terminate_seg entry (ptr, fixed bin(1), fixed bin(35)); call hcs_$terminate_seg (seg_ptr, seg_sw, code); Arguments: seg_ptr is a pointer to the segment to be terminated. (Input) seg_sw is the reserved segment switch. (Input) 1 saves segment number in reserved segment list 0 does not save segment number code is a storage system status code. (Output) Notes: The hcs_$terminate_file entry point performs the same operation given the pathname of a segment instead of a pointer; the hcs_$terminate_name and hcs_$terminate_noname entry points terminate a single reference name. The term_$seg_ptr entry point (see the term_ subroutine description) performs the same operation as the hcs_$terminate_seg entry point, unsnapping links as well. Use of the term_ subroutine is recommended. The only reference names that are removed are those for which the ring level associated with the name is greater than or equal to the validation level of the process. If any reference names exist that are associated with a ring level less than the validation level of the process, the segment is not made unknown and the code is returned as error_table_$bad_ring_brackets. For a discussion of rings refer to "Intraprocess Access Control" in the Reference Manual. :Entry: truncate_file: 03/08/82 hcs_$truncate_file Function: given a pathname, truncates a segment to a specified length. If the segment is already shorter than the specified length, no truncation is done. The effect of truncating a segment is to store zeros in the words beyond the specified length. Syntax: declare hcs_$truncate_file entry (char(*), char(*), fixed bin(19), fixed bin(35)); call hcs_$truncate_file (dir_name, entryname, length, code); Arguments: dir_name is the pathname of the containing directory. (Input) entryname is the entryname of the segment. (Input) length is the new length of the segment in words. (Input) code is a storage system status code. (Output) Access required: The user must have write access on the segment in order to truncate it. Notes: A directory cannot be truncated. A segment is truncated as follows: all full pages after the page containing the last word of the new length segment (as defined by the length argument) are discarded. The remainder of the page containing the last word is converted to zeros. Bit count is not automatically set by the hcs_$truncate_file entry point. If desired, bit count may be set by using the hcs_$set_bc entry point. The hcs_$truncate_seg entry point performs the same function when given a pointer to the segment instead of the pathname. :Entry: truncate_seg: 03/08/82 hcs_$truncate_seg Function: given a pointer, truncates a segment to a specified length. If the segment is already shorter than the specified length, no truncation is done. The effect of truncating a segment is to store zeros in the words beyond the specified length. Syntax: declare hcs_$truncate_seg entry (ptr, fixed bin(19), fixed bin(35)); call hcs_$truncate_seg (seg_ptr, length, code); Arguments: seg_ptr is a pointer to the segment to be truncated. (Input) Only the segment number portion of the pointer is used. length is the new length of the segment in words. (Input) code is a storage system status code. (Output) Access required: The user must have write access on the segment in order to truncate it. Notes: A directory cannot be truncated. A segment is truncated as follows: all full pages after the page containing the last word of the new length (as defined by the length argument) segment are discarded. The remainder of the page containing the last word is converted to zeros. Bit count is not automatically set by the hcs_$truncate_seg entry point. If desired, bit count may be set by using the hcs_$set_bc_seg entry point. The hcs_$truncate_file entry point performs the same function when given the pathname of the segment instead of the pointer. :Entry: validate_processid: 03/05/85 hcs_$validate_processid Function: This entry determines whether a 36-bit quantity is the unique identifier of a process which is currently active on the system. Syntax: declare hcs_$validate_processid entry (bit(36) aligned, fixed bin(35)); call hcs_$validate_processid (processid, code); Arguments: processid contains a quantity which may be the unique identifier of an active process. (Input) code is a standard status code. (Output) If processid is the unique identifier of an active process, the value returned is zero. Otherwise, the value is error_table_$process_unknown. :Entry: unmask_ips: 03/08/82 hcs_$unmask_ips Function: masks off, or disables, the specified ips interrupts. This entry point can be used at the beginning of a critical section of code to disable one or more ips interrupts, and turn on the control bit as an indication that some interrupts are disabled. See "Notes" in the description of the hcs_$mask_ips entry point for a discussion of the control bit. Syntax: declare hcs_$unmask_ips entry (bit(36) aligned, bit(36) aligned); call hcs_$unmask_ips (mask, old_mask) Arguments: mask is a word containing a "1"b for each ips interrupt that is to be disabled. (Input) See "Notes". old_mask is the former value of the ips mask, with a control bit of "1"b. (Output) Notes: The create_ips_mask_ subroutine can be used to create a mask, given a set of ips names. The hcs_$mask_ips entry point can be used at the end of a critical section of code, to undo the mask changes made by this entry point. :Entry: wakeup: 03/08/82 hcs_$wakeup Function: sends an interprocess communication wakeup signal to a specified process over a specified event channel. If that process has previously called the ipc_$block entry point, it is awakened. See the ipc_ subroutine description. Syntax: declare hcs_$wakeup entry (bit(36) aligned, fixed bin(71), fixed bin(71), fixed bin(35)); call hcs_$wakeup (process_id, channel_id, message, code); Arguments: process_id is the process identifier of the target process. (Input) channel_id is the identifier of the event channel over which the wakeup is to be sent. (Input) message is the event message to be interpreted by the target process. (Input) code is a standard status code. (Output) ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved