Not so well documented Device Helpers in OS/2

Index

DevHlp_OpenFile

Description

This devhlp allows to open a file for read access in the Init routine of a BASEDEV.

Calling convention

Returns

Data structures

 
; assembler structure
SYIOpenFile struc
length		dw	8	; length of structure, must contain value 8
name		dd	?	; 16:16 ASCIZ pathname
fsize		dd	?	; returned: size of file
SYIOpenFile	ends

Restrictions

 Valid at INIT time only. This routine is not handle based, so it is only possible to have only one file at a time open.
This routine uses the corresponding function of the miniFSD, not normal file I/O, thus access is restricted. At this phase of boot, drive letters do not yet exist, and IFSs/DMDs might not yet have been initialized, so you can only open files on the boot drive. Depending on the type of IPL (e.g. loading from a network file system), other restrictions might apply.

Bugs

The returned file size is unreliable, the value returned is always <65K. IMHO, the length field of the data structure should contain 10, not 8.

DevHlp_CloseFile

Description

This devhlp closes a file opened by DevHlp_OpenFile.

Calling convention

Returns

Data structures

 
; assembler structure
SYICloseFile	struc
length		dw	2	; length of structure (must be 2)
SYICloseFile	ends

Restrictions

Valid at INIT time only. See also restrictions of DevHlp_OpenFile

DevHlp_ReadFile

Description

This devhlp is used to read from a file opened with DevHlp_OpenFile.

Calling convention

Returns

Data structures

 
; assembler structure
SYIReadFile	struc
length		dw	8	; length of structure (must be 8)
buffer		dd	?	; 16:16 address of a read buffer
size		dd	?	; number of bytes to read
SYIReadFile	ends

Restrictions

Valid at INIT time only. Although the size argument of the data structure implies, I'd recommend to better not read more than 32K at a time. Note that the buffer itself is segmented, so DMA overrun and other effects might apply, depending on the quality of the miniIFS in use.

Bugs

IMHO, the length of structure should be 10, not 8.

DevHlp_ReadFileAt

Description

This devhlp is used to read from a file opened with DevHlp_OpenFile, in contrast to a normal read, a start position can be specified.

Calling convention

Returns

Data structures

 
; assembler structure
SYIReadFile	struc
length		dw	12	; length of structure (must be 12)
buffer		dd	?	; 16:16 address of a read buffer
size		dd	?	; number of bytes to read
startpos	dd	?	; starting position of read relative to
				; start of file
SYIReadFile	ends

Restrictions

Valid at INIT time only. Although the size argument of the data structure implies, I'd recommend to better not read more than 32K at a time. Note that the buffer itself is segmented, so DMA overrun and other effects might apply, depending on the quality of the miniIFS in use.

Bugs

IMHO, the length of structure should be 14, not 12.

DevHlp_QSysState

Description

This devhlp is the equivalent of DosQuerySysState API call. See more details about the data structures, arguments and options there.

Calling convention

Returns

Data structures

See DosQuerySysState

Restrictions

Valid at TASK time only. See DosQuerySysState

DevHlp_KillProc

Description

This is a special entry into DosKillProcess, which is more rigid in killing processes: the killed process won't be able to execute its kill signal handler, thus open files might not be closed properly. A process currently operating in ring 0 will terminate as soon as it returns to ring 3 (this means, a process blocked in the kernel, e.g. on a pending I/O, can still not be killed). This devhlp corresponds to the SESKillProcess API.

Calling convention

Returns

Data structures

None.

Restrictions

Valid at TASK time only.

DevHlp_Security

Description

This is the kernel support for the security enabling services.

Calling convention

Subfunction: DHSEC_SETIMPORT

This function will load the ISS Security Event Service Routine Table into the kernel. Each service routine will be called upon a certain API event, such as opening a file, or starting a program. There are also service routines to capture each DOS API routine (if you are interested in this, and you are considered trustworthy by me, i.e. well-known in the OS/2 hacker's scene, I can give you code for these rather tricky routines - collectors and gatherers stay off!).

Subfunction: DHSEC_GETEXPORT

This function will return the table of security helper functions for file access. These helpers provide low level access to any file in the system which is not controlled by security services (unlike the normal DOS API).

Subfunction: DHSEC_GETINFO

Internally used function, information withheld intentionally.

Subfunction: DHSEC_AUDITHOOK

Internally used function, information withheld intentionally.

Subfunction: DHSEC_TRUSTEDPATHNOTIFY

Internally used function, information withheld intentionally.

Subfunction: DHSEC_IMPORT_PDF

Special purpose function for an IBM product, information withheld intentionally.

Subfunction: DHSEC_IMPORT_AV

Special purpose function for an IBM product, information withheld intentionally.

Returns

Data structures

It is beyond the scope of this text to explain all details of SES. Consult the Red Book SG2446-68, also available via DevCon. IBM has decided, as of SG2446-68, appendix A, not to publish the SES KPI. You can ask, according to the Red Book for this documentation at:
IBM Manager of OS/2 Security
Mail Stop 9171
11400 Burnet Rd.
Austin, Texas 78758
(is this address still valid?)

Restrictions

Valid at any time.
Comments to: Holger Veit