LIB_Get_Default_File_Protection and LIB_Substitute_Wildcards

In this article we will we look at two of the new services we've been referencing in the past several articles. First the user documentation and then the code.

LIB_Get_Default_File_Protection

Returns the default file protection mask for a given process.

Format

LIB_Get_Default_File_Protection pid

Arguments

pid
The process ID of the process whose default file protection mask is to be returned. A value of 0 indicates to return the current process default file protection mask.

Description

This service returns the default file protection mask for the specified process. This mask is a set of 4 fields, each 4 bits, which indicate the protection for newly created files. Each field indicates protection for a given type of user: owner, group, system, and world. The fields are layed out in the following order:

Type	Access	Bit value (hex)
Owner	Read	1
Owner	Write	2
Owner	Delete/Control	4
Owner	Execute	8
Group	Read	10
Group	Write	20
Group	Delete/Control	40
Group	Execute	80
System	Read	100
System	Write	200
System	Delete/Control	400
System	Execute	800
World	Read	1000
World	Write	2000
World	Delete/Control	4000
World	Execute	8000

Condition codes returned
SS_NONEXPR Specified process does not exist.
SS_NORMAL Normal completion of service.

---

function Get_Default_File_Protection( PID : TPID ) : int64 ;

begin
    Result := 0 ;
    LIB_Get_Default_File_Protection( int64( @PID ), int64( @Result ) ) ;
end ;

This PasStartlet function is a wrapper for the Starlet function.

function LIB_Get_Default_File_Protection( PID, Res : int64 ) : int64 ;

begin
    //TODO: Hard-coded for now
    Result := 0 ;
    if( Res <> 0 ) then
    begin
        pint64( Res )^ := PROTECTION_OWNER_MASK or PROTECTION_SYSTEM_MASK or
            PROTECTION_GROUP_READ or PROTECTION_GROUP_EXECUTE ;
    end ;
end ;

This Starlet function is used to return the default file protection for the passed process. For now, this is simply defaults to O:RWED,S:RWED,G:RE
In the future, we will address how this can be changed.

The question may come to the mind of some readers: why is there a separate READ and EXECUTE protection flag? Isn't execution simply a form of reading? Couldn't someone copy the file (read), mark it as executable and then run it anyway? Though that is true, there is one important consideration: execution of a file is done with the file's privilege mask such that those privileges are active while the file is executing. But a user cannot grant privileges they do not have to any of their files. Thus, they cannot give those privileges to their copy of the file and then run it with said privileges. And if they only have read access to the original file, they cannot run it with it's assigned privileges either. So, though READ and EXECUTE protections usually go hand-in-hand, there are important security reasons for allowing them to be separate.

One other thing of note with file protections. The DELETE protection is also used as a CONTROL protection. The CONTROL concept has no effect on files, but it does have an effect on other system resources which use the file protection flags. The exact effect(s) depend on the resource in question and we will address those as they come up.

---

LIB_Substitute_Wildcards

Returns a file specification substituting wildcards with defaults and values from a non-wildcard specification.

Format

LIB_Substitute_Wildcards source target defaults result length

Arguments

source
The address of an SRB that points to the source file specification.

target
The address of an SRB that points to the target file specification. This is the specification that can contain wildcards. Note that empty fields are implied "*" wildcards.

defaults
The address of an SRB that points to the default file specification. Any fields missing (null) in the target specification are filled from this specification before the wildcard substitution is done.

result
The address of an SRB that points to the buffer to receive the resulting file specification. The length indicates the maximum size of the buffer, in bytes.

length
The address of a 64-bit integer to receive the actual size of the result. If 0, no size is returned.

Description

This service constructs a result file specification from a source specification, a target (containing wildcards) and a default specification. The default specification is first used to fill any null fields in the target. Wildcard fields are not filled from the default. Next the source specification is used to fill any remaining null fields or wildcards in the target. The result is returned to the specificed buffer. If the buffer is too small to contain the result, as much as will fit is returned and the service returns a SS_BUFFEROVF condition. Note that null fields that are not specified in any of the three specifications will be null in the result. This service does not perform any validation of the file specifications' syntax nor does it check to see if the resulting specification refers to an existing file.

Condition codes returned
SS_NORMAL Normal completion of service.
SS_BUFFEROVF Result buffer was not large enough to fit the entire result specification.

---

function Substitute_Wildcards( Source, Target, Defaults : string ) : string ;

var SRB_Source, SRB_Target, SRB_Defaults, Res : TSRB ;
    ResLen : int64 ;

begin
    Result := Source + Target + Defaults ;
    Set_String( Result, Res ) ;
    Set_String( Source, SRB_Source ) ;
    Set_String( Target, SRB_Target ) ;
    Set_String( Defaults, SRB_Defaults ) ;
    ResLen := 0 ;
    if( LIB_Substitute_Wildcards( int64( @SRB_Source ), int64( @SRB_Target ),
        int64( @SRB_Defaults ), int64( @Res ), int64( @ResLen ) ) <> 0 ) then
    begin
        Result := '' ;
        exit ;
    end ;
end ;

This function is PasStarlet is a wrapper for the Starlet routine.

function Substitute_Wildcards( Source, Target, Defaults : string ) : string ;

var SRB_Source, SRB_Target, SRB_Defaults, Res : TSRB ;
    ResLen : int64 ;

begin
    Result := Source + Target + Defaults ;
    Set_String( Result, Res ) ;
    Set_String( Source, SRB_Source ) ;
    Set_String( Target, SRB_Target ) ;
    Set_String( Defaults, SRB_Defaults ) ;
    ResLen := 0 ;
    if( LIB_Substitute_Wildcards( int64( @SRB_Source ), int64( @SRB_Target ),
        int64( @SRB_Defaults ), int64( @Res ), int64( @ResLen ) ) <> 0 ) then
    begin
        Result := '' ;
        exit ;
    end ;
end ;

This Paslib function is a Pascal wrapper for LIB_Substitute_Wildcards. The reason for the first assignment is that the resulting string cannot be longer than all three of the source strings, so by appending them together, we get a result buffer that is guaranteed to be long enough to hold the entire result.

function LIB_Substitute_Wildcards( _Source, _Target, _Defaults, _Res,
    Reslen : int64 ) : int64 ;

var Source, Wildcards, Target, Defaults, Res : string ;
    SNode, SAccess, SNode2, SDevice, SPath, SName, SFType, SVersion : string ;
    TNode, TAccess, TNode2, TDevice, TPath, TName, TFType, TVersion : string ;
    DNode, DAccess, DNode2, DDevice, DPath, DName, DFType, DVersion : string ;

begin
    // Setup...
    Result := 0 ; // Assume success
    Source := Get_String( PSRB( _Source )^ ) ;
    Target := Get_String( PSRB( _Target )^ ) ;
    Defaults := Get_String( PSRB( _Defaults )^ ) ;

    // Parse each filespec...
    Parse_Filename( Source, SNode, SAccess, SNode2, SDevice, SPath, SName, SFType, 
        SVersion ) ;
    Parse_Filename( Target, TNode, TAccess, TNode2, TDevice, TPath, TName, TFType, 
        TVersion ) ;
    Parse_Filename( Defaults, DNode, DAccess, DNode2, DDevice, DPath, DName, DFType, 
        DVersion ) ;

This new Starlet function starts by obtaining the parameter strings and then parsing the three specifications.

    // Substitute defaults...
    if( ( TNode = '' ) and ( DNode <> '' ) ) then
    begin
        TNode := DNode ;
    end ;
    if( ( TAccess = '' ) and ( DAccess <> '' ) ) then
    begin
        TAccess := DAccess ;
    end ;
    if( ( TNode2 = '' ) and ( DNode2 <> '' ) ) then
    begin
        TNode2 := DNode2 ;
    end ;
    if( ( TDevice = '' ) and ( DDevice <> '' ) ) then
    begin
        TDevice := DDevice ;
    end ;
    if( ( TPath = '' ) and ( DPath <> '' ) ) then
    begin
        TPath := DPath ;
    end ;
    if( ( TName = '' ) and ( DName <> '' ) ) then
    begin
        TName := DName ;
    end ;
    if( ( TFType = '' ) and ( DFType <> '' ) ) then
    begin
        TFType := DFType ;
    end ;
    if( ( TVersion = '' ) and ( DVersion <> '' ) ) then
    begin
        TVersion := DVersion ;
    end ;

The first step is to substitute any null fields in the target with the values (if any) from the default specification.

    // Now substitute wildcards...
    if( ( TNode = '' ) and ( SNode <> '' ) ) then
    begin
        TNode := SNode ;
    end ;
    TNode := _Substitute( TNode, SNode ) ;
    if( ( TAccess = '' ) and ( SAccess <> '' ) ) then
    begin
        TAccess := SAccess ;
    end ;
    TAccess := _Substitute( TAccess, SAccess ) ;
    if( ( TNode2 = '' ) and ( SNode2 <> '' ) ) then
    begin
        TNode2 := SNode2 ;
    end ;
    TNode := _Substitute( TNode, SNode ) ;
    if( ( TDevice = '' ) and ( SDevice <> '' ) ) then
    begin
        TDevice := SDevice ;
    end ;
    TDevice := _Substitute( TDevice, SDevice ) ;
    if( ( TPath = '' ) and ( SPath <> '' ) ) then
    begin
        TPath := SPath ;
    end ;
    TPath := _Substitute( TPath, SPath ) ;
    if( ( TName = '' ) and ( SName <> '' ) ) then
    begin
        TName := SName ;
    end ;
    TName := _Substitute( TName, SName ) ;
    if( ( TFType = '' ) and ( SFType <> '' ) ) then
    begin
        TFType := SFType ;
    end ;
    TFType := _Substitute( TFType, SFType ) ;
    if( ( TVersion = '' ) and ( SVersion <> '' ) ) then
    begin
        TVersion := SVersion ;
    end ;
    TVersion := _Substitute( TVersion, SVersion ) ;

Next we go through each field, doing the substitution for each one.

    // Build result string...
    Res := TNode + TAccess + TDevice + TName + TFType + TVersion ;
    if( length( Res ) > PSRB( _Res )^.Length ) then
    begin
        setlength( Res, PSRB( _Res )^.Length ) ;
        Result := UOSErr_Buffer_Overflow ;
    end ;

    // Return results...
    if( ResLen <> 0 ) then
    begin
        pint64( Reslen )^ := length( Res ) ; // Return actual result length
    end ;
    move( PChar( Res )[ 0 ], PChar( PSRB( _Res )^.Buffer )[ 0 ], length( Res ) ) ;
end ; // LIB_Substitute_Wildcards

Next, we build the new result specification from the individual fields. If this is longer than the size of the result buffer, we truncate the result and set the buffer overflow notice. Finally, we update the result length if an address was provided, and then write the result value.

    function _Substitute( T, S : string ) : string ;

    begin
        if( ( T = '' ) or ( T = '*' ) ) then
        begin
            Result := S ;
        end else
        begin
            Result := T ;
        end ;
    end ;

This local function does the actual substitution for us. As noted in a previous article, this only does the substitution if the result field is a "*" wildcard or null (an implied wildcard). We may enhance this in the future.

In the next article, We will look at some more system services.