ieee_get_state_at_signal man page on Tru64

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
Tru64 logo
[printable version]

ieee(3)								       ieee(3)

NAME
       ieee,  ieee_set_fp_control, ieee_get_fp_control, ieee_set_state_at_sig‐
       nal, ieee_get_state_at_signal, ieee_ignore_state_at_signal - libc  ieee
       trap enable support routines

SYNOPSIS
       #include <machine/fpu.h>

       void ieee_set_fp_control(
	       unsigned	 long fp_control ); unsigned long ieee_get_fp_control(
       ); void ieee_set_state_at_signal(
	       unsigned long fp_control,
	       unsigned long fpcr ); int ieee_get_state_at_signal(
	       unsigned long *fp_control,
	       unsigned long *fpcr ); void ieee_ignore_state_at_signal( );

LIBRARY
       Standard C Library (libc.so, libc.a)

PARAMETERS
       Software IEEE floating-point  control.	Hardware  IEEE	floating-point
       control register.

DESCRIPTION
       These  routines	support	 the  implementation  of the IEEE Standard for
       Binary Floating-Point Arithmetic.

       IEEE-format floating-point operations  are  subject  to	the  following
       traps:  Invalid	operation  Division by zero Overflow Underflow Inexact
       result

       (Note that floating-point-to-integer conversion operations may generate
       an integer overflow trap, which the operating system traps and delivers
       as an invalid operation.)

       By default, floating-point  operations  generate	 imprecise  traps  for
       invalid	operation,  division  by  zero,	 and overflow errors. To cause
       floating-point errors to be handled with precise exception  faults,  or
       with the signal handling specified in the IEEE floating-point standard,
       C language programmers should use the -ieee option to the  cc  command.
       Assembly	 language  programmers	should	use the su suffix on floating-
       point instruction opcodes and follow the software completion  rules  of
       the  Alpha architecture. These methods allow you to access all features
       of the IEEE standard except the inexact result feature.

       The inexact result feature can sometimes degrade performance, so a dif‐
       ferent  method  is required to enable it. Assembly language programmers
       can access the inexact result feature by using the sui suffix on float‐
       ing-point  instruction  opcodes.	 C language programmers can access the
       inexact result feature by replacing the -ieee option to the cc  command
       with  the -ieee_with_inexact option. On some Alpha implementations, the
       inexact result feature is implemented by trapping to a software	emula‐
       tor.  Using  sui	 floating-point instructions or the -ieee_with_inexact
       option might cause a significant drop in performance on such  implemen‐
       tations.	 Because  of  this,  you should use the inexact result feature
       only in those few program statements where inexact signaling is needed.

       When your code is compiled with- ieee or -ieee_with_inexact, the deliv‐
       ery  of	all  floating-point  traps  to	a  user program is disabled by
       default. A user program can request the delivery of  any	 of  the  five
       standard IEEE traps by calling ieee_set_fp_control() to set the associ‐
       ated options in	the  software  IEEE  floating-point  control  register
       (fp_control)  that control trap delivery. And, in a similar way, a user
       program can request delivery of an invalid operation  trap  whenever  a
       denormalized operand is used.

       When the IEEE gradual underflow capability (that is, denormalized oper‐
       ands and results) is not desired, it can be disabled by specifying  one
       or both of the options to map denormalized input operands to zero or to
       flush underflowing results to zero.

       The following constants are defined in machine/fpu.h and can be used to
       construct  an  appropriate  set	mask  in the fp_control argument to an
       ieee_set_fp_control() call:

       ──────────────────────────────────────────────────────
       Constant		       Meaning
       ──────────────────────────────────────────────────────
       IEEE_TRAP_ENABLE_INV    Invalid operation
       IEEE_TRAP_ENABLE_DZE    Divide by 0
       IEEE_TRAP_ENABLE_OVF    Overflow
       IEEE_TRAP_ENABLE_UNF    Underflow
       IEEE_TRAP_ENABLE_INE    Inexact
       IEEE_TRAP_ENABLE_DNO    Denormal operand
       IEEE_TRAP_ENABLE_MASK   Mask of all the trap enables
       IEEE_MAP_DMZ	       Map denormal inputs to zero
       IEEE_MAP_UMZ	       Map underflow results to zero
       ──────────────────────────────────────────────────────

       The fp_control, which can be read by  means  of	ieee_get_fp_control(),
       also  contains  status  options	which,	when set, indicate one or more
       occurrences of individual floating-point	 exception  conditions.	 These
       options remain set until a user program explicitly clears them by call‐
       ing ieee_set_fp_control(). To allow manipulation of these options,  the
       following constants are defined in machine/fpu.h:

       ──────────────────────────────────────────────────
       Constant		  Meaning
       ──────────────────────────────────────────────────
       IEEE_STATUS_INV	  Invalid operation
       IEEE_STATUS_DZE	  Divide by 0
       IEEE_STATUS_OVF	  Overflow
       IEEE_STATUS_UNF	  Underflow
       IEEE_STATUS_INE	  Inexact
       IEEE_STATUS_DNO	  Denormal operand
       IEEE_STATUS_MASK	  Mask of all the status options
       ──────────────────────────────────────────────────

       At  thread  creation  (and  process  creation as a result of an exec(2)
       call), the delivery of all floating-point traps	is  disabled  and  all
       floating-point exception status options in the fp_control are clear. If
       the thread creating the new process has set  the	 inherit  bit  in  its
       fp_control  (by	specifying the constant IEEE_INHERIT in the fp_control
       mask to an ieee_set_fp_control() call), the newly created process  will
       inherit its creator's fpcr and fp_control settings.

       At  a  fork(2)  call,  the  child  process always inherits its parent's
       fp_control and fpcr settings, regardless of the setting of the  inherit
       bit.

       Users  should  be  careful  to  remember	 that  setting the bits in the
       fp_control, like setting signal handlers, will affect other code within
       their thread.

       A user program calls ieee_get_fp_control() to obtain a copy of the cur‐
       rent fp_control. Additionally,  the  jmp_buf  argument  for  setjmp(3),
       which  uses struct sigcontext from signal(4) as an overlay, provides an
       sc_fp_control field. When a user program issues a longjmp(3) or	sigre‐
       turn(2), the sc_fp_control includes the current set of trap options.

       The  IEEE standard specifies default result values (including denormal‐
       ized numbers, NaNs, and infinities) for	operations  that  cause	 traps
       that  are not user-enabled. An operating system trap handler must “com‐
       plete” these operations by supplying the default IEEE result.  For  the
       operating  system  to properly fix the results of these operations, the
       code must be generated as resumption safe and software completion  must
       be specified in the trapping mode.

       The  concept  of	 resumption-safe  code	warrants  further explanation.
       Because HP Alpha systems incorporate pipelining	and  multi-instruction
       issue  techniques,  when	 an  arithmetic	 exception occurs, the program
       counter may not contain the address of the  instruction	that  actually
       caused the trap (referred to as the trigger PC). It may instead contain
       the address of the instruction that was executing at the time the  trap
       was  executed  (referred	 to  as	 the  trap  PC).   Several intervening
       instructions may have been present and could have changed  the  machine
       state  from  what it was at the time of the exception. The instructions
       between the trigger PC and the trap PC are called the trap shadow.

       The Alpha Architecture Reference Manual specifies conventions for  cre‐
       ating  the  trap	 shadow	 so that the operating system trap handler can
       provide an IEEE result value for an operation and  continue  execution.
       The architecture provides a way for software to mark instructions which
       abide by the conventions and a user may request this  of	 the  compiler
       driver (cc(1)) by specifying the -ieee option on the command line.

       To  determine  which exception occurred, the operating system trap han‐
       dler must back up instructions and look for the	trigger	 PC.  Once  it
       finds  the  trigger  PC, the software may need to re-execute or emulate
       the trigger instruction to determine which trap it actually caused.

       Once the validity of the trap  shadow  and  the	trigger	 exception  is
       determined,  the	 operating  system  can then decide what to do when an
       exception occurs, depending on three factors: Whether the user  program
       has  set	 any of the trap-enable options in fp_control Whether the user
       program has been created as resumption safe code Whether the user  pro‐
       gram has specified a handler for SIGFPE, has decided to ignore the sig‐
       nal (SIG_IGN), or has accepted the signal's default treatment (SIG_DFL)

       The following table describes the system's actions based on these three
       factors:

       ───────────────────────────────────────────────────────────────
       SIGFPE		 Trap enable   Shadow	 Actions
       ───────────────────────────────────────────────────────────────
       SIG_IGN		 clear	       invalid	 Continue     at
						 trap PC + 4.
       SIG_DFL		 clear	       invalid	 Cause	    core
						 dump.
       SIG_IGN|SIG_DFL	 clear	       safe	 Supply	 default
						 IEEE	  result
						 value	and con‐
						 tinue at  trig‐
						 ger PC + 4.
       SIG_IGN		 set	       invalid	 Continue     at
						 trap PC + 4.
       SIG_DFL		 set	       invalid	 Cause	    core
						 dump.
       SIG_IGN		 set	       safe	 Supply	 default
						 IEEE	  result
						 value	and con‐
						 tinue at  trig‐
						 ger PC + 4.

       SIG_DFL		 set	       safe	 Cause	    core
						 dump.
       user handler	 clear	       invalid	 Deliver  SIGFPE
						 to   user  pro‐
						 gram.
       user handler	 clear	       safe	 Supply	 default
						 IEEE	  result
						 value and  con‐
						 tinue	at trig‐
						 ger PC + 4.
       user handler	 set	       invalid	 Deliver  SIGFPE
						 to   user  pro‐
						 gram,	trap  PC
						 ==  trigger PC,
						 and	     set
						 ieee_invalid_shadow.
       user handler	 set	       safe	 Deliver  SIGFPE   to
						 user	program	  and
						 trap PC  !=  trigger
						 PC.
       ───────────────────────────────────────────────────────────────

       See signal(4) for additional information on default actions for SIGFPE.

       A SIGFPE handler can also obtain additional information about floating-
       point exceptions from the sigcontext. The sigcontext contains a copy of
       the  current  fp_control in sc_fp_control, allowing a handler to deter‐
       mine which traps were enabled at the time of the exception.

       On precise floating faults (in which the system trap handler has	 indi‐
       cated  a	 valid	trap  shadow  and executed successfully), indicated by
       codes FPE_xxxxx_FAULT, relevant sigcontext fields contain the following
       information:  sc_traparg_a0  contains  the  exception  summary register
       reported by hardware.  sc_traparg_a1 contains  the  exception  register
       write  mask  reported by hardware.  sc_fp_trap_pc contains the trap PC.
       sc_pc contains the trigger PC.  sc_fp_trigger_sum contains  the	excep‐
       tion summary register reported by hardware with the SWC bit masked off.
       sc_fp_trigger_inst is a copy of the trigger instruction.

       On precise arithmetic faults with valid trap shadows, the result regis‐
       ter  of the faulting instruction is loaded with the IEEE floating-point
       result that would have been generated if the  exception	had  not  been
       signaled.  One  way to continue from such a fault is to increment sc_pc
       by 4 and continue with  this  result  (or  some	modification  of  it).
       Another	way  to	 continue  from a precise fault is to modify the input
       registers to the floating operation, leave the sc_pc  field  unchanged,
       and then reexecute the faulting instruction with the modified input.

       On  imprecise  arithmetic  traps	 (for  instance,  when an invalid trap
       shadow has been detected), indicated by codes  FPE_xxxxx_TRAP,  sigcon‐
       text  provides  the  same  information, with the following differences:
       sc_pc contains the trap PC.  sc_fp_trigger_inst is undefined.

       By default, the exception state at the time of a floating-point	excep‐
       tion,  as represented by the fp_control and fpcr, is the state provided
       to a signal handler.

       The ieee_set_state_at_signal() routine allows a user program to specify
       the values to be placed in the fp_control and the fpcr at the call to a
       signal handler. This enables the program	 to  easily  modify  the  trap
       enables	or  rounding modes so that a critical region (for instance, in
       third-party code executed from a signal handler) is immune from certain
       exception  state.  The original settings of the fp_control and the fpcr
       are saved in the sigcontext prior  to  the  signal.  When  the  handler
       returns, the original floating-point context is restored.

       A  user	program	 can  retrieve	the  current exception state reporting
       behavior by calling ieee_get_state_at_signal().

       The ieee_ignore_state_at_signal() routine specifies that floating-point
       state  is  not  modified	 when calling a signal handler. A user program
       calls this routine to restore the  default  exception  state  reporting
       behavior.

FILES
       /usr/include/excpt.h -- include file
       /usr/include/signal.h -- include file
       /usr/include/machine/fpu.h -- include file

SEE ALSO
       Commands: cc(1).

       Functions:  exec(2),  ieee_functions(3),	 longjmp(3), setjmp(3), sigre‐
       turn(2), write_rnd(3).

       Files: c_excpt(4), excpt(4), signal(4).

       IEEE Standard  for  Binary  Floating-Point  Arithmetic  (ANSI/IEEE  Std
       754-1985).

       Alpha Architecture Reference Manual.

       Assembly Language Programmer's Guide.

       Programmer's Guide.

								       ieee(3)
[top]
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server Tru64

List of man pages available for Tru64

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net