SYS_WRITE Service

In the previous article, we wrote to a file in our INQUIRE command processing. In this article, we cover the code for Blockwrite and address the SYS_WRITE service, which does the actual file output. Here is the system call documentation:

WRITE

The WRITE service transfers a specified number of bytes to a file or device.

Format

WRITE rab, err, suc

Arguments

rab
RAB structure that defines what to write.

err
Address of AST routine to call if the operation is unsuccessful. If non-zero, this overrides RAB_AST_Err field of the RAB.

suc
Address of AST routine to call when the operation completess successfully. If non-zero, this overrides RAB_AST_Success field of the RAB.

Description

The address of the data and its size must be passed to the service. Writing to/past the end of a file results in the extending the file. The following RAB fields are used by this service:

RAB field Description

RAB_Size Byte size of the RAB structure

RAB_AST_Err Address of AST routine to call on error

RAB_AST_Success Address of AST routine to call when operation completes successfully

RAB_Data_Stream Data stream to write to

RAB_L_BKT File offset to write to

RAB_W_ISI Handle to open file

RAB_B_RAC Access type. 0 = binary file access.

RAB_L_ROP Record processing options (see RAB_V_*)

RAB_L_UBF Address of data to write

RAB_W_USZ Number of bytes to write

Condition Values Returned
RMS_RAB
UOSErr_Invalid_Handle
UOSErr_Memory_Address_Error
UOSErr_Quota_Exceeded
Other errors specific to the device or file

procedure TUOS_File_Wrapper.Blockwrite( var Buf ; Count : int64 ;
   var Res : int64 ) ;

var RAB : TRAB ;

begin
    fillchar( RAB, sizeof( RAB ), 0 ) ;
    RAB.RAB_Size := sizeof( RAB ) ;
    RAB.RAB_L_BKT := _FilePos ;
    RAB.RAB_W_ISI := FAB.FAB_Q_HANDLE ;
    RAB.RAB_L_UBF	:= int64( @Buf ) ; // User buffer address
    RAB.RAB_W_USZ	:= Count ; // Record size
    SYS_WRITE( int64( @RAB ), 0, 0 ) ;
    Res := RAB.RAB_W_RSZ ; // Bytes actually written
end ;

The code in the previous article made use of the Blockwrite function of the File object. Thus far, we had only discussed reading data from files. So, here we add this new file method to allow writing data to files.

function SYS_WRITE( RAB : int64 ; Err : int64 = 0 ; Succ : int64 = 0 ) : int64 ;

var Status : int64 ;
    SysRequest : TInteger_Request ;

begin
    if( RAB = 0 ) then
    begin
        Result := RMS_RAB ;
        Call_To_User( Err ) ;
        exit ;
    end ;
    Status := 0 ;
    fillchar( SysRequest, sizeof( SysRequest ), 0 ) ;
    SysRequest.Request.Subsystem :=  UOS_Subsystem_FIP ;
    SysRequest.Request.Request := UOS_FIP_Write ;
    SysRequest.Request.Length := sizeof( SysRequest ) - sizeof( TSystem_Request ) ;
    SysRequest.Request.Status := integer( @Status ) ;
    SysRequest.Int := RAB ;

    Call_To_Ring0( integer( @SysRequest ) ) ;
end ; // SYS_WRITE

This new function wraps the call to the kernel. Other than the UOS_FIP_Write request value, this is identical to the SYS_READ routine.

        UOS_FIP_Write:
            begin
                UE := Enter_System_Call( Request, SReq, PID, MMC,
                    sizeof( Integer_Request ) - sizeof( SReq ), Address ) ;
                if( UE <> nil ) then
                begin
                    Set_Last_Error( UE ) ;
                    exit ;
                end ;
                try
                    Integer_Request := PInteger_Request( Address ) ;

                    Status := File_Write( Integer_Request.Int, IOSB ) ;
                    Write_User_int64( Kernel, PID, Integer_Request.Request.Status,
                        IOSB.r_io_64.r_bcnt_32.l_bcnt ) ;
                finally
                    Exit_System_Call( integer( Integer_Request ), PID, MMC,
                        sizeof( Integer_Request ) - sizeof( SReq ) ) ;
                end ;
            end ;

This new code in the kernel's API method handles the WRITE call.

function TUOS_FiP.File_Write( _RAB : int64 ; var IOSB : TIOSB ) : int64 ;

var Buff : PAnsiChar ;
    Offset : integer ;
    PID : TPID ;
    RAB : TRAB ;
    Resource : TResource ;
    S : string ;

begin>
    Result := 0 ;
    if( _RAB = 0 ) then
    begin
        Result := RMS_RAB ;
        IOSB.r_io_64.w_status := Result ;
        exit ;
    end ;

    // Get the RAB...
    fillchar( RAB, sizeof( RAB ), 0 ) ;
    PID := Kernel.PID ;
    Get_User_Data( Kernel, PID, _RAB, 2, RAB, IOSB.r_io_64.w_status ) ; // Get RAB length
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;
    if( RAB.RAB_Size > sizeof( RAB ) ) then
    begin
        RAB.RAB_Size := sizeof( RAB ) ;
    end ;
    Get_User_Data( Kernel, PID, _RAB, RAB.RAB_Size, RAB, IOSB.r_io_64.w_status ) ; // Get RAB
    if( IOSB.r_io_64.w_status <> 0 ) then
    begin
        Result := IOSB.r_io_64.w_status ;
        exit ;
    end ;

This new FIP method handles the actual writing of data to a file. The first thing we do is validate the RAB structure, whose address was passed to us. This mirrors the work done in File_Read, which we covered before.

    // Validate...
    if( not USC.Valid_Handle( PID, RAB.RAB_W_ISI ) ) then
    begin
        Set_Last_Error( Create_Error( UOSErr_Invalid_Handle ) ) ;
        Result := UOSErr_Invalid_Handle ;
        exit ;
    end ;
    if( RAB.RAB_W_USZ = 0 ) then
    begin
        exit ; // No operation
    end ;
    Resource := TResource( RAB.RAB_W_ISI ) ;
    if( ( RAB.RAB_B_RAC = 0 ) or ( RAB.RAB_L_BKT <> 0 ) ) then // Binary I/O or non-zero position
    begin
        Resource.Position := RAB.RAB_L_BKT ;
    end ;

Next we validate the handle and exit if there is an error. Otherwise, we update the file position as per the RAB, like we did in File_Read.

    // Map user buffer into our memory space...
    Offset := MMC.Lock_Pages( PID, RAB.RAB_L_UBF, RAB.RAB_W_USZ ) ;
    try
        Buff := PAnsiChar( MMC.Map_Pages( PID, 0, RAB.RAB_L_UBF, RAB.RAB_W_USZ, MAM_Read or MAM_Lock ) ) ;
        if( Buff = nil ) then
        begin
            if( MMC.Last_Error = nil ) then
            begin
                Generate_Exception( UOSErr_Memory_Address_Error ) ;
            end ;
            exit ;
        end ;

        try
            // Write to the file...
            if( Write_File( RAB.RAB_W_ISI, RAB.RAB_Data_Stream, Buff + Offset, RAB.RAB_W_USZ, 
              RAB.RAB_L_ROP ) <> nil ) then
            begin
                E := USC.Get_Process_Exception( PID ) ;
                Result := E.Get_Error ;
                IOSB.r_io_64.w_status := Result ;
            end ;
        finally
            MMC.UnMap_Pages( 0, RAB.RAB_L_UBF, RAB.RAB_W_USZ ) ;
        end ;
    finally
        MMC.Unlock_Pages( PID, RAB.RAB_L_UBF, RAB.RAB_W_USZ ) ;
    end ;
end ; // TUOS_FiP.File_Write

Next, we map the user's buffer into the kernel's address space and then call Write_File to do the actual write operation. Finally, we unmap the pages containing the user's buffer. Note that it is possible that the write operation may have failed (for instance, due to the file being read-only). In any case, the IOSB result will be set appropriately.

    if( ( Flags and RAB_V_CCO ) <> 0 ) then // Disable Control-O
    begin
        Output_Filter.Flags := Output_Filter.Flags and ( not TOFF_Null ) ;
        _Disable_Ctrl_O := True ;
    end ;
    Result := Output_Filter.Write( S, False, 0, Flags ) ;
    if( ( Flags and RAB_V_CCO ) <> 0 ) then // Re-enable Control-O
    begin
        _Disable_Ctrl_O := False ;
    end ;

One of the flags that can be used for writing to terminals is RAB_V_CCO. This turns off the Control-O feature for the duration of this operation. We wrap the Output_Filter.Write (in TTerminal.Write_Data) with code to handle this flag. Note: this flag is ignored for writes to any device other than terminals.

        if(
            ( ( Flags and TIFF_Binary ) = 0 ) // Cooked input
            and
            ( not Term.Disable_Ctrl_O ) // Control-O not disabled
          ) then

We update the TDefault_Input_Filter.New_Character method to check this flag when processing control-O. The original check for binary mode is replaced by this code.

In the next article, we will look at the next UCL command.