-qcheck

Purpose

Generates code that performs certain types of runtime checking.

-qcheck is the long form of the -C option.

Syntax


        .-nocheck--------------------------.   
>>- -q--+-check--+-----------------------+-+-------------------><
                 |    .-all------------. |     
                 '-=--+-bounds---------+-'     
                      +-nobounds-------+       
                      +-stackclobber---+       
                      +-nostackclobber-+       
                      +-unset----------+       
                      '-nounset--------'

@PROCESS:

@PROCESS CHECK[(suboptions)] | NOCHECK

Defaults

-qnocheck

Parameters

all

Enables all suboptions.

bounds | nobounds

Checks each reference to an array element, array section, or character substring to ensure the reference stays within the defined bounds of the entity.

stackclobber | nostackclobber

Detects stack corruption of nonvolatile registers in the save area in user programs. This type of corruption happens only if any of the nonvolatile registers in the save area of the stack is modified.

If the -qstackprotect option and this suboption are both on, this suboption catches the stack corruption first.

unset | nounset

Checks for automatic variables that are used before they are set. A trap will occur at run time if an automatic variable is not set before it is used.

The -qinitauto option initializes automatic variables. As a result, the -qinitauto option hides uninitialized variables from the -qcheck=unset option.

The -qsave option changes the storage class of automatic variables to STATIC. As a result, the -qsave option hides variables that are used before they are set from the -qcheck=unset option.

Specify the -qsigtrap option to get a traceback that shows the procedure calls leading to the use of the variable. If you also specify the -g option, the traceback will include the line numbers and procedure names.

Specifying -qcheck with no suboption is equivalent to specifying -qcheck=all.

Usage

You can specify the -qcheck option more than once. The suboption settings are accumulated, but the later suboptions override the earlier ones.

You can use the all suboption along with the no... form of one or more of the other options as a filter. For example, using:

xlf myprogram.f -qcheck=all:nobounds

provides checking for everything except for references that go out of bounds. If you use all with the no... form of the suboptions, all should usually be the first suboption.

At compile time, if the compiler can determine that a reference goes out of bounds, the severity of the error reported is increased to S (severe) when -qcheck=bounds is enabled.

At run time, if a reference goes out of bounds or if a certain type of stack corruption is detected, the program generates a SIGTRAP signal. By default, this signal ends the program and produces a core dump. This is an expected behavior and does not indicate there is a defect in the compiler product.

Because runtime checking can slow execution, you should decide which is the more important factor for each program: the performance impact or the possibility of incorrect results if an error goes undetected. You might decide to use this option only while testing and debugging a program (if performance is more important) or also for compiling the production version (if safety is more important).

The -qcheck option prevents some optimizations. You may want to remove the -qcheck option after the debugging of your code is complete and then add any wanted optimization options for better performance.

The valid bounds for character substring expressions differ depending on the setting of the -qzerosize option.

Examples

The following code example shows an out-of-bounds access of an allocatable array that is detected by -qcheck=bounds:

program outofbounds
  real, allocatable :: x(:)  
  allocate(x(5:10))  
  x(1) = 3.0  ! Out of bound access. 
  print *, x
end

In the following example, a random assignment of an integer pointer corrupts the save area of the call stack. -qcheck=stackclobber detects the problem and causes a trap:

subroutine update(i, off, value)
  implicit none
  integer, value :: i, off
  character, value :: value
  integer pointee
  pointer(p, pointee)
  p = i + off
  pointee = ichar(value)
end subroutine

subroutine sub1()
  implicit none
  interface
    subroutine update(i, off, value)
      integer, value :: i, off
      character, value :: value
    end subroutine
  end interface
  character(9) buffer
  buffer = ""
  ! This call to update will corrupt the call stack.
  ! Offset 48 is within the save area for this program.
  call update(loc(buffer), 48, 'a')
  print *, buffer
end subroutine

program main
  call sub1
end program

Note: The offset of the save area of the call stack depends on the program source and optimization level. When -O2 or a lower optimization level is in effect, offset 48 falls within the save area.

In the following function factorial, temp is not initialized when n<=1, and result is accessed before it is set when n>1. To compile factorial.f to detect this issue and causes traps during run time, enter the following command:

xlf95 -qcheck=unset -O -g -qsigtrap factorial.f

factorial.f contains the following code:

module m
contains
  recursive function factorial(n) result(result)
    integer, value :: n
    integer result, temp

    if (n > 1) then
      temp = n * factorial(n - 1)
      print *, result ! line 9
    endif
 
    result = temp ! line 12
  end function
end module
 
use m
integer x
x = factorial(1)
end

The compiler issues the following informational messages and traps occur near line 12 and line 18 during run time:

1500-098 (I) "factorial.f", line 9: "result" is used before it is set. 
1500-098 (I) "factorial.f", line 12: "temp" might be used before it is set. 
1501-510  Compilation successful for file factorial.f.
$ ./a.out    

  Signal received: SIGTRAP - Trace trap
    Fortran language trap: reference to unset memory location    

  Traceback:
    Offset 0x00000014 in procedure __m_NMOD_factorial, near line 12 in file factorial.f
    Offset 0x00000028 in procedure _main, near line 18 in file factorial.f
    --- End of call chain ---

Note: If you set -qcheck=unset at noopt, the compiler does not issue informational messages at compile time.

Related information

-qstackprotect
-qhot
-qzerosize
-qsigtrap and Installing an exception handler describe how to detect and recover from SIGTRAP signals without ending the program.