Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       sys - A Functional Interface to System Messages

DESCRIPTION

       This  module contains functions for sending system messages used by programs, and messages
       used for debugging purposes.

       Functions used for implementation of processes should also understand system messages such
       as  debugging  messages and code change. These functions must be used to implement the use
       of system messages for a process; either directly, or through standard behaviours, such as
       gen_server.

       The  default  timeout is 5000 ms, unless otherwise specified. The timeout defines the time
       period to wait for the process to respond to a request. If the process does  not  respond,
       the function evaluates exit({timeout, {M, F, A}}).

       The  functions  make  reference  to  a  debug  structure. The debug structure is a list of
       dbg_opt(). dbg_opt() is an internal data type used by the handle_system_msg/6 function. No
       debugging is performed if it is an empty list.

SYSTEM MESSAGES

       Processes  which  are  not  implemented  as  one  of  the  standard  behaviours must still
       understand system messages. There are three different messages which must be understood:

         * Plain system messages. These are received as {system,  From,  Msg}.  The  content  and
           meaning  of  this  message are not interpreted by the receiving process module. When a
           system message has been received, the function sys:handle_system_msg/6  is  called  in
           order to handle the request.

         * Shutdown  messages. If the process traps exits, it must be able to handle an shut-down
           request from its parent, the supervisor. The message {'EXIT', Parent, Reason} from the
           parent  is  an  order  to  terminate.  The process must terminate when this message is
           received, normally with the same Reason as Parent.

         * There is one more message which the process must understand if  the  modules  used  to
           implement  the process change dynamically during runtime. An example of such a process
           is the gen_event processes. This message is {get_modules, From}.  The  reply  to  this
           message  is From ! {modules, Modules}, where Modules is a list of the currently active
           modules in the process.

           This message is used by the release handler to find which processes execute a  certain
           module.  The  process  may  at a later time be suspended and ordered to perform a code
           change for one of its modules.

SYSTEM EVENTS

       When debugging a process  with  the  functions  of  this  module,  the  process  generates
       system_events which are then treated in the debug function. For example, trace formats the
       system events to the tty.

       There are three predefined system events which are used when a process receives or sends a
       message. The process can also define its own system events. It is always up to the process
       itself to format these events.

DATA TYPES

       name() = pid() | atom() | {global, atom()}

       system_event() = {in, Msg :: term()}
                      | {in, Msg :: term(), From :: term()}
                      | {out, Msg :: term(), To :: term()}
                      | term()

       dbg_opt()

              See above.

       dbg_fun() =
           fun((FuncState :: term(),
                Event :: system_event(),
                ProcState :: term()) ->
                   done | (NewFuncState :: term()))

EXPORTS

       log(Name, Flag) -> ok | {ok, [system_event()]}

       log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}

              Types:

                 Name = name()
                 Flag = true | {true, N :: integer() >= 1} | false | get | print
                 Timeout = timeout()

              Turns the logging of system events On or Off. If On, a maximum of N events are kept
              in  the  debug  structure (the default is 10). If Flag is get, a list of all logged
              events is returned. If Flag is print, the logged events are printed to standard_io.
              The  events  are  formatted  with  a  function  that is defined by the process that
              generated the event (with a call to sys:handle_debug/4).

       log_to_file(Name, Flag) -> ok | {error, open_file}

       log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}

              Types:

                 Name = name()
                 Flag = (FileName :: string()) | false
                 Timeout = timeout()

              Enables or disables the logging of all system events in textual format to the file.
              The  events  are  formatted  with  a  function  that is defined by the process that
              generated the event (with a call to sys:handle_debug/4).

       statistics(Name, Flag) -> ok | {ok, Statistics}

       statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}

              Types:

                 Name = name()
                 Flag = true | false | get
                 Statistics = [StatisticsTuple] | no_statistics
                 StatisticsTuple = {start_time, DateTime1}
                                 | {current_time, DateTime2}
                                 | {reductions, integer() >= 0}
                                 | {messages_in, integer() >= 0}
                                 | {messages_out, integer() >= 0}
                 DateTime1 = DateTime2 = file:date_time()
                 Timeout = timeout()

              Enables or disables the collection of statistics. If Flag is get,  the  statistical
              collection is returned.

       trace(Name, Flag) -> ok

       trace(Name, Flag, Timeout) -> ok

              Types:

                 Name = name()
                 Flag = boolean()
                 Timeout = timeout()

              Prints  all  system events on standard_io. The events are formatted with a function
              that is  defined  by  the  process  that  generated  the  event  (with  a  call  to
              sys:handle_debug/4).

       no_debug(Name) -> ok

       no_debug(Name, Timeout) -> ok

              Types:

                 Name = name()
                 Timeout = timeout()

              Turns  off  all  debugging  for the process. This includes functions that have been
              installed explicitly with the install function, for example triggers.

       suspend(Name) -> ok

       suspend(Name, Timeout) -> ok

              Types:

                 Name = name()
                 Timeout = timeout()

              Suspends the process. When the process is suspended, it will only respond to  other
              system messages, but not other messages.

       resume(Name) -> ok

       resume(Name, Timeout) -> ok

              Types:

                 Name = name()
                 Timeout = timeout()

              Resumes a suspended process.

       change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}

       change_code(Name, Module, OldVsn, Extra, Timeout) ->
                      ok | {error, Reason}

              Types:

                 Name = name()
                 Module = module()
                 OldVsn = undefined | term()
                 Extra = term()
                 Timeout = timeout()
                 Reason = term()

              Tells  the  process  to  change  code. The process must be suspended to handle this
              message. The Extra argument is reserved for each process to use  as  its  own.  The
              function  Module:system_code_change/4  is  called. OldVsn is the old version of the
              Module.

       get_status(Name) -> Status

       get_status(Name, Timeout) -> Status

              Types:

                 Name = name()
                 Timeout = timeout()
                 Status =
                     {status, Pid :: pid(), {module, Module :: module()}, [SItem]}
                 SItem = (PDict :: [{Key :: term(), Value :: term()}])
                       | (SysState :: running | suspended)
                       | (Parent :: pid())
                       | (Dbg :: [dbg_opt()])
                       | (Misc :: term())

              Gets the status of the process.

              The value of  Misc  varies  for  different  types  of  processes.  For  example,  a
              gen_server  process  returns the callback module's state, a gen_fsm process returns
              information such as its current state name and state data, and a gen_event  process
              returns  information  about  each  of its registered handlers. Callback modules for
              gen_server, gen_fsm, and  gen_event  can  also  customise  the  value  of  Misc  by
              exporting  a format_status/2 function that contributes module-specific information;
              see        gen_server:format_status/2,         gen_fsm:format_status/2,         and
              gen_event:format_status/2 for more details.

       get_state(Name) -> State

       get_state(Name, Timeout) -> State

              Types:

                 Name = name()
                 Timeout = timeout()
                 State = term()

              Gets the state of the process.

          Note:
              These  functions  are  intended  only to help with debugging. They are provided for
              convenience, allowing  developers  to  avoid  having  to  create  their  own  state
              extraction  functions and also avoid having to interactively extract state from the
              return values of get_status/1 or get_status/2 while debugging.

              The value of State varies for  different  types  of  processes.  For  a  gen_server
              process,  the  returned  State is simply the callback module's state. For a gen_fsm
              process, State is the tuple {CurrentStateName, CurrentStateData}. For  a  gen_event
              process,  State  a list of tuples, where each tuple corresponds to an event handler
              registered in the process and contains {Module, Id, HandlerState}, where Module  is
              the  event  handler's module name, Id is the handler's ID (which is the value false
              if it was registered without an ID), and HandlerState is the handler's state.

              To obtain more information about a process, including its state,  see  get_status/1
              and get_status/2.

       replace_state(Name, StateFun) -> NewState

       replace_state(Name, StateFun, Timeout) -> NewState

              Types:

                 Name = name()
                 StateFun = fun((State :: term()) -> NewState :: term())
                 Timeout = timeout()
                 NewState = term()

              Replaces the state of the process, and returns the new state.

          Note:
              These functions are intended only to help with debugging, and they should not be be
              called from normal code. They are provided for convenience, allowing developers  to
              avoid having to create their own custom state replacement functions.

              The  StateFun function provides a new state for the process. The State argument and
              NewState return value of StateFun vary for different  types  of  processes.  For  a
              gen_server  process, State is simply the callback module's state, and NewState is a
              new  instance  of  that  state.  For  a  gen_fsm  process,  State  is   the   tuple
              {CurrentStateName,  CurrentStateData},  and  NewState  is  a similar tuple that may
              contain a new state name, new state data, or both. For a gen_event  process,  State
              is  the tuple {Module, Id, HandlerState} where Module is the event handler's module
              name, Id is the handler's ID (which is the value false if it was registered without
              an  ID), and HandlerState is the handler's state. NewState is a similar tuple where
              Module and Id shall have the same values as in State but the value of  HandlerState
              may  be different. Returning a NewState whose Module or Id values differ from those
              of State will result in the  event  handler's  state  remaining  unchanged.  For  a
              gen_event process, StateFun is called once for each event handler registered in the
              gen_event process.

              If a StateFun function decides not to effect any  change  in  process  state,  then
              regardless of process type, it may simply return its State argument.

              If  a  StateFun  function  crashes  or throws an exception, then for gen_server and
              gen_fsm processes, the original state of the process is  unchanged.  For  gen_event
              processes, a crashing or failing StateFun function means that only the state of the
              particular event handler it was working on when it failed or crashed is  unchanged;
              it  can  still succeed in changing the states of other event handlers registered in
              the same gen_event process.

       install(Name, FuncSpec) -> ok

       install(Name, FuncSpec, Timeout) -> ok

              Types:

                 Name = name()
                 FuncSpec = {Func, FuncState}
                 Func = dbg_fun()
                 FuncState = term()
                 Timeout = timeout()

              This function makes it possible to install other  debug  functions  than  the  ones
              defined  above.  An  example of such a function is a trigger, a function that waits
              for some special event and performs some action when the event is  generated.  This
              could, for example, be turning on low level tracing.

              Func  is  called  whenever a system event is generated. This function should return
              done, or a new func state. In the first  case,  the  function  is  removed.  It  is
              removed if the function fails.

       remove(Name, Func) -> ok

       remove(Name, Func, Timeout) -> ok

              Types:

                 Name = name()
                 Func = dbg_fun()
                 Timeout = timeout()

              Removes  a  previously  installed debug function from the process. Func must be the
              same as previously installed.

PROCESS IMPLEMENTATION FUNCTIONS

       The following functions are used when implementing a special process. This is an  ordinary
       process  which  does  not  use  a  standard behaviour, but a process which understands the
       standard system messages.

EXPORTS

       debug_options(Options) -> [dbg_opt()]

              Types:

                 Options = [Opt]
                 Opt = trace
                     | log
                     | {log, integer() >= 1}
                     | statistics
                     | {log_to_file, FileName}
                     | {install, FuncSpec}
                 FileName = file:name()
                 FuncSpec = {Func, FuncState}
                 Func = dbg_fun()
                 FuncState = term()

              This function can be used by a process that initiates a debug structure from a list
              of  options.  The  values  of  the  Opt  argument are the same as the corresponding
              functions.

       get_debug(Item, Debug, Default) -> term()

              Types:

                 Item = log | statistics
                 Debug = [dbg_opt()]
                 Default = term()

              This function gets the data associated with a debug option. Default is returned  if
              the  Item  is  not  found.  Can  be  used by the process to retrieve debug data for
              printing before it terminates.

       handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]

              Types:

                 Debug = [dbg_opt()]
                 FormFunc = dbg_fun()
                 Extra = term()
                 Event = system_event()

              This function is called by a process when it generates a system event. FormFunc  is
              a formatting function which is called as FormFunc(Device, Event, Extra) in order to
              print the events, which is necessary if tracing is activated. Extra  is  any  extra
              information which the process needs in the format function, for example the name of
              the process.

       handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
                            no_return()

              Types:

                 Msg = term()
                 From = {pid(), Tag :: term()}
                 Parent = pid()
                 Module = module()
                 Debug = [dbg_opt()]
                 Misc = term()

              This function is used by a process module  that  wishes  to  take  care  of  system
              messages. The process receives a {system, From, Msg} message and passes the Msg and
              From to this function.

              This function never returns. It calls the  function  Module:system_continue(Parent,
              NDebug,    Misc)    where    the    process    continues    the    execution,    or
              Module:system_terminate(Reason,  Parent,  Debug,  Misc)  if  the   process   should
              terminate.  The  Module  must  export  system_continue/3,  system_terminate/4,  and
              system_code_change/4 (see below).

              The Misc argument can be used to save internal data in a process, for  example  its
              state. It is sent to Module:system_continue/3 or Module:system_terminate/4

       print_log(Debug) -> ok

              Types:

                 Debug = [dbg_opt()]

              Prints  the  logged  system events in the debug structure using FormFunc as defined
              when the event was generated by a call to handle_debug/4.

       Mod:system_continue(Parent, Debug, Misc) -> none()

              Types:

                 Parent = pid()
                 Debug = [dbg_opt()]
                 Misc = term()

              This function is  called  from  sys:handle_system_msg/6  when  the  process  should
              continue  its  execution  (for  example after it has been suspended). This function
              never returns.

       Mod:system_terminate(Reason, Parent, Debug, Misc) -> none()

              Types:

                 Reason = term()
                 Parent = pid()
                 Debug = [dbg_opt()]
                 Misc = term()

              This function is  called  from  sys:handle_system_msg/6  when  the  process  should
              terminate.  For  example, this function is called when the process is suspended and
              its parent orders shut-down. It gives the process a chance to do a  clean-up.  This
              function never returns.

       Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}

              Types:

                 Misc = term()
                 OldVsn = undefined | term()
                 Module = atom()
                 Extra = term()
                 NMisc = term()

              Called  from sys:handle_system_msg/6 when the process should perform a code change.
              The code change is used when the internal data structure has changed. This function
              converts  the  Misc argument to the new data structure. OldVsn is the vsn attribute
              of the old version of the Module. If  no  such  attribute  was  defined,  the  atom
              undefined is sent.