Info Catalog octave: Leaving Debug Mode octave: Debugging octave: Debug Mode

octave: Breakpoints

 
 13.3 Breakpoints
 ================
 
 Breakpoints can be set in any m-file function by using the ‘dbstop’
 function.
 
  -- : dbstop FUNC
  -- : dbstop FUNC LINE
  -- : dbstop FUNC LINE1 LINE2 ...
  -- : dbstop LINE1 ...
  -- : dbstop in FUNC
  -- : dbstop in FUNC at LINE
  -- : dbstop in FUNC at LINE if "CONDITION"
  -- : dbstop if EVENT
  -- : dbstop if EVENT ID
  -- : dbstop (BP_STRUCT)
  -- : RLINE = dbstop ...
 
      Set breakpoints for the built-in debugger.
 
      FUNC is the name of a function on the current ‘path’.  When already
      in debug mode the FUNC argument can be omitted and the current
      function will be used.  Breakpoints at subfunctions are set with
      the scope operator ‘>’.  For example, If ‘file.m’ has a subfunction
      ‘func2’, then a breakpoint in ‘func2’ can be specified by
      ‘file>func2’.
 
      LINE is the line number at which to break.  If LINE is not
      specified, it defaults to the first executable line in the file
      ‘func.m’.  Multiple lines can be specified in a single command;
      when function syntax is used, the lines may also be passed as a
      single vector argument (‘[LINE1, LINE2, ...]’).
 
      CONDITION is any Octave expression that can be evaluated in the
      code context that exists at the breakpoint.  When the breakpoint is
      encountered, CONDITION will be evaluated, and execution will stop
      if CONDITION is true.  If CONDITION cannot be evaluated, for
      example because it refers to an undefined variable, an error will
      be thrown.  Expressions with side effects (such as ‘y++ > 1’) will
      alter variables, and should generally be avoided.  Conditions
      containing quotes (‘"’, ‘'’) or comment characters (‘#’, ‘%’) must
      be enclosed in quotes.  (This does not apply to conditions entered
      from the editor’s context menu.)  For example:
 
           dbstop in strread at 209 if 'any (format == "%f")'
 
      The form specifying EVENT does not cause a specific breakpoint at a
      given function and line number.  Instead it causes debug mode to be
      entered when certain unexpected events are encountered.  Possible
      values are
 
      ‘error’
           Stop when an error is reported.  This is equivalent to
           specifying both ‘debug_on_error (true)’ and
           ‘debug_on_interrupt (true)’.
 
      ‘caught error’
           Stop when an error is caught by a try-catch block (not yet
           implemented).
 
      ‘interrupt’
           Stop when an interrupt (‘Ctrl-C’) occurs.
 
      ‘naninf’
           Stop when code returns a non-finite value (not yet
           implemented).
 
      ‘warning’
           Stop when a warning is reported.  This is equivalent to
           specifying ‘debug_on_warning (true)’.
 
      The events ‘error’, ‘caught error’, and ‘warning’ can all be
      followed by a string specifying an error ID or warning ID.  If that
      is done, only errors with the specified ID will cause execution to
      stop.  To stop on one of a set of IDs, multiple ‘dbstop’ commands
      must be issued.
 
      Breakpoints and events can be removed using the ‘dbclear’ command
      with the same syntax.
 
      It is possible to save all breakpoints and restore them at once by
      issuing the commands ‘bp_state = dbstatus; ...; dbstop (bp_state)’.
 
      The optional output RLINE is the real line number where the
      breakpoint was set.  This can differ from the specified line if the
      line is not executable.  For example, if a breakpoint attempted on
      a blank line then Octave will set the real breakpoint at the next
      executable line.
 
      When a file is re-parsed, such as when it is modified outside the
      GUI, all breakpoints within the file are cleared.
 
      See also: dbclear XREFdbclear, dbstatus XREFdbstatus,
      dbstep XREFdbstep, debug_on_error XREFdebug_on_error,
DONTPRINTYET       debug_on_warning XREFdebug_on_warning, *noteDONTPRINTYET       debug_on_warning XREFdebug_on_warning, 
      debug_on_interrupt XREFdebug_on_interrupt.
 
 Breakpoints in class methods are also supported (e.g., ‘dbstop
 ("@class/method")’).  However, breakpoints cannot be set in built-in
 functions (e.g., ‘sin’, etc.)  or dynamically loaded functions (i.e.,
 oct-files).
 
    To set a breakpoint immediately upon entering a function use line
 number 1, or omit the line number entirely and just give the function
 name.  When setting the breakpoint Octave will ignore the leading
 comment block, and the breakpoint will be set on the first executable
 statement in the function.  For example:
 
      dbstop ("asind", 1)
      ⇒ 29
 
 Note that the return value of ‘29’ means that the breakpoint was
 effectively set to line 29.  The status of breakpoints in a function can
 be queried with ‘dbstatus’.
 
  -- : dbstatus
  -- : dbstatus FUNC
  -- : BP_LIST = dbstatus ...
      Report the location of active breakpoints.
 
      When called with no input or output arguments, print the list of
      all functions with breakpoints and the line numbers where those
      breakpoints are set.
 
      If a function name FUNC is specified then only report breakpoints
      for the named function and its subfunctions.
 
      The optional return argument BP_LIST is a struct array with the
      following fields.
 
      name
           The name of the function with a breakpoint.  A subfunction,
           say ‘func2’ within an m-file, say ‘file.m’, is specified as
           ‘file>func2’.
 
      file
           The name of the m-file where the function code is located.
 
      line
           The line number with the breakpoint.
 
      cond
           The condition that must be satisfied for the breakpoint to be
           active, or the empty string for unconditional breakpoints.
 
      If ‘dbstop if error’ is true but no explicit IDs are specified, the
      return value will have an empty field called "errs".  If IDs are
      specified, the ‘errs’ field will have one row per ID.  If ‘dbstop
      if error’ is false, there is no "errs" field.  The "warn" field is
      set similarly by ‘dbstop if warning’.
 
      See also: dbstop XREFdbstop, dbclear XREFdbclear,
DONTPRINTYET       dbwhere XREFdbwhere, dblist XREFdblist, *noteDONTPRINTYET       dbwhere XREFdbwhere, dblist XREFdblist, 
      dbstack XREFdbstack.
 
 Reusing the previous example, ‘dbstatus ("asind")’ will return 29.  The
 breakpoints listed can then be cleared with the ‘dbclear’ function.
 
  -- : dbclear FUNC
  -- : dbclear FUNC LINE
  -- : dbclear FUNC LINE1 LINE2 ...
  -- : dbclear LINE ...
  -- : dbclear all
  -- : dbclear in FUNC
  -- : dbclear in FUNC at LINE
  -- : dbclear if EVENT
  -- : dbclear ("FUNC")
  -- : dbclear ("FUNC", LINE)
  -- : dbclear ("FUNC", LINE1, LINE2, ...)
  -- : dbclear ("FUNC", LINE1, ...)
  -- : dbclear (LINE, ...)
  -- : dbclear ("all")
      Delete a breakpoint at line number LINE in the function FUNC.
 
      Arguments are
 
      FUNC
           Function name as a string variable.  When already in debug
           mode this argument can be omitted and the current function
           will be used.
 
      LINE
           Line number from which to remove a breakpoint.  Multiple lines
           may be given as separate arguments or as a vector.
 
      EVENT
           An event such as ‘error’, ‘interrupt’, or ‘warning’ (
           dbstop XREFdbstop. for details).
 
      When called without a line number specification all breakpoints in
      the named function are cleared.
 
      If the requested line is not a breakpoint no action is performed.
 
      The special keyword "all" will clear all breakpoints from all
      files.
 
      See also: dbstop XREFdbstop, dbstatus XREFdbstatus,
      dbwhere XREFdbwhere.
 
 
    A breakpoint may also be set in a subfunction.  For example, if a
 file contains the functions
 
      function y = func1 (x)
        y = func2 (x);
      endfunction
      function y = func2 (x)
        y = x + 1;
      endfunction
 
 then a breakpoint can be set at the start of the subfunction directly
 with
 
      dbstop (["func1", filemarker(), "func2"])
      ⇒ 5
 
    Note that ‘filemarker’ returns the character that marks subfunctions
 from the file containing them.  Unless the default has been changed this
 character is ‘>’.  Thus, a quicker and more normal way to set the
 breakpoint would be
 
      dbstop func1>func2
 
    Another simple way of setting a breakpoint in an Octave script is the
 use of the ‘keyboard’ function.
 
  -- : keyboard ()
  -- : keyboard ("PROMPT")
      Stop m-file execution and enter debug mode.
 
      When the ‘keyboard’ function is executed, Octave prints a prompt
      and waits for user input.  The input strings are then evaluated and
      the results are printed.  This makes it possible to examine the
      values of variables within a function, and to assign new values if
      necessary.  To leave the prompt and return to normal execution type
      ‘return’ or ‘dbcont’.  The ‘keyboard’ function does not return an
      exit status.
 
      If ‘keyboard’ is invoked without arguments, a default prompt of
      ‘debug> ’ is used.
 
DONTPRINTYET       See also: dbstop XREFdbstop, dbcont XREFdbcont, *noteDONTPRINTYET       See also: dbstop XREFdbstop, dbcont XREFdbcont, 
      dbquit XREFdbquit.
 
 The ‘keyboard’ function is placed in a script at the point where the
 user desires that the execution be stopped.  It automatically sets the
 running script into the debug mode.
 

Info Catalog octave: Leaving Debug Mode octave: Debugging octave: Debug Mode