@node _go32_dpmi_allocate_real_mode_callback_iret, dpmi
@findex _go32_dpmi_allocate_real_mode_callback_iret
@subheading Syntax

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_iret(
        _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in effect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of an @code{iret}
instruction, so this function is useful for trapping real-mode software
interrupts (like 0x1b - @kbd{Ctrl-@key{Break}} hit). 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@example
_go32_dpmi_registers regs;

my_handler(_go32_dpmi_registers *r)
@{
  r->d.eax = 4;
@}

setup()
@{
  _go32_dpmi_seginfo info;
  _go32_dpmi_seginfo old_vector;
  _go32_dpmi_get_real_mode_interrupt_vector(0x84, &old_vector);
  info.pm_offset = my_handler;
  _go32_dpmi_allocate_real_mode_callback_iret(&info, &regs);
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &info);
  do_stuff();
  _go32_dpmi_set_real_mode_interrupt_vector(0x84, &old_vector);
  _go32_dpmi_free_real_mode_callback(&info);
@}
@end example

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

@example
#include <dpmi.h>

int _go32_dpmi_allocate_real_mode_callback_retf(
        _go32_dpmi_seginfo *info, _go32_dpmi_registers *regs
);
@end example

@subheading Description

@xref{DPMI Overview}.

This function allocates a "real-mode callback".  Fill in the
@code{pm_offset} field of @var{info} and call this function.  It will
fill in the @code{rm_segment} and @code{rm_offset} fields.  Any time a
real-mode program calls the real-mode address, your function gets
called.  The registers in effect will be stored in @var{regs}, which
should be a global, and will be passed to your function.  Any changes in
@var{regs} will be reflected back into real mode.  A wrapper will be
added to your function to simulate the effects of a far return, such
as the callback for the packet driver receiver.

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

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

@example
#include <dpmi.h>

int _go32_dpmi_free_real_mode_callback(_go32_dpmi_seginfo *info);
@end example

@subheading Description

@xref{DPMI Overview}.

This function frees the real-mode callbacks and wrappers allocated by
@code{_go32_dpmi_allocate_real_mode_callback_iret} and
@code{_go32_dpmi_allocate_real_mode_callback_retf}. 

@subheading Return Value

Zero on success, nonzero on failure.

@subheading Portability

@portability !ansi, !posix

@subheading Example

@xref{_go32_dpmi_allocate_real_mode_callback_iret}, for an example of
usage.

@c ----------------------------------------------------------------------
@node _go32_rmcb_stack_size, go32
@vindex _go32_rmcb_stack_size
@subheading Syntax

@example
#include <dpmi.h>

extern unsigned long _go32_rmcb_stack_size;
@end example

@subheading Description

The default size of the real mode callback handler's stack.  Defaults to 32k.

@subheading Portability

@portability !ansi, !posix