Microsoft's answer: APIs that raise MUST be documented

NTFSD
1

Here is Wei Mao's answer to my original question asking which
kernel-mode APIs can raise exceptions:

Hi Nick.
Generally say if an API throws an exception but its not in the docs, that
is a doc bug. if you do meet such one, please send your feedback to
xxxxx@microsoft.com and the community will benifit from your
contribution.

However we have one reservation here and that is bad callers. For examle,
if the caller tries to release a bad poitner and causes AV in the end,
should we doc that the function raises an exception in this case? we do
not think so. The exception raised here is clearly to show the bug at
runtime. Documenting and letting others handle the exception will shield
the error from being captured at the first place.

thanks
wei

So bottom line is, if you KNOW of APIs that raise and aren't documented,
please report them and also tell us on this list.

--
Nick Ryan (MVP for DDK)

2

As far as I can tell in the IFSKIT, these APIs and no others are
documented to raise:

CcCopyWrite
CcFastCopyWrite
CcCopyRead
CcMdlRead
CcZeroData
CcInitializeCacheMap

PsReturnPoolQuota
PsChargePoolQuota

IoCreateStreamFileObjectLite
IoCreateStreamFileObjectEx
IoCreateStreamFileObject

FsRtlSplitLargeMcb
FsRtlRemoveLargeMcbEntry
FsRtlNotifyInitializeSync
FsRtlAreNamesEqual
FsRtlAllocatePoolWithTag
FsRtlAllocatePoolWithQuotaTag
FsRtlAddLargeMcbEntry
FsRtlInitializeLargeMcb

ProbeForRead
ProbeForWrite

ExRaiseDatatypeMisalignment
ExRaiseAccessViolation
ExAllocatePoolWithQuotaTag

MmMapLockedPagesSpecifyCache
MmProbeAndLockPages

–
Nick Ryan (MVP for DDK)

3

And here’s Wei’s answer to the second part of my question (about the
need to watch out for hardware exceptions):

> I still do not see the value of using SEH around
>> functions that do not take user-mode pointers and
>> are not documented to throw exceptions.

agree. if the function is not documented to throw exceptions, do not use
SEH; if it does throw, it is either a doc bug (report it) or a coding bug
with the driver (fix it)

thanks
wei

–
This posting is provided “AS IS” with no warranties, and confers no rights.
Hardware & Driver portal: http://www.microsoft.com/whdc/

–
Nick Ryan (MVP for DDK)