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
- CY=0, AX = 0: okay, structure pointed to by ES:DI is modified
- CY=1, AX = ERROR_BAD_LENGTH: packet is invalid
- CY=1, AX = <>0: other filesystem related errors
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
- CY=0, AX = 0, okay
- CY=1, AX = APIRET error code
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
- CY=0, AX = 0: read okay
- CY=1, AX = ERROR_BAD_LENGTH: packet is invalid
- CY=1, AX = <>0: other filesystem related errors
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
- CY=0, AX = 0: read okay
- CY=1, AX = ERROR_BAD_LENGTH: packet is invalid
- CY=1, AX = <>0: other filesystem related errors
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
- EAX = function code
- EBX = argument 1
- EDI = high 16 bit: argument 2, low 16 bit: argument 3
- ESI = FLAT (linear) address of a buffer
- ECX = size of buffer
- DL = 07eh
Returns
- CY=0, AX = 0, okay
- CY=1, AX = APIRET error code
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
- BX = Pid of process to kill, 0 = current process
- DL = 07dh
Returns
- CY=0, AX = 0, okay
- CY=1, AX = APIRET error code
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!).
- EAX = 073ae3627h special function key
- ECX = FLAT (linear) address of table to be submitted
- DL = 044h
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).
- EAX = 048a78df8h special function key
- ECX = FLAT (linear) address of a buffer to receive the 40 byte table
- DL = 044h
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
- CY=0, AX = 0, okay
- CY=1, AX = APIRET error code
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