Bull HN Migration Guide MULTICS TO UNIX MIGRATION GUIDE PREPARED BY: ACTC TECHNOLOGIES INC. DATE: DECEMBER 21, 1990 SUBJECT A guide to porting Multics products to a UNIX environment. SPECIAL INSTRUCTIONS This guide assumes basic knowledge of the Multics and UNIX operating systems. 12/13/90 i Migration Guide Bull HN PREFACE _P_u_r_p_o_s_e _a_n_d _A_u_d_i_e_n_c_e This guide is intended for use by sites migrating from a Multics system to a BullHN UNIX system. It provides information on 1) significant areas of difference between Multics and UNIX, including those that may cause the user difficulty; 2) the Migration Package; 3) porting applications; and 4) descriptions of the communication tools used for porting. This guide does not provide a complete description of either UNIX or Multics but is merely intended as an aid to migration. It is assumed that the reader of this guide is an experienced Multics user. (For a full discussion of the UNIX system refer to the UNIX manuals described in the References section of this guide.) Currently, the development system for the Migration Package is a DPX/2 running System V UNIX. _H_o_w _t_h_i_s _g_u_i_d_e _i_s _o_r_g_a_n_i_z_e_d Section 1, The Multics to UNIX Migration Package, describes the components of the Migration Package. Section 2, Communications Protocols, describes how to connect to the DPX/2 and how to transfer files with cu (UNIX connect utility) and Kermit. Section 3, Differences Between Multics and UNIX, discusses those differences between the two systems that are significant to the migration of Multics software to UNIX. This section will be of particular interest to Multics programmers, as it gives background information on UNIX necessary for porting or rewriting software. Section 4, Porting Applications, suggests approaches and considerations for porting applications from Multics to UNIX. This section provides information useful to those users doing the initial porting of software. Section 5, Administration, briefly describes some of the administrative features of System V UNIX, including accounting and security. This section should be of interest to system administrators. Appendix A, Getting Started, describes the documents that should be read and what needs to be done in order to start using the Migration Package. This section should be read before attempting a port. ii 12/13/90 Bull HN Migration Guide Appendix B, Notes on DPX/2 Hardware and UNIX Software Errors and Incompatibilities, warns of potential problems associated with software ported to the DPX/2. Appendix C, Quick Reference to Multics/Unix Equivalents, lists Multics routines and facilities that have equivalents on UNIX. Appendix D, References, lists the Multics and UNIX manuals that are significant to the migration process. 12/13/90 iii Migration Guide Bull HN _C_o_n_v_e_n_t_i_o_n_s _u_s_e_d _i_n _t_h_i_s _g_u_i_d_e a. Multics Manuals will be referred to in this guide by the explicit order numbers. UNIX Manuals will be referred to by an entry name and section number. For example printf(3) refers to the entry printf in section 3 of the standard UNIX manuals. b. Braces {} are used in this guide to enclose optional information. For example command {control arguments} argument _C_o_p_y_r_i_g_h_t _I_n_f_o_r_m_a_t_i_o_n Copyright, (C) BullHN Information Systems Inc, 1989. _T_r_a_d_e_m_a_r_k _I_n_f_o_r_m_a_t_i_o_n UNIX is a registered trademark of AT&T Bell Laboratories. iv 12/13/90 Bull HN Migration Guide _T_A_B_L_E _O_F _C_O_N_T_E_N_T_S _S_e_c_t_i_o_n _S_u_b_j_e_c_t _P_a_g_e 1 The Multics to UNIX Migration Package 1 1.1 . . Overview 1 1.2 . . Documentation 1 1.3 . . Migration Support Routines on UNIX 2 1.3.1 . . . . Commands 2 1.3.2 . . . . Subroutines 3 1.3.3 . . . . I/O Modules 7 2 Communication Protocols 8 2.1 . . Kermit 8 2.1.1 . . . . Examples of File Transfers 9 2.2 . . Connect to UNIX (cu) 11 2.2.1 . . . . cu Connection Example: ASCII 11 3 Multics and UNIX Differences 13 3.1 . . Process Usage 13 3.2 . . Command Line Processing 15 3.3 . . Handling Special Characters in Filenames 15 3.4 . . Equivalent Commands 17 3.5 . . Active Function Handling 17 3.6 . . Dynamic Linking vs. Static Linking 18 3.7 . . File Systems 19 3.8 . . Time Clock Values 23 3.9 . . UNIX Limits 23 3.10 . . Multics Exec_Coms vs UNIX Shell Scripts 23 4 Porting Applications 27 4.1 . . Analysis 27 4.1.1 . . . . Conversion Considerations 28 4.2 . . Procedures 31 4.2.1 . . . . Standard PL/I Conversions 31 4.2.2 . . . . create_data_segment (cds) Files 32 4.2.3 . . . . create_error_table (cet) 33 4.2.4 . . . . Reduction Compiler (rdc) Source 33 4.2.5 . . . . Using the SDB Debugger 33 5 Administration 35 5.1 . . Accounting 35 5.1.1 . . . . Accounting Hierarchy 35 5.1.2 . . . . Accounting Information 36 5.2 . . Security 37 5.2.1 . . . . Accesses 38 5.2.2 . . . . Password Protection 40 5.2.3 . . . . Suggested Security Checks 40 6 Appendices 43 6.1 . . Appendix A: Getting Started 43 6.1.1 . . . . Initial Setup 43 6.1.2 . . . . Getting Help 45 6.1.3 . . . . Sample Session 45 6.2 . . Appendix B: Notes on DPX/2 Hardware and 48 UNIX Software Errors and Incompatibilities 6.2.1 . . . . CAS and CAS2 Instructions 48 12/13/90 v Migration Guide Bull HN 6.2.2 . . . . Incompatible UNIX System Routines 48 6.3 . . Appendix C: Quick Reference to Multics/UNIX 50 Equivalents 6.4 . . Appendix D: References 54 vi 12/13/90 Bull HN Migration Guide 1. The Multics to UNIX Migration Package 1.1. Overview The Multics to UNIX Migration Package consists of the PL/I compiler, porting tools, support routines and documentation that will assist the user migrating from Multics to UNIX. Porting tools are software entities that automate analysis or conversion activities. Support routines are commands or subroutines, either new or of Multics origin, that have been implemented on UNIX. Together, the migration tools and support routines make up the software products of this package. Documentation is in the form of online information files, a Multics/UNIX Product Differences Guide and this Migration Guide. Most components of the Migration Package reside on UNIX. The exceptions can be found on Multics and include the Multics/UNIX Product Differences Guide, this Migration Guide and the porting tools. Users that are new to the Migration Package are encouraged to review this guide, the Multics/UNIX Product Differences Guide and the UNIX online information file "migration.g.i" to fully understand the contents of the package, and the implications of product differences. The following sections describe the components of the migration package for each major area. 1.2. Documentation There are four major sources of information available to the user migrating from a Multics system to a UNIX system: 1. Migration product online information files. 2. Multics to UNIX Migration Guide. 3. Multics/UNIX Product Differences Guide. 4. Multics and UNIX system manuals. For each software product of the Migration Package there is an associated online information file. An information file describes the use of a product, and can be viewed using the "help" command on the appropriate system. 12/13/90 1 Migration Guide Bull HN The Multics to UNIX Migration Guide (this document), is a Multics online text file suitable for printing. This guide discusses the Migration Package, operating system differences and porting concerns. The Multics/UNIX Product Differences Guide is also a Multics online text file suitable for printing. This guide covers the Multics commands and subroutines that have been implemented on UNIX as part of the package, and discusses how they differ from their Multics equivalents. For a description of a product's use, refer to its online information file on UNIX. In addition to the documentation provided with the Migration Package, users may need to access existing Multics and UNIX manuals. (See Appendix C: References.) 1.3. Migration Support Routines on UNIX A number of new commands and subroutines are available on UNIX as a part of the Migration Package. Most of the commands and subroutines are based on Multics equivalents. The commands are available as stand-alone executables, while the subroutines take the form of object files that are generally found within a particular library. Each command or subroutine is accompanied by an online information file, and differences between the Multics and UNIX versions can be found in the Multics/UNIX Product Differences Guide. See the UNIX online information file "migration.g.i" for the location of the commands, subroutines, include files and information files on your system. 1.3.1. Commands This section lists the commands available as part of the Migration Package. The Multics name is given in parentheses for those commands derived from a Multics equivalent. For more information see the appropriate information file and, if applicable, the Multics/UNIX Product Differences Guide. cdo (create_data_segment, cds) The command cdo is based on the Multics version of create_data_segment. It translates a cdo (create data object) source file using the pl1 compiler into a UNIX Common Object File Format (COFF) object file. 2 12/13/90 Bull HN Migration Guide cet (ALM, for error tables only) The command cet translates a Multics ALM (Multics assembly language) error table source file into a UNIX Common Object File Format (COFF) object file. help (help) UNIX help is based on the Multics version of help, with minor changes due to system differences. Help selects information from files maintained online; these files are in a special format called info files. list_help, lh (list_help, lh) Displays the names of all info files pertaining to a given topic, similar to the Multics list_help command. pl1 (pl1) The UNIX implementation of the pl1 compiler corresponds as closely as possible to Multics pl1. Hardware and operating system differences have required some features to be dropped or modified, and in a few cases, added. rdc (reductions, rdc) The UNIX rdc command generates language translators and is based on the Multics version. It compiles a file containing reductions and action routines into a PL/I source file; it then invokes the pl1 compiler to compile the PL/I source. 1.3.2. Subroutines This section lists the subroutines available as part of the Migration Package. The Multics name is given in parentheses for those subroutines derived from a Multics equivalent. Subroutines that were based on a Multics equivalent, but with a modified interface, are prefixed with the "u" character. For more information see the appropriate information file and, if applicable, the Multics/UNIX Product Differences Guide. create_data_object_ (create_data_segment_) Used in conjunction with the cdo command to create an object file containing externally accessible data. The call to create_data_object_ from within a cdo program causes the object file to be created. uget_wdir_ (get_wdir_) Returns the absolute pathname of the user's current working directory. 12/13/90 3 Migration Guide Bull HN ulex_error_ (lex_error_) Generates compiler-style error messages to standard error for procedures that process tokens generated by the ulex_string_ subroutine. ulex_string_ (lex_string_) Provides a facility for parsing an ASCII character string into tokens (character strings delimited by break characters) and statements (groups of tokens). The entrypoints supported are ulex_string_ ulex_string_$init_lex_delims ulex_string_$lex upathname_ (pathname_) Contains an entry point for constructing given pathnames, a directory name and an entry name. uabsolute_pathname_ (absolute_pathname_) Converts a relative or absolute pathname into a full absolute pathname. The entrypoints supported are uabsolute_pathname_ uabsolute_pathname_$add_suffix uassign_ (assign_) Assigns a specified source value to a specified target. See the information file for the allowable data types. The entrypoints supported are uassign_ uassign_$computational_ uassign_$round_ uassign_$truncate_ uassign_$char_to_numeric_ ucom_err_ (com_err_) Is the principal subroutine used by commands for printing error messages. The entrypoints supported are ucom_err_ ucom_err_$suppress_name uconvert_date_to_binary_ (convert_date_to_binary_) Converts a character representation of a date and time into a 64-bit clock reading. The entrypoints supported are uconvert_date_to_binary_ uconvert_date_to_binary_$relative 4 12/13/90 Bull HN Migration Guide ucu_ (cu_) Contains a number of useful command utility programs that provide functions not directly available in the PL/I language. The entrypoints supported are ucu_$arg_count ucu_$cp ucu_$arg_count_rel ucu_$decode_entry_value ucu_$arg_list_ptr ucu_$gen_call ucu_$arg_ptr ucu_$generate_call ucu_$arg_ptr_rel ucu_$make_entry_value ucu_$caller_ptr ucu_$ptr_call udate_time_ (date_time_) Encodes, decodes, adjusts or formats a clock value which is represented in microseconds relative to 1901-01-01 0:00 gmt. Various languages and time zones are supported. The entrypoints supported are udate_time_ udate_time_$format udate_time_$format_max_length udate_time_$from_clock udate_time_$from_clock_interval udate_time_$fstime udate_time_$offset_to_clock udate_time_$set_lang udate_time_$set_zone udate_time_$to_clock udate_time_$valid_format udecode_descriptor_ (decode_descriptor_) Extracts information from argument descriptors. uexpand_pathname_ (expand_pathname_) Used to convert a relative or absolute pathname into a directory name and entryname. The entrypoints supported are uexpand_pathname_ uexpand_pathname_$add_suffix 12/13/90 5 Migration Guide Bull HN uioa_ (ioa_) Used for formatting a character string from fixed-point numbers, floating-point numbers, character strings, bit strings, and pointers. The character string is constructed according to the control characters entered in a "control string", and a variable list of arguments (that are either edited into the output string in character form, or are used in some way to control the formatting of the string). The supported entrypoints are uioa_ uioa_$rs uioa_$fd uioa_$rsnnl uioa_$fdnnl uioa_$rsnp uioa_$general_rs uioa_$rsnpnnl uioa_$nnl uiox_ (iox_) The uiox_ subroutine implements the Multics I/O system. The supported entrypoints are uiox_$attach_loud uiox_$look_switch uiox_$attach_name uiox_$modes uiox_$attach_switch uiox_$move_attach uiox_$close uiox_$open uiox_$close_file uiox_$open_file uiox_$control uiox_$position uiox_$delete_record uiox_$put_chars uiox_$destroy_switch uiox_$read_key uiox_$detach uiox_$read_length uiox_$detach_switch uiox_$read_record uiox_$find_switch uiox_$rewrite_record uiox_$get_chars uiox_$seek_key uiox_$get_line uiox_$switch_data uiox_$list_switches uiox_$write_record The following two routines are C routines that can be used to perform request loop handling: rq_loop Interactively queries the user until a request matches an entry in the provided table (or an empty line), and returns an index to the selected element. rq_error Prints an error message to standard error describing an error which is indicated by the external variable 'rqerrno'; the error message is specific to the request loop facility. 6 12/13/90 Bull HN Migration Guide The following four routines are C routines that can be used for manipulating and handling search rules/paths. These routines support the UNIX conventions for handling search rules/paths (which are based on the use of environment variables). sp_getpaths Creates a NULL terminated character string which contains the directory names (separated by ':' characters) in which a file with the supplied access can be found. The returned directory names will appear in the same order as specified in the environment variable. If duplicates are not requested, then only the first directory name containing the file will be returned. sp_parse Parses a search_path environment variable for pathnames, and returns a pointer to an allocated array of character string pointers (which are the individual search paths). sp_verify Verifies that the contents of an environment variable are syntactically correct pathnames. sp_error Prints an error message to standard error describing an error which is indicated by the external variable 'sperrno'; the error message is specific to the search path utilities. 1.3.3. I/O Modules This section lists the I/O modules available as part of the Migration Package. These I/O modules are accessible through uiox_. The Multics name is given in parentheses for those modules derived from a Multics equivalent. For more information see the appropriate information file and, if applicable, the Multics/UNIX Product Differences Guide. unix_io_ The unix_io_ I/O module supports stream I/O to and from I/O streams. It is not invoked directly, but via the uiox_ I/O system. vfile_ (vfile_) The vfile_ I/O module supports I/O to and from files in the UNIX storage system. The vfile_ I/O module is not invoked directly, but via the uiox_ I/O system. Blocked file types are not supported. 12/13/90 7 Migration Guide Bull HN 2. Communication Protocols There are two communications packages available on UNIX that allow you to dial out and connect to external systems: Kermit and cu(1). Kermit is a simple file transfer protocol that enables users to connect to and transfer files (either ASCII or binary) between various computer systems. cu is the UNIX connect utility that is used to connect to other UNIX machines and perform file transfers. If Kermit is not on your system see your Site Administrator. 2.1. Kermit Kermit lets you specify most internal field definitions to accommodate various machine dependencies. The field specification characters must not be the same value (i.e. the control prefix character cannot equal the end of packet character); they also must match between the remote and host systems (although Kermit will try to negotiate with the other system to settle on a group of field characters). The field settings for Kermit are as follows: _F_i_e_l_d _D_e_f_a_u_l_t _P_o_s_s_i_b_l_e _V_a_l_u_e_s control prefix # "!" through ">" or "`" through "~" eight bit prefix & "!" through ">" or "`" through "~" end of packet 015 SOH (001) through US (037) packet length 80 implementation dependent parity none none, mark, space, even, odd repeat prefix ~ "!" through ">" or "`" through "~" start of packet 001 SOH (001) through US (037) file type ASCII ASCII or binary Most implementations of Kermit have a "show" command which displays the current settings for the fields. 8 12/13/90 Bull HN Migration Guide 2.1.1. Examples of File Transfers This section presents examples of using Kermit to send ASCII and binary files. The examples are given in terms of connecting to a Multics system from a UNIX system, and transferring files from Multics to UNIX. The procedure may vary depending on the version of Kermit used, but in most cases newer versions of Kermit will work as described below. User input is prefixed by the character "!". Comments are preceded by the character "*". EXAMPLE 1: ASCII UNIX-prompt> !kermit C-kermit> !show Communications Parameters: Line: /dev/tty, speed -1, mode: remote, modem-dialer: direct Parity: none, duplex: full, flow: xon/xoff, handshake: none Protocol Parameters: Send Receive Timeout: 10 7 Padding: 0 0 Pad Character: 0 0 Packet Start: 001 001 Packet End: 013 013 Packet Length: 90 90 File Parameters: File Names: converted Debugging Log: none File Type: text Packet Log: none File Warning: off Session Log: none File Display: on Transaction Log: none C-Kermit> !set line /dev/tty15 * This is used to specify which line to use for the file transfer. * The line specified above is dependent on the specific system used; * check with your systems personnel for the line to be used. C-Kermit> !set speed 9600 * The line speed is dependent on the specific system used; check * with your systems personnel for the correct speed. C-Kermit> !connect 12/13/90 9 Migration Guide Bull HN * This will connect you to the remote system (Multics). Once * connected you will have to log on to the system and set the * Kermit settings. Welcome to the Multics System. Multics MR12.2: Multics Center (Channel e.h405) Load = 40.0 out of 50.0 units: users = 40, 04/26/89 1314.9 mdt Thur !l user_id project_id Password: !XXXXXXXXXXX Multics_ready> !kermit Multics-Kermit: !send file_name !^\C * ^\C is the escape sequence used to get back to the host * system. The ^\ sequence represents a control sequence. * (Press the control key and \ simultaneously, and then press C.) C-Kermit> receive * At this point Kermit will transfer the specified file to the * host system. C-Kermit> connect * This will get you back to the Multics system. Multics-Kermit: !quit Multics_ready> !logout EXAMPLE 2: binary C-Kermit> !set file type binary C-Kermit> !connect Welcome to the Multics System. Multics MR12.2: Multics Center (Channel e.h405) Load = 40.0 out of 50.0 units: users = 40, 04/26/89 1314.9 mdt Thur !l user_id project_id Password: XXXXXXXXXXX 10 12/13/90 Bull HN Migration Guide Multics_ready> !kermit Multics-Kermit: !set file_type binary Multics-Kermit: !send file_name !^\C C-Kermit> !connect Multics-Kermit: !q Multics_ready> !logout C-Kermit> !quit UNIX-ready> !logout 2.2. Connect to UNIX (cu) Because the cu command expects to find another UNIX system on the remote end, its file transfer facilities ("put" and "take") will not work with Multics. You can, however, use cu to connect to Multics and do file transfers by capturing output. For a complete description of the cu command see cu(1) in the UNIX manuals. 2.2.1. cu Connection Example: ASCII Below is an example of transferring a file from Multics to UNIX using cu. Note: User input is prefixed by the character "!". Comments are preceded by the character "*". * In order to perform file transfers, cu requires rw permission * to the user's tty. The command used to do this is "mesg y". UNIX-prompt> !mesg y UNIX-prompt> !chmod 777 target_file UNIX-prompt> !cu -l /dev/tty15 -s 9600 * The above command line specifies the line the connection is to * use and the line speed at which the line is to be set. To find * out what lines are available on your system contact your system * personnel. 12/13/90 11 Migration Guide Bull HN Welcome to the Multics System. Multics MR12.2: Multics Center (Channel e.h405) Load = 40.0 out of 50.0 units: users = 40, 04/26/89 1314.9 mdt Thur !l user_id project_id Password: !XXXXXXXXXXX * A simple ASCII file transfer is possible, however, extra * information is passed along with the transferred file so you * must edit it out of the target file. cu opens a pipe on the * UNIX system and dumps any information coming from Multics to * that file. cu requires rw access to the file being created, * so you will have to either create a file with access set to * 777 or set access of an existing file to 777. Multics-prompt> !~~>:target_file * The next two commands will not be seen by the user since the * output goes into the target_file. Multics-prompt> !pr source_file Multics-prompt> !~~> 10 lines/307 characters Multics-prompt> !logout UNIX-prompt> !logout You are now back at the UNIX system and the transferred source_file now exists there with the name target_file (which will look something like below). Using an editor, remove the extra information added to the file. The lines you want to remove are prefixed with the character "&". ------------------------------------------------------------------- &command_processor: Some directory in path specified does not exist. &>udd>project_id>person_id>~>:target_file &Multics-prompt> pr source_file & & & source_file 04/19/89 1148.4 mdt Mon Now comes the contents of the source file as would be shown by the Multics print command. &Multics-prompt> ------------------------------------------------------------------- 12 12/13/90 Bull HN Migration Guide 3. Multics and UNIX Differences An important factor which determines potentially how difficult the porting process might be is the degree of difference between the source and target systems. This includes differences in library or application support, differences in operating systems, and differences in hardware capabilities which may be used directly or indirectly by the operating system or in application support. There are a number of differences which often cause difficulties when porting Multics code to UNIX. System specific features affect not only the functionality that each system can provide, but also the conventions and considerations that are built into applications written for use on these systems. 3.1. Process Usage A major difference between Multics and UNIX is how processes are used during a login session. On Multics, only one process is active per login. Functionally, this process serves to encapsulate an environment for the duration of a login; thus, a significant amount of processing takes place in setting up the process. Once the process is initialized, commands or programs which are invoked by the user are then executed by the process. If one of these commands or programs is interrupted by the user (generating a quit signal), the current state of execution may be saved and the process will enter a new command level. The process has total control over the execution of programs so it is possible to resume execution or to begin execution of a new command. The fact that the same process will execute a number of different commands or programs means that it is relatively easy for one program to pass information to a subsequent one by placing the information in an accessible part of the process. On Multics, this location is the process directory (which is also where PL/I external/static variables are kept). The repeated use of the same process also implies that each program that is executed must be careful about not creating undesirable side-effects for subsequent programs; thus, Multics programs in general pay particular attention to cleanup. On UNIX, a process is created upon login to handle user commands. This first process is usually a UNIX shell program which interprets user commands and spawns other processes to execute each of the user commands or programs. The process has certain attributes or values which make up the environment and these values are initialized as part of the login process. When 12/13/90 13 Migration Guide Bull HN subsequent commands are invoked, the process is cloned and overlaid with the executable code of the command being invoked. This essentially creates a new process (with its own copy of the environment) that is the new command. Any changes to the created environment of the new process affect the new process' copy of the environment, so these changes are lost when the new process terminates. The original process is not affected. This process usage difference affects code that is to be ported. To begin with, those commands or programs which function to manipulate per process data on Multics may not behave the same on UNIX. For example, a Multics program could be written so that after execution completes, the user is placed in a particular part of the Multics hierarchy. On UNIX, after execution completes, the user's place in the hierarchy remains unchanged in the login process; this is because the current directory is per-process information and that information is changed only in the process newly created for the program, not in the login process. Similarly, search paths using environment variables can be changed but they affect only the current process. However, it may be possible to simulate the Multics behaviour in some cases by using PL/I shared static variables, which are effectively per-login information. Along similar lines is the use of external variables; the repository for data that is external to a program on Multics is the process, but on UNIX there is no such repository since the process goes away when the program terminates. Porting problems that are due to differences in process usage generally occur because applications need to access external or static data. On UNIX, since a process terminates along with the program, such data must be external to a process. Hence, external or static variables are generally kept in entities which are globally accessible by processes: primarily files, shared memory, or other processes. This, however, brings up the need for concurrency considerations, as the possibility of more than one process accessing these global entities arises. A less important consequence of process usage differences is that some of the cleanup or condition handling that is required on Multics has little or no meaning on UNIX. For instance, a program on Multics may be interrupted and the suspended state of the program kept around. While in its interrupted state, it may have to allow itself to be invoked again with a suspended invocation of itself. Multics applications tend to be designed and coded with this in mind. On UNIX, however, applications generally cannot be resumed once they have been interrupted. In addition, cleanup is not as critical on UNIX for most things 14 12/13/90 Bull HN Migration Guide since processes are usually not restarted and the next application, therefore, will not pick up side-effects from previous programs. Also, storage allocated from the process' data space (for example, via malloc(3C)) is released when the process terminates, so explicit freeing of such storage is not essential. 3.2. Command Line Processing The Multics command processor and UNIX shells are roughly analogous to each other as both serve as interfaces between the user and the command line; however, they process command lines according to different conventions. Rather than describe the differences between the various UNIX shells and the Multics command processor, it is sufficient to warn of some common actions taken by UNIX shells on command lines. (Refer to the User Reference Manual for descriptions about the standard UNIX shells sh and csh). First, many special characters that are passed uninterpreted by the Multics command processor to Multics programs have special meanings to UNIX shell programs. These characters would cause UNIX shells to perform special command line processing, unless the special characters were enclosed in quotes. Such special characters include *, $, >, <, and |. (The exact set depends on the particular shell being used). If the Multics application being ported supports use of Multics conventions such as star names, equal names, etc., it may be worth considering removing that functionality and using the UNIX conventions. This may be desirable since the inconvenience of having to enclose star names in quotes is eliminated, and routines for handling these conventions possibly would not need to be ported or rewritten. (Or it may be possible to retain the command processing characteristics of Multics by writing a shell program to emulate the Multics command processor.) 12/13/90 15 Migration Guide Bull HN 3.3. Handling Special Characters in Filenames There are differences in the way that special characters (such as "*" or "?") in filenames are handled. On Multics, such names are passed directly to a program which then makes certain library calls to select files that match the given names. On UNIX, unless quoting is done, arguments containing certain special characters are assumed to be file names and, as such, files which match the wildcard arguments replace that argument before they are passed to the program. A second difference is that UNIX does not separate names into a suffix and prefix. The name abc.d is not made up of the name "abc" and the suffix "d"; its name is the string "abc.d". On Multics there is a separation implied in file names; this allows you to do things such as "dl *" which will remove only those files that have no suffix appended to their name. On UNIX the same command "rm *" will remove all of the existing files in the current working directory. 16 12/13/90 Bull HN Migration Guide 3.4. Equivalent Commands There are a number of Multics commands that each have an equivalent on UNIX: _M_u_l_t_i_c_s _U_N_I_X change_wdir cd copy cp compare_ascii diff create_dir mkdir date,time date delete rm delete_dir rmdir dial_out cu enter_absentee_request at emacs emacs (not standard with UNIX but widely available) forum readnews get_quota du, df login -change_password passwd link ln list ls login login logout exit, logout (shell dependent) move mv print pr, cat, more print_wdir pwd probe sdb qedx ed read_mail mail send_mail mail send_message write set_acl chgrp, chmod set_tty stty who who 3.5. Active Function Handling Many Multics commands can be used as active functions. This allows for the output of a command to be used as part of the command line. On Multics this requires that certain system calls (which detect that the program is being used as an active function) be used from within a program. Also required are system calls to define the output being passed back to the command line; these system calls are closely tied to the command processor software. 12/13/90 17 Migration Guide Bull HN Since the UNIX user will be expected to use the standard UNIX shells, there will be no standard support for active function usage by a program. A UNIX shell does provide support for something similar to active functions, but this does not require explicit handling by programs. (When back quote characters are used around a command on the command line, this string is replaced by the results of the output of that command or program.) Thus, during the porting process, code that specifically supports usage as a Multics active function should be removed. 3.6. Dynamic Linking vs. Static Linking Dynamic linking is a feature supported by Multics that allows external references to be resolved at runtime when the reference is actually made. Thus, if program A calls an external subroutine B, program A looks for subroutine B only when subroutine B gets called. This feature is not supported by UNIX. On UNIX, before a program can be executed, an executable file must be created from the compiled object files. This action is performed by the UNIX link editor and, during this process of static linking, all references are resolved before the executable file is created. If references cannot be resolved the executable file cannot be created. Thus, only "complete" programs normally can be executed; UNIX does not provide a mechanism to directly execute a particular subroutine in an executable file other than from its use in the course of running the entire program. The binder on Multics performs a task similar to the UNIX link editor in that it collects object segments and resolves references that are used between them. However, the binder does not require all references to be resolved, as is the case with the UNIX link editor, so that external references can still be made from within the bound segment. This linking difference means that it is difficult to work around cases where dynamic linking is explicitly used; therefore, it is necessary that use of dynamic linking be identified before porting a program. Explicit use of dynamic linking is usually indicated by calls to Multics routines such as cv_entry_ or cv_ptr_, but it is also possible to examine an object segment (given a pointer to the segment) and derive the entrypoint manually. Dynamic linking is used implicitly on Multics when external references are made by compiler generated code. In these cases, static linking would generally result in no differences in program functionality on the two systems. 18 12/13/90 Bull HN Migration Guide 3.7. File Systems There are significant differences between the file systems of the two operating systems. However, basic file system structures are similar in that both are composed of tree-structured hierarchies containing directories, subdirectories, and entries. Entries that are common to both are files, directories and links. File names on Multics can be (and often are) descriptive and can support descriptive suffixes. To balance the use of long and descriptive names (on Multics) with the inconvenience of typing them in, additional names can be assigned to the same file. These "add names" are generally short for the sake of convenience; there is nothing equivalent to "add names" on UNIX. A more important difference between the file systems is that Multics files are based on segments and, as such, have different properties from files on UNIX. In particular, a segment has a specific size limit and is entirely addressable by a program. As far as a program is concerned, a segment is a contiguous piece of memory; therefore, modifications to this memory immediately become modifications to the segment. This ability to map a file to a part of memory is called memory-mapped I/O. UNIX files cannot be accessed in this manner; generally, buffered I/O is performed instead. Applications that rely on memory-mapped I/O may require some code restructuring or workarounds. Many standard Multics subroutines rely on memory-mapped I/O as well: in particular, commonly used area management routines such as define_area_() and get_temp_segment_(). One way of resolving the memory-mapped I/O problem is to substitute the initiation of a file with the allocation of a memory block in the user heap space (e.g. using the UNIX allocation routine malloc()), and to read the entire file into memory. The pointer to the memory block can then be used in place of the pointer to a segment. A drawback to this method is that changes made to the memory block are not reflected in the file until the contents of the buffer are flushed back to the file. This sometimes causes failure, for example, in schemes where file locking information is kept within a segment, since only a copy of the lock is used. There also may be system imposed limits on the amount of memory that can be dynamically allocated by a process. These limits may affect the size or the number of the memory blocks that can be obtained. Applications that initiate files do not necessarily terminate them, so it may be necessary to determine when code is needed to update the file, and then where in the code flushing is required. 12/13/90 19 Migration Guide Bull HN Another method of handling memory-mapped I/O is to use shared memory instead of memory allocated from the user's heap space. Shared memory has the attributes of a Multics segment more so than does memory allocated from the process heap space. This is because shared memory isn't freed when the process that allocates it terminates, and because it can be accessed by different processes. However, more work is required to set up and keep track of shared memory. Also, system and process limitations may restrict how much shared memory can be used, and shared memory does not have the permanency of files. Although the methods described work in many cases, they may not work in others so, as a last resort, the code may need to be modified so it does not use memory-mapped I/O. This may be necessary (and in many instances not be too difficult) in cases where system limits prove to be too restrictive. Such solutions require that buffered I/O be used, where only a part of a file is read in and processed at a time. For example, if an application stores an array of structures in a file, it may be possible to read in only the structure that is needed and then write the structure back out before processing the next. The use of UNIX routines like lseek() will be useful in such cases to perform file positioning. This method will result in slower processing, but the use of bigger buffers (or a greater number of buffers) can be used to minimize this deficiency. Another file system difference is the existence of multi-segment files and extended entries on Multics; these have no equivalents on UNIX. A multi-segment file is a way of having a file larger than a single segment on Multics. This is not necessary on UNIX since UNIX files are not based on segments. Multics also has extended entries such as mailboxes or message segments which have no equivalents on UNIX. Such extended entries are manipulated by Multics-specific facilities which don't exist on UNIX. This means that code which specifically handles multi-segment files and extended entries would need to be removed. There are also many differences in the information that is kept about entries by each system. This is summarized in the following lists: 20 12/13/90 Bull HN Migration Guide Information associated with file system entries on Multics: access control list (ACL) author bit count bit count author complete volume dump switch copy switch current length (in pages) damaged switch date/time dumped date/time contents modified date/time entry modified date/time used date/time volume dumped dnzp switch (don't null zero pages) entry point bound incremental volume dump switch initial access control lists logical volume identifier master directory switch maximum length multisegment file indicator names quota records used ring brackets safety switch security out-of-service switch type unique identifier use count Information associated with file system entries on UNIX: name inode number mode and type number of links to the file owner user id owner group id length in bytes disk block addresses time last accessed time last modified time of last file status change 12/13/90 21 Migration Guide Bull HN File System Entry Information: The following table shows the Multics entry information and the UNIX entry information which is either directly or partially equivalent. Note: The UNIX info is available through the routines stat() and fstat(). _M_u_l_t_i_c_s _U_N_I_X _E_q_u_i_v_a_l_e_n_t names name type mode and type ACLs date/time contents modified time last modified date/time entry used time last accessed author owner user id owner group id current length length in bytes bitcount unique identifier inode and filesystem identifier Applications that need Multics entry information for which there is no UNIX equivalent will be difficult to port. Since ring brackets have no equivalent on UNIX, applications which must rely on the ring protection mechanism cannot be directly supported on UNIX. The use of ring brackets need not show up explicitly as part of the code anyway, because security information is kept by the operating system. Also, the file modes on UNIX correspond only roughly to the access control list on Multics. On Multics, access can be given or denied to a particular individual, whereas this is not possible on UNIX. UNIX requires that in order to access a file in a particular directory, all directories in the path must be accessible. Applications that rely on access mechanisms will need to account for these differences. 22 12/13/90 Bull HN Migration Guide 3.8. Time Clock Values Another difference worth noting is that of clock values. Clock values on Multics (e.g. generated by clock_ or the PL/I clock builtin) are values which represent time in microsecond resolution. The standard clock value on UNIX represents time to the resolution of seconds. This difference usually doesn't present too much of a problem except when the clock values are used as unique time stamps or for generating unique values; then the resolution on UNIX is not small enough and alternate methods are required. Similarly, the vclock builtin on UNIX does not represent time to the resolution of microseconds but rather to 1/60 of a second. (Units for process usage times are based on the value of the environment variable HZ.) 3.9. UNIX Limits Some of the limits imposed by UNIX may present problems in porting Multics programs. There is a limit on the number of files that can be opened at a time by a UNIX process. Thus, applications which require more than this limit may need to be modified. Solutions to this involve using fewer files, closing those files that are not immediately necessary (opening each again as necessary), or using more processes (but this requires more overhead in the interprocess-communications set-up). There is also a limit on the number of processes that a user can have running at a time, and there are limits on the size of files and process sizes (i.e. the amount of memory that can be accessed by a process). The file and process size limits can be obtained through calls to the UNIX function ulimit(). Note that these limits may vary depending on the configuration of the particular UNIX system. 3.10. Multics Exec_Coms vs UNIX Shell Scripts The UNIX shell scripts are programmable languages in the same manner as Multics exec_coms are programmable. The shell interfaces available on UNIX are C shell, the Korn shell and the Bourne shell. C shell has some constructs that are extensions to the Bourne shell. The Korn shell is a super-Bourne shell that combines the Bourne shell and C shell. (For the sake of simplicity, discussion is in terms of the Bourne shell only.) 12/13/90 23 Migration Guide Bull HN Note that a major difference between UNIX and Multics is that UNIX splits its command executions (thus shell scripts) into physically separate tasks, whereas on Multics the execution of commands (thus exec_coms) is done as subroutine calls. The following table compares the functionality of Multics exec_coms to the functionality of UNIX shell scripts. _F_u_n_c_t_i_o_n _M_u_l_t_i_c_s _E_x_e_c_-_C_o_m_s _B_o_u_r_n_e _S_h_e_l_l Parameter References &1..&n $1..$n &q1..&qn \"$n\" &r1..&rn \"\"$n\"\" &f(1)..&f(n) $* &qf(1)..&qf(n) $@ &rf(1)..&rf(n) $@ &n $# Builtin Values &cond_info_ptr no equivalent &cond_name exit status &ec_dir no equivalent &ec_name $0 &ec_path $0 &ec_switch no equivalent &handlers no equivalent Variables &(NAME) $NAME or ${NAME} &(N) $N &q(NAME) \"$NAME\" &[active function] `command` 24 12/13/90 Bull HN Migration Guide Literals &".." '..' && \& & \& &SP ' ' &BS \BS &HT \HT &VT \VT &FF \FF &NL echo \n &QT \" & tmpname Predicates &is_defined ${var:-string} &is_absin no equivalent &is_af no equivalent &is_attached no equivalent &is_input_line no equivalent &was_attached no equivalent Control Statements &attach pipes/redirection &detach no meaning &if if statement &goto no equivalent &label no equivalent &quit exit &return no equivalent Assignment Statements &set VAR=value &default ${var:-string} Printing Statements &print echo &print_nnl echo \\c Condition Handling &on trap &revert trap &signal kill &exit &continue break, continue Tracing Statements &lsv echo &ready not necessary &trace command options 12/13/90 25 Migration Guide Bull HN For UNIX, some of the above functions will have to be written (using system defined support routines) in order to obtain the same effect generated by Multics exec_coms. These functions can then be used within the back quote character to return the result written to the standard output. 26 12/13/90 Bull HN Migration Guide 4. Porting Applications Before any porting is performed, an understanding of the UNIX environment and the tools available in the Migration Package is necessary. Also useful is some knowledge of the C programming language, as most of the programming interface to the UNIX system is through C library routines. 4.1. Analysis The factors which determine the effort needed to port an application are different for every piece of software. It is possible that a 20,000 line program ports easily while a 10 line program ports with extreme difficulty. This is why it is recommended that each application be analyzed. Key factors in determining the effort are the amount and type of functionality that is external to the program; somehow this functionality will need to be replaced on UNIX. The particular type of functionality is also important because if there are no UNIX equivalents, porting may be very difficult. Thus, we need to know the extent and type of external support required through some sort of analysis. From that information, we can then answer the following questions: ox Is it possible to port? Is some functionality that cannot be supplied on UNIX needed? ox How much effort is required? Is it worth the trouble of trying to port as opposed to rewriting some of the functionality? ox What options are available? Is there needed functionality that can be obtained elsewhere? During the analysis phase, it is generally best to first determine those things which will present the greatest difficulties, as these immediately may give an idea of the magnitude of the porting effort. Non-PL/I programs or routines will need to be rewritten in PL/I (or even in C) in order to port them. We then must determine the external support that is needed. (External support includes external variables, subroutine entries, data segments, data files, I/O modules, etc.) In the case of external variables, subroutine entries and data segment values, one convenient source 12/13/90 27 Migration Guide Bull HN of information is an examination of the compiled object segments. If the Multics PL/I compiler was used to compile the code, then the object segments will have a standard format. In particular, there is an area in the object segment, called the linkage section, from which information about external references (external data and external routines) can be obtained. Where the object segments are bound, a linkage section still will be present and will contain information about external references outside the bound unit. Once we know what external support is needed, we should have some idea of the effort required to port. If no external support is needed, porting should be straight forward and no further analysis should be required. Otherwise, we want to determine 1) How much support needs to be written: If a program makes extensive use of Multics subroutines, these subroutines may need to be written or ported. 2) What the problem areas are: Subroutines which indicate the use of Multics-specific features (e.g. ring brackets, ACLs, etc.) may cause difficulties. 3) What types of conversions are required: For example, the use of initiate_file_ indicates the possible use of memory-mapped I/O, so workarounds may be needed. To determine how much support needs to be written, we take the list of externally supported items needed and check that against a list of supported items (those that already have been implemented or ported). If there are external items that still need to be supported, then we are at a stage where new support has to be written or ported. At this stage, certain considerations should be reviewed. 4.1.1. Conversion Considerations Since there are many ways to get a piece of Multics software to work on UNIX, there are many decisions that need to be made. The decisions are largely dependent on the strategy that is employed in the porting process: 1) Do I want to keep Multics conventions and features or do I want to adopt UNIX conventions and features? 28 12/13/90 Bull HN Migration Guide 2) Should the new support be written in a manner in which it is usable by other applications, or should it be written as quickly and inexpensively as possible? The former strategy implies additional effort will be required in writing some interface or wrapper, so that other applications can use this support with minimal modifications to the source. The appropriate choice will depend on how frequently this particular support would be used. 3) What functionality can or should be changed? When support needs to be written or ported, this is a convenient time to decide whether such support is even necessary. Some reasons why a particular functionality may not be necessary: ox Supports Multics conventions (e.g. Multics star name conventions) and we wish to use UNIX conventions (e.g. UNIX star name conventions). ox Performs a function which is necessary or applicable only on Multics (e.g. adjusting bit counts). ox Performs a task which is not essential to the functionality of the program. 4) Where will the functionality come from? At this point, we must look at the remaining support to determine how we are going to obtain the needed functionality. There are several possibilities: ox Port over the functionality. Porting over support is viable only if it in turn does not require additional support which cannot be obtained. The effort needed to port over the support may be too costly. However, porting over support means that future effort may not be required for applications ported later. ox Use UNIX functionality. Using UNIX functionality, where possible, is probably the most cost-effective alternative in many cases. Support which interfaces applications to the operating system (such as accessing the file system, accessing system timers, administrative information, etc.) will require direct or indirect use of UNIX functionality; this will be possible where the functionality has a UNIX equivalent. More about using UNIX functionality is described later. 12/13/90 29 Migration Guide Bull HN ox Rewrite the functionality. Where necessary, support might be rewritten. When the code is not PL/I code and does not have a particular dependence on the specifics of the operating system (e.g. a hashing routine written in ALM), rewriting may be necessary. ox Redesign/Recode. As a last resort, redesign/recode to bypass the use of a particular support routine. Obviously, this could be a very expensive process, depending on what needs to be recoded. This option may be necessary, for example, when a Multics application uses memory-mapped I/O. UNIX functionality: As mentioned previously, using UNIX functionality is usually the most cost-effective and sometimes the only source of needed support. The support is normally available as library routines for C code. (UNIX is based on C, like Multics is based on PL/I.) The PL/I compiler has an extension to permit C code to be called by PL/I programs, making it possible to use the support provided by UNIX. This approach requires an understanding of the UNIX routines, and some knowledge of C and how parameters and parameter types are passed between the two languages. Modifications to the source are often needed to accommodate the use of UNIX routines. The following table presents some examples of Multics subroutines for which UNIX subroutines may provide equivalent support or functionality. | Multics UNIX _______________|________________________________ | File system | hcs_$status_minf stat | fstat | Video | window_ CURSES | ttt_info_ TERMINFO | Timers | timer_manager_ sleep | alarm 30 12/13/90 Bull HN Migration Guide 4.2. Procedures Once the analysis has been completed, and the decision has been made to port the code, there are standard adjustments and checks required for the PL/I source code. 4.2.1. Standard PL/I Conversions Revising subroutine names: Many of the Multics subroutines which have been ported to UNIX have been renamed to indicate differences (e.g. parameter type sizes). For example, ioa_ entries now become uioa_ entries (with the "u" prefix indicating UNIX). Thus, changes will be required to the PL/I source code where the converted routines are referenced. Some of the migration runtime libraries contain externally accessible variables and routines which are intended only for internal use by the migration software. These routines are prefixed by underscores to avoid conflicts with applications in the use of identifier names. Therefore, identifier names prefixed by underscores should be avoided in applications. Redeclarations: Since the parameters of some of the converted Multics subroutines (included in the Migration Package) have been changed, the declarations of the associated entries need to be updated in the source. Variables which are passed as parameters to these entries also may need to be redeclared. In addition, error table values are now 32 bit values instead of 36 bit values, so their declarations need to be changed from "fixed bin (35) external" to "fixed bin(31) external". Updating pathnames: As pathnames are represented differently on Multics and UNIX, it will be necessary to convert Multics paths to UNIX paths. First determine to where in the UNIX hierarchy the Multics path maps. For example, ">udd>Multics>Lee" might map to "/usr/lee" on UNIX. 12/13/90 31 Migration Guide Bull HN Having determined equivalent locations in the UNIX hierarchy, translations of ">" into "/", "<" into "../", etc. are needed to convert the pathname syntax. This is a fairly simple process if the entire path is represented as a string such as ">udd>Multics>Lee". However, where pathnames are constructed, correcting the pathname may be trickier. See the code fragments below: stringA = ">udd>Multics>Lee>fileX"; /* easy to detect */ stringB = stringC || ">" || stringD; /* is this a pathname? */ Updating file names and file name references: On Multics, a name containing a "$" character such as "xxx_$yyy" identifies a segment with a reference name "xxx_" and an entry into the segment with the entrypoint name "yyy". Under UNIX PL/I, the "$" has no special meaning and "xxx_$yyy" is just an ordinary symbol name. Thus, the entrypoint "xxx_$yyy" need not necessarily be defined in a file called "xxx_". This implies that an entrypoint name needs to be fully qualified with the name of the procedure in which it was declared. Thus, if an entry with a label of "ep" was declared in the procedure "x_", the entry name should be changed to "x_$ep". Identifying the main procedure: The main procedure which must have the label "main" must be identified. This is required because execution will begin at the label "main", regardless of the name of the executable file. Note that this applies to the main procedure in cdo source files as well. 4.2.2. create_data_segment (cds) Files As mentioned before, there is currently no facility to directly translate a Multics cds file for use on UNIX. However, there is a facility called cdo (create_data_object) which serves the same purpose of creating the equivalent data values which are usable on UNIX. cdo differs from cds in that an object file is produced; this object file is suitable for linking with other object files on UNIX (the output is in UNIX Common Object File Format, i.e. COFF format). 32 12/13/90 Bull HN Migration Guide Source code should be adjusted to replace the create_data_segment_ calls present in the create_data_segment source with calls to the create_data_object_ routine. The structures for passing information to the create_data_segment_ and create_data_object_ routines differ so the include macro "%include cds_args;" should be replaced with "%include cdo_item;". The structures also need to be filled with different information. (See the online info file "cdo.i" for more information.) 4.2.3. create_error_table (cet) Conversions of create_error_table source files (which are Multics ALM error table segments) are straight forward. The command is invoked with the source file as an argument, and an object file is produced. This object file can then be linked with the rest of the application's object files. 4.2.4. Reduction Compiler (rdc) Source Since the reduction source is basically PL/I, conversions which apply to PL/I code also apply to reduction compiler code (e.g. subroutine names may need to be changed and redeclared along with parameters which have changed, include file names may need to be renamed to their UNIX versions, etc.). The parsing code generated is then compiled using the PL/I compiler; this produces an object file which can then be linked with the rest of the application's object files. 4.2.5. Using the SDB Debugger SDB, the UNIX symbolic debugger, can be used to help debug PL/I programs; however, since PL/I is fundamentally different from any other language available under UNIX, there are some problem areas. Only a subset of a program's PL/I datatypes can be accessed by SDB. PL/I variables must be aligned and map to a C datatype in order to be accessed. The following PL/I datatypes can be accessed: 12/13/90 33 Migration Guide Bull HN aligned pointer options (packed) aligned fixed bin (1-31) aligned float bin (1-53) SDB cannot access automatics (which have been declared outside the procedure being examined), parameters, based variables or members of a PL/I structure or array. SDB cannot trace past PL/I condition frames. SDB can be very useful for setting breakpoints in UNIX PL/I code. It can access the PL/I source code and set breakpoints within the source, except for a few rare occasions. When a procedure contains automatic initialization and multiple entrypoints, the PL/I compiler will generate code which SDB will find out of order, preventing a breakpoint from being set on the line. To assist in debugging source code with SDB, it is recommended that the source be compiled non-optimized with no quick blocks and that condition handlers be temporarily commented out. 34 12/13/90 Bull HN Migration Guide 5. Administration 5.1. Accounting The DPX/2 UNIX accounting facility gathers only some of the accounting information gathered by Multics. On Multics, this information is accumulated and used in real time without the need for administrator intervention (e.g. accounts are locked when funds run out). This is not so for the DPX/2 UNIX which requires that the system administrator invoke programs to gather this information. However, tools are available on UNIX for displaying the accounting information in a useful manner, and shell scripts or programs can be written to achieve automation. For a complete description of the available UNIX accounting facility see the section on accounting in the UNIX System V Administrator Guide (and also look at the associated commands in the guide). 5.1.1. Accounting Hierarchy The DPX/2 UNIX accounting facility is kept under the hierarchy "/usr/adm". Shell scripts and programs written to extend it can be kept in a subdirectory named "acct". The accounting data is kept in subdirectories of "acct" named "nite", "sum" and "fiscal". Active data is kept in "/usr/adm". 12/13/90 35 Migration Guide Bull HN 5.1.2. Accounting Information The data or information generated and saved by the accounting facility is fairly basic. It is gathered in terms of user logins, lines, or specific commands used throughout the system. "User Login Information" CPU MIN The amount of time a user's process used the CPU. This is divided into PRIME time and NPRIME time. (PRIME time default is 9:00 to 17:00). KCORE MIN The memory used by a process while running. This reflects kilobyte segments used per minute. This measurement is also given in terms of NPRIME and PRIME times. CONNECT MIN The actual connect time the user was connected to the system, divided into PRIME and NPRIME times. DISK BLOCKS The number of blocks associated with the defined user. # OF PROCS The number of processes executed by the user. # OF SESS The number of times the user logged in. "Line Information" LINE The line id (e.g. /dev/tty14). MINUTES The amount of time (in minutes) the line was used. PERCENT The percentage of time the line was used. # SESS The number of times a login occurred on the line. # OFF The number of times interrupts and log offs occurred on the line. 36 12/13/90 Bull HN Migration Guide "Command Information" NUMBER CMDS The number of times the command was executed. TOTAL KCOREMIN The total amount of kilobyte segments of memory used per minute of execution time. TOTAL CPU-MIN The total CPU time used by this program. TOTAL REAL-MIN The wall clock minutes used during the execution of this program. MEAN SIZE-K The mean KCOREMIN used by the command. MEAN CPU-MIN The average CPU time used by the command. HOG FACTOR The weight of the command in terms of total system time available versus the time this command actually used. TRNSFD The number of bytes sent to the "read" and "write" system calls. BLOCK READ The total physical block reads and writes done during the execution of the command. Use of the above information is left up to the procedures employed by the System Administrator. 5.2. Security Multics is world renowned for its security structure. In addition to its default structure, it allows the user to set and deny access to specific users and projects. The security of UNIX, on the other hand, is solely dependent on the administrative control of its users. Unless access is set directly, the default access of UNIX leaves the potential for many holes in security. 12/13/90 37 Migration Guide Bull HN 5.2.1. Accesses The access mechanism which applies to files and directories allows permission to be specified for each of three categories of users: 1) the owner of the file 2) users belonging to the file's group and 3) any other user. When users are registered on a UNIX system they are assigned one or more group identifiers, just as on Multics where they are assigned a project identifier. The known groups on a UNIX system are kept in the file /etc/group. Users may belong to more than one group within their login identifier, but usually have only one login identifier with which they are associated. The user identifier and associated information is kept in the file /etc/passwd. UNIX access can be specified by an octal number where numerical positioning represents accesses possible for owner, group and others. The value of a specific access is the sum of the component accesses: read, write and execute (where execute = 1, write = 2 and read = 4). Example: 07000 represents "special access" permissions (see below). 00700 represents access for the owner of the file or directory. 00070 represents access for the group associated with the file or directory. 00007 represents access for everybody else on the system for the file or directory. For further information on access, refer to chmod(1) in the UNIX manuals. Special Access A group of special accesses on UNIX can be associated with specific files. These accesses can change the user identification or group identification when the file is executed. A file set with these privileges (accesses) has the following values for the special access field: 2 Changes the user's group identifier to the file's group id on execution. 4 Changes the user's user identifier to the file's user identifier on execution. The above accesses can be altered by the setuid(2) and setgid(2) routines. 38 12/13/90 Bull HN Migration Guide File Access The file accesses on UNIX are 1 Execute Access If set the user can execute the file. 2 Write Access If set the user can write to the file. 4 Read Access. If set the user can read the file. Directory Access The directory accesses on UNIX are 1 Execute Access If set allows the user to use the directory as part of a pathname. 2 Write Access If set allows the user to modify files within a directory (i.e. remove, add, or modify files). 4 Read Access If set allows the user to read the contents of a directory. Default Access Most commands on UNIX set the default access to global read, write and execute for all files and directories. It is therefore suggested that the "umask" shell command (see sh(1) or csh(1)) be used in the startup to set default access to 700. This will give read, write and execute access only to the creator of files and directories, similar to the Multics default. On UNIX there is a special user who has global access rights to everything on the system: the Super User. This user, who can bypass any set security structure, is usually responsible for system maintenance and administration. The Super User account should not be used to perform basic functions such as accounting and library maintenance. There are other accounts available for this (such as adm,lib). Obviously it is wise to keep the password of the Super User as private as possible. 12/13/90 39 Migration Guide Bull HN tty_ Access A possible problem area for UNIX users is the access set to the login tty device. The default access to the tty is dependent on the version of UNIX being used. If this access is set to 777, it allows anyone to look at or modify information entered on the user's tty device. It is suggested that the "mesg n" (see mesg (1)) command be used in the startup to alter this default access to 600, which sets read and write access to the user logged in on that device. 5.2.2. Password Protection Both Multics and UNIX allow users to specify a password to their login identifiers (see passwd(1)4). On UNIX, the password file must have read access set to everyone on the system; the password field within this file is encrypted. 5.2.3. Suggested Security Checks To protect them from major security breaches, users should use the following as a check list of what to look for in terms of UNIX security. 40 12/13/90 Bull HN Migration Guide Directories Access to all root directories should be checked. Users require the following access rights to the following directories and any exceptions to this should be thought through carefully. _A_c_c_e_s_s _D_i_r_e_c_t_o_r_y _P_u_r_p_o_s_e _R_i_g_h_t_s / root directory) primary file 755 system base /bin executables required to boot 755 or rebuild the system /lib libraries required to rebuild 755 the system /etc administrative information 755 required during boot, and configuration information /unix operating system image 700 /dev devices required during boot; 755 usually contains all devices /usr auxiliary file system not 755 required during boot /usr/bin executables not required during 755 boot /usr/lib libraries not required during 755 boot (e.g. libc.archive) /usr/adm accounting information 750 /usr/man online documentation 755 /usr/doc online documentation 755 Setuid Programs All programs that have the setuid flag set, and are owned by root or other privileged accounts, should be checked to insure they are not malicious. A simple way of finding the files that use the setuid flag is to use the df command to list the devices specified on the system, and then use the ncheck program on all of the raw devices to find the files that use the setuid flag. For example, use the following ncheck command for all of the raw devices on the system: df ncheck -s raw_device_name > output_file 12/13/90 41 Migration Guide Bull HN This will generate a list of all of the files which use the setuid flag. Each file will then have to be checked for its ownership (using ls -l). The access rights of any files which are owned by root, daemon, and adm (or any other privileged account) should be checked manually. File Accesses Check to be sure the following files have the accesses listed below: _F_i_l_e _N_a_m_e _A_c_c_e_s_s /etc/passwd 644 disk devices 700 tty devices default access can be set by the user using the "mesg" command tape devices system dependent 42 12/13/90 Bull HN Migration Guide 6. Appendices 6.1. Appendix A: Getting Started This appendix gives instructions for quickly getting started using the Migration Package facilities. This includes setting up the UNIX environment, setting up the Migration help facility (for obtaining online help), and a sample session of getting a simple Multics PL/I program to compile and run on UNIX. 6.1.1. Initial Setup To use the Migration Package facilities, first the UNIX environment must be set up. 1) Search Rules To use the Migration Package tools, you will need to set up your UNIX search rules so that the migration tools directory is searched. This is done by setting the value of the environment variable named PATH. Whenever a command is entered on the command line, each directory (separated by a ":" character) is searched left to right until the command is found. If the default migration tools directory is not in the search rules, the following commands can be used to add it to the search rules: Using Bourne shell: PATH=/usr/lbin:$PATH; export PATH Using C shell: setenv PATH /usr/lbin:$PATH If you do not know which of these shells you are using, enter the following command line: grep "^`logname`:" /etc/passwd This will display your entry in the password file (which is a line containing fields separated by ":" characters). The rightmost field will indicate the path of your login shell. "/bin/sh" indicates the Bourne shell while "/bin/csh" indicates C shell. 12/13/90 43 Migration Guide Bull HN 2) Help Search Path The migration help facility examines the HELP_PATH environment variable to determine which directories are to be searched when help is invoked. A default migration info directory is used when this variable is not set. If info files that are not contained in the default migration info directory are required, the HELP_PATH environment variable should be set to include the containing directories in addition to the default help system directory. The following commands cause the default migration info directory and the example user directory "/user/joe/info" to be searched: Using Bourne shell: HELP_PATH=/usr/local/info:/user/joe/info; export HELP_PATH Using C shell: setenv HELP_PATH /usr/local/info:/user/joe/info 3) Translator Search Path The PL/I facility looks at the translator environment variable to determine in which directories to look for include files. The following commands cause the user's current directory, as well as the default migration include directory, to be searched when an include file is encountered: Using Bourne shell: translator=.:/usr/include/multics; export translator Using C shell: setenv translator .:/usr/include/multics 4) Verification At this point, the user should be able to access the migration tools. For example, entering the command "list_help migration" should result in "migration.g.i" being displayed. If this is not the case, the tools might be set up in directories other than the default, and the system administrator should be consulted in order to obtain the installed paths. Users may wish to consider placing the above commands in their .login start up (if using C shell) or .profile start up file (if using Bourne shell) to have the setup done automatically upon login. 44 12/13/90 Bull HN Migration Guide 6.1.2. Getting Help Before proceeding, the user should read the file migration.g.i which outlines some useful information about the Migration Package. This file should reflect any changes made by the site administrator to the location of the Migration Package facilities on the system, so it should be read first. The file can be read through the migration help facility (which behaves and looks like Multics help) by entering the command "help migration.g". A list_help facility exists for listing available help topics for a particular subject. The command "list_help -a" will list all the help topics available. (Enter the command "help list_help" for further information on list_help). Note that UNIX also has a command called help which is used in conjunction with the SCCS package (the UNIX system help). The setup described above causes the migration help to be invoked when "help" is entered as a command. If you need to use the system help, change your search rules to put the migration directory at the end. Links, shell scripts or aliases (if using C shell) can be used to access either help facility through another name. 6.1.3. Sample Session The following outlines the process of getting an application from Multics running on the DPX/2. For the purposes of this example, a simple PL/I program is used. (Issues related to the porting of a more complex program are described in other sections of this guide.) Suppose there is a PL/I program on Multics, called count_arguments.pl1, that simply displays the number of arguments passed to it. It is composed of the following lines: count_arguments: proc; dcl ioa_ entry options(variable); dcl cu_$arg_count entry (fixed bin, fixed bin(35)); dcl arg_count fixed bin; call cu_$arg_count(arg_count,(0)); call ioa_ ("Passed ^d args", arg_count); end; 12/13/90 45 Migration Guide Bull HN The steps needed to get this program running on the DPX/2 are as follows. 1) Rename file names When this file is transferred from Multics to the DPX/2, its name on the DPX/2 must conform to UNIX conventions. The .pl1 extension needs to be replaced by the .p extension. (Refer to "Differences in Filenames" in the Multics/UNIX Product Differences Guide for further details on naming conventions.) It is more convenient to rename the files on Multics before transferring them to UNIX. 2) Transfer file to UNIX Now the file needs to be transferred from Multics to UNIX (for example, using Kermit). The site administrator should be able to provide the details of transfer as the available methods may vary from site to site. Refer to the "Communciation Protocols" section in this manual for additional information. 3) Make source changes Some changes may be required to the source before it will compile correctly. In general, you will need to see if required support routines are available (such as equivalents for ioa_ and cu_$arg_count in this case). Available support routines are listed in "Quick Reference to Multics/UNIX Equivalents" in this document. It is recommended that help be invoked on each routine being used to note differences from its Multics counterpart, especially in the parameter declarations. In this case, entering the command help "ucu_$arg_count" will reveal that the declaration of ucu_$arg_count is "entry (fixed bin, fixed bin(31))" whereas the declaration for cu_$arg_count is "entry (fixed bin, fixed bin(35))" 46 12/13/90 Bull HN Migration Guide under Multics. Subroutine name changes may also be required (e.g. ioa_ should be renamed to uioa_). (These and other needed changes are described in more detail in the section "Porting Applications" of this manual (which should be read thoroughly before making any of the source code changes). Also, the PL/I section (and any other related sections) of the Multics/UNIX Product Differences Manual should be read as product differences may affect correct behaviour of user applications.) When necessary changes have been made, the example program will resemble the following: main: proc; dcl uioa_ entry options(variable); dcl ucu_$arg_count entry (fixed bin, fixed bin(31)); dcl arg_count fixed bin; call ucu_$arg_count(arg_count,(0)); call uioa_ ("Passed ^d args", arg_count); end; 4) Compile/Link The pl1 command is used to compile and link PL/I programs on the DPX/2. In this case, the following command should compile the program count_args.p: pl1 count_args.p -o count_args This will produce an executable file called count_args. Now, entering the command "count_args arg1 arg2" should indicate 2 arguments and "count_args" should indicate 0 arguments. There are a number of useful features and options in the pl1 compiler. You are encouraged to read the help file by entering the command "help pl1". 12/13/90 47 Migration Guide Bull HN 6.2. Appendix B: Notes on DPX/2 Hardware and UNIX Software Errors and Incompatibilities 6.2.1. CAS and CAS2 Instructions A problem exists either in the DPX/2 hardware or in the UNIX kernal regarding the MC68030 instructions cas and cas2. These instructions perform atomic read-modify-write operations on 32 and 64 bit operands, respectively. The problem manifests as a "hang" -- that is, the process experiencing the problem fails to proceed executing instructions following the cas or cas2. In some cases, if the hung process is not killed, the entire system will hang. The circumstances under which this occurs cannot be easily predicted, so using these instructions until such time as this fault is corrected is risky. These instructions are generated by the PL/I builtin functions stac and stacq, and are used by the PL/I area management code (allocate and free commands), the uiox_ subroutines, and the vfile_ I/O module. 6.2.2. Incompatible UNIX System Routines The following UNIX system routines should not be used with the Migration Package: o "signal" is incompatible with Migration Package condition management, which uses the UNIX routine sigset. Details are available from the UNIX manual (sigset(2), signal(2)). o "pause" is also incompatible with Migration Package condition management, for the same reasons as signal. See the UNIX manual (pause(2), sigpause(2)). o direct use of UNIX signal management routines (such as sigset) will override Migration Package condition management, and may result in incorrect or a lack of invocation of PL/I condition handlers, or failure of PL/I "on" or "revert" statements. 48 12/13/90 Bull HN Migration Guide o certain UNIX system routines have been replaced with equivalents in the Migration Package. When using the Migration Package, these routines would be used in preference to the standard UNIX versions. This is default behaviour when linking programs via the pl1 command, but requires careful thought when linking via the UNIX cc command, or link editor (ld command). 12/13/90 49 Migration Guide Bull HN 6.3. Appendix C: Quick Reference to Multics/UNIX Equivalents This section provides a quick reference of facilities and subroutines available on UNIX which simulate equivalent products on Multics. Be sure to look at the online help or the Multics/UNIX Product Differences Guide for a particular product before actually using it, since possible differences from the Multics equivalent may affect use of the product. Commands and Tools _M_U_L_T_I_C_S _U_N_I_X ALM (for error tables only) cet create_data_segment, cds cdo help help list_help, lh list_help, lh pl1 pl1 reductions, rdc rdc Subroutine Support _M_U_L_T_I_C_S _U_N_I_X absolute_pathname_ uabsolute_pathname_ absolute_pathname_$add_suffix uabsolute_pathname_$add_suffix assign_ uassign_ assign_$computational_ uassign_$computational_ assign_$assign_round_ uassign_$round_ assign_$assign_truncate_ uassign_$truncate_ assign_$char_to_numeric_ uassign_$char_to_numeric_ com_err_ ucom_err_ com_err_$suppress_name ucom_err_$suppress_name convert_date_to_binary_ uconvert_date_to_binary_ convert_date_to_binary_$relative uconvert_date_to_binary_$relative create_data_segment_ create_data_object_ 50 12/13/90 Bull HN Migration Guide (Subroutine Support continued) _M_U_L_T_I_C_S _U_N_I_X cu_ ucu_ cu_$arg_count ucu_$arg_count cu_$arg_count_rel ucu_$arg_count_rel cu_$arg_list_ptr ucu_$arg_list_ptr cu_$arg_ptr ucu_$arg_ptr cu_$arg_ptr_rel ucu_$arg_ptr_rel cu_$caller_ptr ucu_$caller_ptr cu_$cp ucu_$cp cu_$decode_entry_value ucu_$decode_entry_value cu_$gen_call ucu_$gen_call cu_$generate_call ucu_$generate_call cu_$make_entry_value ucu_$make_entry_value cu_$ptr_call ucu_$ptr_call date_time_ udate_time_ date_time_$format udate_time_$format date_time_$format_max_length udate_time_$format_max_length date_time_$from_clock udate_time_$from_clock date_time_$from_clock_interval udate_time_$from_clock_interval date_time_$fstime udate_time_$fstime date_time_$offset_to_clock udate_time_$offset_to_clock date_time_$set_lang udate_time_$set_lang date_time_$set_zone udate_time_$set_zone date_time_$to_clock udate_time_$to_clock date_time_$valid_format udate_time_$valid_format decode_descriptor_ udecode_descriptor_ expand_pathname_ uexpand_pathname_ expand_pathname_$add_suffix uexpand_pathname_$add_suffix get_wdir_ uget_wdir_ ioa_ uioa_ ioa_$ioa_switch uioa_$fd ioa_$ioa_switch_nnl uioa_$fdnnl ioa_$general_rs uioa_$general_rs ioa_$nnl uioa_$nnl ioa_$rs uioa_$rs ioa_$rsnnl uioa_$rsnnl ioa_$rsnp uioa_$rsnp ioa_$rsnpnnl uioa_$rsnpnnl 12/13/90 51 Migration Guide Bull HN (Subroutine Support continued) _M_U_L_T_I_C_S _U_N_I_X iox_ uiox_ iox_$attach_loud uiox_$attach_loud iox_$attach_name uiox_$attach_name iox_$attach_iocb uiox_$attach_switch iox_$close uiox_$close iox_$close_file uiox_$close_file iox_$control uiox_$control iox_$delete_record uiox_$delete_record iox_$destroy_iocb uiox_$destroy_switch iox_$detach uiox_$detach iox_$detach_iocb uiox_$detach_switch iox_$find_iocb uiox_$find_switch iox_$get_chars uiox_$get_chars iox_$get_line uiox_$get_line iox_$look_iocb uiox_$look_switch iox_$modes uiox_$modes iox_$move_attach uiox_$move_attach iox_$open uiox_$open iox_$open_file uiox_$open_file iox_$position uiox_$position iox_$put_chars uiox_$put_chars iox_$read_key uiox_$read_key iox_$read_length uiox_$read_length iox_$read_record uiox_$read_record iox_$rewrite_record uiox_$rewrite_record iox_$seek_key uiox_$seek_key iox_$write_record uiox_$write_record lex_error_ ulex_error_ lex_string_ ulex_string_ lex_string_$init_lex_delims ulex_string_$init_lex_delims lex_string_$lex ulex_string_$lex pathname_ upathname_ 52 12/13/90 Bull HN Migration Guide I/O Modules _M_U_L_T_I_C_S _U_N_I_X tty_ unix_io_ vfile_ vfile_ 12/13/90 53 Migration Guide Bull HN 6.4. Appendix D: References 1) AT&T, UNIX System V Programmer's Reference Manual 2) Bull HN, Multics Programmer's Reference Manual (AG91-04C) 54 12/13/90 ----------------------------------------------------------- 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