STOP

In this article, we look at the STOP command - the next new thing used in our shutdown script. STOP is used to terminate a running image. If the specified process is detached, the process will immediately end. The process can be specified by name or ID. STOP also can be used to end an interrupted program. For attached processes, control returns to the shell.

It may be helpful to review images and processes before we continue. A process consists of a supervisor-mode context and a user-mode context. The shell runs in supervisor mode. Any programs are executed in user mode. A control-Y can be used to interrupt the program and return control to the shell. The user-mode context remains paused. At that point, the program execution can be resumed or STOP can be used to force the program to terminate. Scripts, on the other hand, run within the shell.

Images are the programs that run in the user-mode context. Thus, an image and a running program are identical. When an image finishes, it automatically exits, which sends the terminal control back to the shell. STOP allows the early termination of an image before it normally exits upon finishing. An image can set ASTs for exit conditions, which STOP can optionally allow to execute. Generally it is good to allow exit routines to run to clean up and save data, etc. However, a program may fail during an exit routine (perhaps an infinite loop), in which case it is important to be able to force the image to end without using any exit routines.

Images terminate normally by calling the $EXIT service, which releases resources such as memory and handles. $FORCEX simply calls this service as if the target process made the call to $EXIT. If the program calls the service, it is considered a normal stop, whereas exceptions and $FORCEX cause an abnormal stop. $DELPRC also causes an abnormal stop, but without calling the $EXIT service. Images come and go but processes only end via $DELPRC.

Reasons for stopping an image abnormally can range from fixing a hung program to interrupting a process that is taking up too many resources. In our immediate case, it is used to remove running detached processes during system shutdown.

First the documentation for STOP and then FORCEX, which is what is used to cause an image to end immediately. Then code for the STOP command in UCL and the service call itself.

STOP
Terminates execution of a command, image, or script, or a program that was interrupted by Ctrl/Y.

Format

STOP {name}{qualifiers}

Parameter

name
If specified, the process with the name is the one whose image is stopped. If the name contains spaces or lowercase characters, it must be enclosed in quotes (").
The specified process must have the same UIC as the calling process or else privileges are required. If the specified process is a different UIC, the user must have WORLD privilege. However, if the both UICs are in the same group, the GROUP privilege allows the current process to stop the specified process.
A process name and the /IDENTIFICATION qualifier are mutually exclusive.

Description

STOP causes an abnormal termination of an image that is currently executing. If the image has declared user-mode exit-handling routines, these handlers are not invoked.
In the absence of a name or qualifier, the currently interrupted image is stopped. If used in a non-interactive process (such as a batch job), the process is also terminated. If used in an interrupted script, the script is ended.

Qualifiers

/EXIT{=accessmode}
Specifies that exit handlers are to be called prior to stopping the image.

Mode	Description
EXECUTIVE_MODE	This is the default if no mode is specified with /EXIT. Executes executive and more privileged mode exit handlers.
KERNEL_MODE	Executes kernel mode exit handlers.
SUPERVISOR_MODE	Executes supervisor and more privileged mode exit handlers.
USER_MODE	Executes user and more privileged mode exit handlers.

/IDENTIFICATION=pid
Indicates the process ID of the process whose image is to be stopped.

/IMAGE
This qualifier is ignored unless used in conjunction with the /IDENTIIFICATION qualifier or a process name. Otherwise, a non-interactive process is not killed - any script will continue executing after the point of the command that started the image that is stopped.

Required Privileges

GROUP is required to stop a process that shares a group but not a UIC.
WORLD is required to stop a process that doesn't share a group and has a different UIC.

Examples

$ ON ERROR THEN STOP
After executing this command, any error in a script will immediately end the script. This operates differently than ON ERROR THEN EXIT, since EXIT only exits the current nest level, but STOP ends the script.

$ STOP/EXIT Terminates the current image and runs exit handlers beginning at executive mode.

$ STOP/IMAGE/ID=42 In this case, the image running in the process with PID of 42 is stopped.

---

FORCEX
Forces an $EXIT service call to be issued on behalf of the specified process.

Format

SYS$FORCEX pidadr prcnam code

Arguments

pidadr
The address of a 64-bit value containing the ID of the process to be forced to exit. If 0, this parameter is ignored. If neither pidadr or prcnam is specified, the current process is the target.

prcnam
The address of a 64-bit integer containing the exit parameter. If not specified (paramter is 0), a value of 0 is passed to the exit routine.

code
The address of an SRB structure pointing to the name of the process. If 0, this parameter is ignored. If neither pidadr or prcnam is specified, the current process is the target.

Description

This service causes the $EXIT service to be called on behalf of the target process. If the current process is the target process, this call does not return. This call ends the image, but not necessarily the process. The process is only deleted if it is a detached process or a non-interactive job. To delete a process, use the $DELPRC service. If the target process is already processing an $EXIT call, this call does nothing but returns success.

If the image resumes normal processing as part of the exit handler, it will not end. If the image is suspended, it cannot execute the exit handler and the call will fail without returning an error.

Required Privileges

GROUP is required to stop a process that shares a group but not a UIC.
WORLD is required to stop a process that doesn't share a group and has a different UIC.

Condition Codes Returned

SS$_NORMAL Normal completion.
SS$_ACCVIO Memory access violation.
SS$_NONEXPR The specified process does not exist.
SS$_NOPRIV The calling process doesn't have the privileges necessary to affect the target process.

---

procedure Process_Stop ;

var Access_Mode : integer ;
    Identification : int64 ;
    Image : boolean ;
    Res : int64 ;
    S, Temp : string ;

begin
    Image := False ;
    Identification := 0 ;
    Access_Mode := PSL_C_EXEC ;
    S := Parser.Grab_Line ; // Get process name
    if( Parse_Switch( 'E|XIT', '', S, Temp ) = 1 ) then
    begin
        if( Name_Match( Temp, 'EXECUTIVE_MODE', 1 ) ) then
        begin
            Access_Mode := PSL_C_EXEC ;
        end else
        if( Name_Match( Temp, 'KERNEL_MODE', 1 ) ) then
        begin
            Access_Mode := PSL_C_KERNEL ;
        end else
        if( Name_Match( Temp, 'SUPERVISOR_MODE', 1 ) ) then
        begin
            Access_Mode := PSL_C_SUPER ;
        end else
        if( Name_Match( Temp, 'USER_MODE', 1 ) ) then
        begin
            Access_Mode := PSL_C_USER ;
        end else
        begin
            Exception( UCL_IVVALU, Temp ) ;
            exit ;
        end ;
    end ;
    if( Parse_Switch( 'IM|AGE', '', S, Temp ) = 1 ) then
    begin
        if( Temp <> '' ) then
        begin
            Exception( UCL_IVQUAL, '' ) ;
            exit ;
        end ;
        Image := True ;
    end ;
    if( Parse_Switch( 'ID|ENTIFICATION', '', S, Temp ) = 1 ) then
    begin
        if( Temp = '' ) then
        begin
            Exception( UCL_VALREQ, '' ) ;
            exit ;
        end ;
        if( not trystrtoint64( Temp, Identification ) ) then
        begin
            Exception( UCL_IVVALU, Temp ) ;
            exit ;
        end ;
    end ;
    if( Switch_Present( S ) > 0 ) then
    begin
        Exception( UCL_IVQUAL, '' ) ;
        exit ;
    end ;
    S := trim( Trim_Quotes( Edit( S, 256 or 512, 0 ) ) ) ;
    if( ( Identification = 0 ) and ( S = '' ) ) then // Stop this process' image
    begin
        if( Parser.Token <> '' ) then // Executing a script
        begin
            while( Contexts.Count > 1 ) do
            begin
                Process_Exit ;
            end ;
            exit ;
        end ;
    end ;
    Res := FORCEX( Identification, S, 0, Access_Mode ) ;
end ; // Process_Stop

We add the contents of this (previously empty) routine in UCL_Main, which handles the STOP command. Note that this must be a UCL command rather than a program because a program can't be used to interrupt an executing script. Once we process the command, there are two possible paths: if we are executing a script, we terminate the script. Otherwise, we call FORCEX to force the image to end.

function FORCEX( PID : int64 ; Name : string ; Code, Ex : int64 ) : int64 ;

var SRB : TSRB ;

begin
    Set_String( Name, SRB ) ;
    Result := SYS_FORCEX( int64( @PID ), int64( @SRB ), int64( @Code ), int64( @Ex ) ) ;
end ;

This Pascal wrapper is added to the PasStarlet.

function SYS_FORCEX( pidadr, prcnam, code, Ex : int64 ) : int64 ;

var Status : int64 ;
    SysRequest : TInteger4_Request ;

begin
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_USC_FORCEX ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Int1 := pidadr ;
    SysRequest.Int2 := prcnam ;
    SysRequest.Int3 := Code ;
    SysRequest.Int4 := Ex ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
    Result := Status ;
end ;

This system service wrapper is added to the SYS unit. It is like all the others that we've covered in the past, so no further discussion is needed.

        UOS_USC_ForceX:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC, 
                    sizeof( TInteger4_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    I4_Request := PInteger4_Request( Address ) ;
                    ForceX( I4_Request.Int1, I4_Request.Int2, I4_Request.Int3,
                        I4_Request.Int4 ) ;
                finally
                    Exit_System_Call( Request, PID, MMC, 
                        sizeof( TItem_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;

This code is added to the USC API method. Like similar code in that method, we simply map the parameters and pass them to the routine that performs the operation.

function TUSC.ForceX( PID, prcname, code, Ex : int64 ) : int64 ;

var IOSB : TIOSB ;
    Name : string ;
    Process, This_Process : TProcess ;
    SRB : TSRB ;
    Status : integer ;
    Target : TPID ;
    US : TUOS_String ;

begin
    Result := 0 ;

    // Get Parameters...
    if( PID <> 0 ) then
    begin
        PID := Get_User_Integer( Kernel, Kernel.PID, PID, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;
    if( Code <> 0 ) then
    begin
        Code := Get_User_Integer( Kernel, Kernel.PID, Code, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
    end ;
    if( Ex < PSL_C_EXEC ) then
    begin
        Ex := PSL_C_EXEC ;
    end ;
    Target := Kernel.PID ; // If not specified, assume ourselves
    Name := '' ;
    if( prcname <> 0 ) then
    begin
        Get_User_Data( _Kernel, Target, prcname, sizeof( SRB ), SRB, Status ) ;
        if( Status = UE_Error ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;
        US := Get_User_String( Kernel, Target, SRB, IOSB.r_io_64.w_status ) ;
        if( IOSB.r_io_64.w_status = UE_Error ) then
        begin
            if( US <> nil ) then
            begin
                US.Free ;
            end ;
            exit ;
        end ;
        Name := As_UTF8( US ) ;
        US.Free ;
    end ; // if( prcname <> 0 )

This new USC method handles the forcing of exit. First we obtain the passed parameters.

    // Determine and validate target process...
    This_Process := Get_Process( Kernel.PID ) ;
    if( Name <> '' ) then
    begin
        Process := Process_By_Name( Name ) ;
        if( Process = nil ) then
        begin
            Result := Generate_Exception( UOSErr_Nonexistent_Process ).Get_Error ;
            exit ;
        end ;
        Target := Process._PID ;
    end else
    if( PID <> 0 ) then
    begin
        Process := Get_Process( PID ) ;
        if( Process = nil ) then // Process does not exist
        begin
            Result := Generate_Exception( UOSErr_Nonexistent_Process ).Get_Error ;
            exit ;
        end ;
        Target := PID ;
    end else
    begin
        Process := This_Process ;
    end ;
    if( Target <> Kernel.PID ) then // Affecting another process
    begin
        if( This_Process._User <> Process._User ) then // Different user
        begin
            //TODO:Check for group commonality...
            if( ( This_Process.Current_Privileges and WORLD ) = 0 ) then
            begin
                Result := Generate_Exception( UOSErr_Not_Enough_Privilege ).Get_Error ;
                exit ;
            end ;
        end ;
    end ;

Next we determine the target process. The first thing we check is if a name was specified. If not, we check the ID. If not, we assume the current process is the target process. If a process was specified, but not found, we exit with an error.

    if( not Process.Exiting ) then // Not already exiting
    begin
        Process.Exit_Process( Code, Ex ) ;
    end ;
    Process.Detach ;
end ; // TUSC.ForceX

Finally, we check to see if the process is already exiting. If so, we just exit. Otherwise, we tell the process to exit. We will cover the Exit_Proces method in a future article.

You may note the use of Process.Detach. Processes are reference-counted so that the object cannot be deleted if there is still code with a reference to the instance. When Get_Process is called, the reference count is incremented in the object. When done with it, we manually detach to decrease the reference count. When a TProcess instance is initially created, the reference count is set to 1. The $DELPRC service decrements the count, which logically deletes the process, but the instance is freed only if/when the reference count goes to 0. Otherwise, if someone else can delete the instance while we still have a pointer to it, it could result in an Executive exception.

Also note the comment about group commonality. We will discuss groups in the future.

In the next article, we will look at OPCCRASH.