.. efun:: int trace(int traceflags)
  :include: <trace.h>

  Sets the trace flags and returns the old trace flags. When tracing is on, a lot of information is printed during execution and too much output can crash your connection or even the whole driver.

  Tracing is done on a per-connection basis: each interactive(!) user may specifiy their own tracelevel and -prefix. Each gets the traceoutput for just the code executed during the evaluation of the commands he entered.

  The trace bits are:

    :macro:`TRACE_NOTHING`     (  0): stop tracing.
    :macro:`TRACE_CALL`        (  1): trace all calls to lfuns.
    :macro:`TRACE_CALL_OTHER`  (  2): trace call_others()s.
    :macro:`TRACE_RETURN`      (  4): trace function returns.
    :macro:`TRACE_ARGS`        (  8): print function arguments and results.
    :macro:`TRACE_EXEC`        ( 16): trace all executed instructions.
    :macro:`TRACE_HEART_BEAT`  ( 32): trace heartbeat code.
    :macro:`TRACE_APPLY`       ( 64): trace driver applies.
    :macro:`TRACE_OBJNAME`     (128): print the object names.

  :macro:`TRACE_EXEC` and :macro:`TRACE_HEART_BEAT` should be avoided as they cause massive output! :macro:`TRACE_OBJNAME` should be avoided when you know what you trace.

  :master:`valid_trace` is called with ``("trace", traceflags)`` as argument to verify the use of this efun.

  .. usage::

    ::

      object obj;
      string prefix;
      obj = find_player("wessex");
      prefix = object_name(obj);
      prefix = prefix[1..];  // cut off the leading "/"
      traceprefix(prefix);
      // From here on, only code in the object "std/player#69"
      // will be traced.
      //
      trace(TRACE_CALL|TRACE_CALL_OTHER|TRACE_RETURN|TRACE_ARGS);
      ...
      trace(TRACE_NOTHING);

  :history 3.2.9 changed: passes the :arg:`traceflags` argument to the :master:`valid_trace` apply as well.

  .. seealso:: :efun:`traceprefix`