B.3.4  Miscellaneous UNIX Kernel Functions, Macros, and Variables

Although the functions, macros, and variables listed below are not part of the STREAMS definition, they are often used by STREAMS stacks. Therefore they are provided as part of the STREAMS environment for Windows NT.

Time Variables:

lbolt
time

Timer Functions:

timeout
untimeout

Miscellaneous Routines:

bcopy
min
suser
bzero
minor
max
major

The global kernel variables lbolt and time are frequently used by STREAMS stacks to calculate relative time. In Windows NT, these variables are defined as macros that call Windows NT kernel services to calculate their value. As such they incur overhead to convert from the Windows NT time format. Performance conscious transports should replace references to these variables with calls to the native Windows NT equivalents: KeQueryTickCount and KeQuerySystemTime.

The suser function currently always returns a value of 1.

The timer function timeout schedules a procedure to be executed at some time in the future. It is implemented using KeSetTimer to schedule the target procedure as a DPC, via a timer object. The function untimeout cancels an earlier call to timeout. It returns 1 if it has successfully canceled the timer, -1 if its argument is invalid, or 0 if the target procedure cannot be canceled.

Note In Windows NT, it is possible for untimeout to fail even thought the timeout handler has not yet executed. In this case, the execution of the timeout handler will be pending. Alternately, the handler may already be executing and spinning on a lock currently held by the transport. Often, a timeout handler will be passed a pointer to a transport structure. If that structure is freed and the timeout cannot be canceled, the handler will execute and possibly modify memory no longer owned by the transport. A transport must be prepared to handle these circumstances in a safe manner, or system crashes will result.

The timeout and untimeout functions incur substantial overhead compared to the native Windows NT services. Performance conscious transports should replace calls to these functions with calls to the native services.