@node _go32_dpmi_allocate_iret_wrapper, dpmi
@findex _go32_dpmi_allocate_iret_wrapper
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function creates a small assembler function that handles the
overhead of servicing an interrupt.  To use, put the address of your
servicing function in the @code{pm_offset} field of @var{info} and call
this function.  The @code{pm_field} will get replaced with the address
of the wrapper function, which you pass to both
@code{_go32_dpmi_set_protected_mode_interrupt_vector} and
@code{_go32_dpmi_free_iret_wrapper}.

@strong{Warning!} Because of the way DPMI works, you may @emph{not}
@code{longjmp} out of an interrupt handler or perform any system calls
(such as @code{printf}) from within an interrupt handler.

Do not enable interrupts with @code{enable()} or @code{asm("sti")} in your function.

See also @ref{_go32_dpmi_set_protected_mode_interrupt_vector},
and @ref{_go32_dpmi_free_iret_wrapper}.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example
_go32_dpmi_seginfo info;
info.pm_offset = my_handler;
_go32_dpmi_allocate_iret_wrapper(&info);
_go32_dpmi_set_protected_mode_interrupt_handler(0x75, &info);
@dots{}
_go32_dpmi_free_iret_wrapper(&info);
@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_chain_protected_mode_interrupt_vector, dpmi
@findex _go32_dpmi_chain_protected_mode_interrupt_vector
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_chain_protected_mode_interrupt_vector(
        int vector, _go32_dpmi_seginfo *info
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function is used to chain a protected mode interrupt.  It will
build a suitable wrapper that will call your function and then jump to
the next handler.  Your function need not perform any special handling.

@strong{Warning!} Because of the way DPMI works, you may @emph{not}
@code{longjmp} out of an interrupt handler or perform any system calls
(such as @code{printf}) from within an interrupt handler.

Do not enable interrupts with @code{enable()} or @code{asm("sti")} in your function.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@xref{_go32_dpmi_set_protected_mode_interrupt_vector}.

@c ----------------------------------------------------------------------
@node _go32_dpmi_free_iret_wrapper, dpmi
@findex _go32_dpmi_free_iret_wrapper
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_free_iret_wrapper(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function frees the memory used by the wrapper created by
@code{_go32_dpmi_allocate_iret_wrapper}.  You should not free a wrapper
that is still in use.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@xref{_go32_dpmi_allocate_iret_wrapper}.
@c ----------------------------------------------------------------------
@node _go32_interrupt_stack_size, go32
@vindex _go32_interrupt_stack_size
@subheading Syntax

@example
#include <dpmi.h>

extern unsigned long _go32_interrupt_stack_size;
@end example

@subheading Description

The default size of the interrupt handler's stack.  Defaults to 32k.

@subheading Portability

@portability !ansi, !posix

@c ----------------------------------------------------------------------
@node _go32_dpmi_lock_code, go32
@findex _go32_dpmi_lock_code
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_lock_code( void *lockaddr, unsigned long locksize);
@end example

@subheading Description

Locks the given region of code, starting at @var{lockaddr} for
@var{locksize} bytes.  @var{lockaddr} is a regular pointer in
your program, such as the address of a function.

@subheading Return Value

0 if success, -1 if failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example

void my_handler()
@{
@}

void lock_my_handler()
@{
  _go32_dpmi_lock_code(my_handler,
                       (unsigned long)(lock_my_handler - my_handler));
@}
@end example

@c ----------------------------------------------------------------------
@node _go32_dpmi_lock_data, go32
@findex _go32_dpmi_lock_data
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_lock_data( void *lockaddr, unsigned long locksize);
@end example

@subheading Description

Locks the given region of data, starting at @var{lockaddr} for
@var{locksize} bytes.  @var{lockaddr} is a regular pointer in
your program, such as the address of a variable.

@subheading Return Value

0 if success, -1 if failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example

int semaphore=0;

void lock_my_handler()
@{
  _go32_dpmi_lock_data(&semaphore, 4);
@}
@end example