1sys(3)                     Erlang Module Definition                     sys(3)
2
3
4

NAME

6       sys - A functional interface to system messages.
7

DESCRIPTION

9       This module contains functions for sending system messages used by pro‐
10       grams, and messages used for debugging purposes.
11
12       Functions used for implementation of processes  are  also  expected  to
13       understand  system  messages,  such  as debug messages and code change.
14       These functions must be used to implement the use  of  system  messages
15       for  a process; either directly, or through standard behaviors, such as
16       gen_server.
17
18       The default time-out is 5000 ms, unless  otherwise  specified.  timeout
19       defines  the  time  to wait for the process to respond to a request. If
20       the process does not respond, the function evaluates exit({timeout, {M,
21       F, A}}).
22
23       The functions make references to a debug structure. The debug structure
24       is a list of dbg_opt(), which is an internal data type used by function
25       handle_system_msg/6. No debugging is performed if it is an empty list.
26

SYSTEM MESSAGES

28       Processes  that  are  not  implemented as one of the standard behaviors
29       must still understand system messages.  The  following  three  messages
30       must be understood:
31
32         * Plain  system  messages. These are received as {system, From, Msg}.
33           The content and meaning of this message are not interpreted by  the
34           receiving  process module. When a system message is received, func‐
35           tion handle_system_msg/6 is called to handle the request.
36
37         * Shutdown messages. If the process traps exits, it must be  able  to
38           handle a shutdown request from its parent, the supervisor. The mes‐
39           sage {'EXIT', Parent, Reason} from the parent is an order to termi‐
40           nate.  The  process  must  terminate when this message is received,
41           normally with the same Reason as Parent.
42
43         * If the modules used to implement  the  process  change  dynamically
44           during  runtime,  the  process must understand one more message. An
45           example is the gen_event processes. The message is {_Label,  {From,
46           Ref},  get_modules}. The reply to this message is From ! {Ref, Mod‐
47           ules}, where Modules is a list of the currently active  modules  in
48           the process.
49
50           This message is used by the release handler to find which processes
51           that execute a certain module. The process can later  be  suspended
52           and ordered to perform a code change for one of its modules.
53

SYSTEM EVENTS

55       When debugging a process with the functions of this module, the process
56       generates system_events, which are then treated in the debug  function.
57       For example, trace formats the system events to the terminal.
58
59       Four predefined system events are used when a process receives or sends
60       a message. The process can also define its own  system  events.  It  is
61       always up to the process itself to format these events.
62

DATA TYPES

64       name() =
65           pid() | atom() | {global, term()} | {via, module(), term()}
66
67       system_event() =
68           {in, Msg :: term()} |
69           {in, Msg :: term(), State :: term()} |
70           {out, Msg :: term(), To :: term()} |
71           {out, Msg :: term(), To :: term(), State :: term()} |
72           {noreply, State :: term()} |
73           {continue, Continuation :: term()} |
74           {code_change, Event :: term(), State :: term()} |
75           {postpone,
76            Event :: term(),
77            State :: term(),
78            NextState :: term()} |
79           {consume,
80            Event :: term(),
81            State :: term(),
82            NextState :: term()} |
83           {start_timer, Action :: term(), State :: term()} |
84           {insert_timeout, Event :: term(), State :: term()} |
85           {enter, State :: term()} |
86           {terminate, Reason :: term(), State :: term()} |
87           term()
88
89                {in,Msg}:
90                  Is produced by gen_server and gen_event when the message Msg
91                  arrives.
92
93                {in,Msg,State}:
94                  Is produced by gen_statem when the message  Msg  arrives  in
95                  state State.
96
97                  For  gen_statem  the Msg term is an {EventType,EventContent}
98                  tuple.
99
100                {out,Msg,To}:
101                  Is produced by gen_statem when the reply Msg is sent back to
102                  To  by  returning  a {reply,To,Msg} action from the callback
103                  module.
104
105                  To  is  of  the  same  type  as  the   first   argument   to
106                  gen_statem:reply/2.
107
108                {out,Msg,To,State}:
109                  Is produced by gen_server when the reply Msg is sent back to
110                  To by returning a {reply,...} tuple from the  callback  mod‐
111                  ule.
112
113                  To   is   of   the  same  type  as  the  first  argument  to
114                  gen_server:reply/2.
115
116                  State is the new server state.
117
118                {noreply,State}:
119                  Is produced by gen_server  when  a  {noreply,...}  tuple  is
120                  returned from the callback module.
121
122                  State is the new server state.
123
124                {continue,Continuation}:
125                  Is  produced  by  gen_server  when a {continue,Continuation}
126                  tuple is returned from the callback module.
127
128                {code_change,Event,State}:
129                  Is produced by gen_statem when the message Event arrives  in
130                  state State as the first event after a code change.
131
132                  Event is an {EventType,EventContent} tuple.
133
134                 {postpone,Event,State,NextState} :
135                  Is  produced  by  gen_statem when the message Event is post‐
136                  poned in state State. NextState is the new state.
137
138                  Event is an {EventType,EventContent} tuple.
139
140                 {consume,Event,State,NextState} :
141                  Is produced by gen_statem when the message Event is consumed
142                  in state State. NextState is the new state.
143
144                  Event is an {EventType,EventContent} tuple.
145
146                 {start_timer,Action,State} :
147                  Is  produced  by  gen_statem when the action Action starts a
148                  timer in state State.
149
150                 {insert_timeout,Event,State} :
151                  Is produced by gen_statem when a timeout zero action inserts
152                  event Event in state State.
153
154                  Event is an {EventType,EventContent} tuple.
155
156                 {enter,State} :
157                  Is  produced  by  gen_statem  when  the first state State is
158                  entered.
159
160                 {terminate,Reason,State} :
161                  Is produced by gen_statem when  it  terminates  with  reason
162                  Reason in state State.
163
164       dbg_opt()
165
166              See the introduction of this manual page.
167
168       dbg_fun() =
169           fun((FuncState :: term(),
170                Event :: system_event(),
171                ProcState :: term()) ->
172                   done | (NewFuncState :: term()))
173
174       debug_option() =
175           trace | log |
176           {log, N :: integer() >= 1} |
177           statistics |
178           {log_to_file, FileName :: file:name()} |
179           {install,
180            {Func :: dbg_fun(), FuncState :: term()} |
181            {FuncId :: term(), Func :: dbg_fun(), FuncState :: term()}}
182
183       format_fun() =
184           fun((Device :: io:device() | file:io_device(),
185                Event :: system_event(),
186                Extra :: term()) ->
187                   any())
188

EXPORTS

190       change_code(Name, Module, OldVsn, Extra) -> ok | {error, Reason}
191
192       change_code(Name, Module, OldVsn, Extra, Timeout) ->
193                      ok | {error, Reason}
194
195              Types:
196
197                 Name = name()
198                 Module = module()
199                 OldVsn = undefined | term()
200                 Extra = term()
201                 Timeout = timeout()
202                 Reason = term()
203
204              Tells  the process to change code. The process must be suspended
205              to handle this message. Argument  Extra  is  reserved  for  each
206              process  to use as its own. Function Module:system_code_change/4
207              is called. OldVsn is the old version of the Module.
208
209       get_state(Name) -> State
210
211       get_state(Name, Timeout) -> State
212
213              Types:
214
215                 Name = name()
216                 Timeout = timeout()
217                 State = term()
218
219              Gets the state of the process.
220
221          Note:
222              These functions are intended only to help with  debugging.  They
223              are  provided for convenience, allowing developers to avoid hav‐
224              ing to create their own  state  extraction  functions  and  also
225              avoid  having to interactively extract the state from the return
226              values of get_status/1 or get_status/2 while debugging.
227
228
229              The value of State varies for different types of  processes,  as
230              follows:
231
232                * For a gen_server process, the returned State is the state of
233                  the callback module.
234
235                * For  a  gen_statem  process,  State  is  the   tuple   {Cur‐
236                  rentState,CurrentData}.
237
238                * For  a  gen_event  process, State is a list of tuples, where
239                  each tuple corresponds to an event handler registered in the
240                  process and contains {Module, Id, HandlerState}, as follows:
241
242                  Module:
243                    The module name of the event handler.
244
245                  Id:
246                    The ID of the handler (which is false if it was registered
247                    without an ID).
248
249                  HandlerState:
250                    The state of the handler.
251
252              If the callback module exports a function system_get_state/1, it
253              is  called  in the target process to get its state. Its argument
254              is the same as the Misc value returned  by  get_status/1,2,  and
255              function  Module:system_get_state/1  is  expected to extract the
256              state  of  the  callback   module   from   it.   Function   sys‐
257              tem_get_state/1  must  return  {ok,  State},  where State is the
258              state of the callback module.
259
260              If the callback module  does  not  export  a  system_get_state/1
261              function, get_state/1,2 assumes that the Misc value is the state
262              of the callback module and returns it directly instead.
263
264              If the callback module's system_get_state/1 function crashes  or
265              throws   an  exception,  the  caller  exits  with  error  {call‐
266              back_failed, {Module, system_get_state}, {Class, Reason}}, where
267              Module  is  the name of the callback module and Class and Reason
268              indicate details of the exception.
269
270              Function system_get_state/1 is primarily useful for user-defined
271              behaviors  and modules that implement OTP special processes. The
272              gen_server,  gen_statem,  and  gen_event  OTP  behavior  modules
273              export  this  function,  so callback modules for those behaviors
274              need not to supply their own.
275
276              For more information about a process, including its  state,  see
277              get_status/1 and get_status/2.
278
279       get_status(Name) -> Status
280
281       get_status(Name, Timeout) -> Status
282
283              Types:
284
285                 Name = name()
286                 Timeout = timeout()
287                 Status =
288                     {status,  Pid  ::  pid(),  {module,  Module :: module()},
289                 [SItem]}
290                 SItem =
291                     (PDict :: [{Key :: term(), Value :: term()}]) |
292                     (SysState :: running | suspended) |
293                     (Parent :: pid()) |
294                     (Dbg :: [dbg_opt()]) |
295                     (Misc :: term())
296
297              Gets the status of the process.
298
299              The value of Misc varies for different types of  processes,  for
300              example:
301
302                * A  gen_server process returns the state of the callback mod‐
303                  ule.
304
305                * A gen_statem process returns information, such as  its  cur‐
306                  rent state name and state data.
307
308                * A  gen_event  process  returns information about each of its
309                  registered handlers.
310
311              Callback modules for gen_server, gen_statem, and  gen_event  can
312              also  change  the  value  of  Misc  by exporting a function for‐
313              mat_status/2, which contributes module-specific information. For
314              details,  see gen_server:format_status/2, gen_statem:format_sta‐
315              tus/2, and gen_event:format_status/2.
316
317       install(Name, FuncSpec) -> ok
318
319       install(Name, FuncSpec, Timeout) -> ok
320
321              Types:
322
323                 Name = name()
324                 FuncSpec = {Func, FuncState} | {FuncId, Func, FuncState}
325                 FuncId = term()
326                 Func = dbg_fun()
327                 FuncState = term()
328                 Timeout = timeout()
329
330              Enables installation of alternative debug functions. An  example
331              of  such a function is a trigger, a function that waits for some
332              special event and performs some action when the event is  gener‐
333              ated. For example, turning on low-level tracing.
334
335              Func  is called whenever a system event is generated. This func‐
336              tion is to return done, or a new Func state. In the first  case,
337              the  function  is  removed.  It  is also removed if the function
338              fails. If one debug function should be installed more  times,  a
339              unique FuncId must be specified for each installation.
340
341       log(Name, Flag) -> ok | {ok, [system_event()]}
342
343       log(Name, Flag, Timeout) -> ok | {ok, [system_event()]}
344
345              Types:
346
347                 Name = name()
348                 Flag  =  true  |  {true, N :: integer() >= 1} | false | get |
349                 print
350                 Timeout = timeout()
351
352              Turns the logging of system events on or off. If on,  a  maximum
353              of N events are kept in the debug structure (default is 10).
354
355              If Flag is get, a list of all logged events is returned.
356
357              If Flag is print, the logged events are printed to standard_io.
358
359              The  events are formatted with a function that is defined by the
360              process  that  generated  the  event  (with  a  call   to   han‐
361              dle_debug/4).
362
363       log_to_file(Name, Flag) -> ok | {error, open_file}
364
365       log_to_file(Name, Flag, Timeout) -> ok | {error, open_file}
366
367              Types:
368
369                 Name = name()
370                 Flag = (FileName :: string()) | false
371                 Timeout = timeout()
372
373              Enables  or  disables  the  logging of all system events in text
374              format to the file. The events are  formatted  with  a  function
375              that  is defined by the process that generated the event (with a
376              call to handle_debug/4). The file is opened with encoding UTF-8.
377
378       no_debug(Name) -> ok
379
380       no_debug(Name, Timeout) -> ok
381
382              Types:
383
384                 Name = name()
385                 Timeout = timeout()
386
387              Turns off all debugging for the process. This includes functions
388              that  are  installed  explicitly  with function install/2,3, for
389              example, triggers.
390
391       remove(Name, FuncOrFuncId :: Func | FuncId) -> ok
392
393       remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok
394
395              Types:
396
397                 Name = name()
398                 Func = dbg_fun()
399                 FuncId = term()
400                 Timeout = timeout()
401
402              Removes an installed debug function from the  process.  Func  or
403              FuncId must be the same as previously installed.
404
405       replace_state(Name, StateFun) -> NewState
406
407       replace_state(Name, StateFun, Timeout) -> NewState
408
409              Types:
410
411                 Name = name()
412                 StateFun = fun((State :: term()) -> NewState :: term())
413                 Timeout = timeout()
414                 NewState = term()
415
416              Replaces the state of the process, and returns the new state.
417
418          Note:
419              These  functions  are  intended only to help with debugging, and
420              are not to be called from normal code.  They  are  provided  for
421              convenience, allowing developers to avoid having to create their
422              own custom state replacement functions.
423
424
425              Function StateFun provides a new state for the process. Argument
426              State and the NewState return value of StateFun vary for differ‐
427              ent types of processes as follows:
428
429                * For a gen_server process, State is the state of the callback
430                  module and NewState is a new instance of that state.
431
432                * For   a   gen_statem  process,  State  is  the  tuple  {Cur‐
433                  rentState,CurrentData}, and NewState  is  a  similar  tuple,
434                  which  can  contain  a new current state, new state data, or
435                  both.
436
437                * For a gen_event process, State is  the  tuple  {Module,  Id,
438                  HandlerState} as follows:
439
440                  Module:
441                    The module name of the event handler.
442
443                  Id:
444                    The ID of the handler (which is false if it was registered
445                    without an ID).
446
447                  HandlerState:
448                    The state of the handler.
449
450                  NewState is a similar tuple where Module and Id are to  have
451                  the  same  values as in State, but the value of HandlerState
452                  can be different. Returning a NewState, whose Module  or  Id
453                  values  differ  from those of State, leaves the state of the
454                  event handler unchanged. For a gen_event  process,  StateFun
455                  is  called  once  for  each  event handler registered in the
456                  gen_event process.
457
458              If a StateFun function decides  not  to  effect  any  change  in
459              process  state,  then  regardless of process type, it can return
460              its State argument.
461
462              If a StateFun function crashes or throws an exception, the orig‐
463              inal  state  of  the  process  is  unchanged for gen_server, and
464              gen_statem processes. For gen_event  processes,  a  crashing  or
465              failing  StateFun function means that only the state of the par‐
466              ticular event handler it  was  working  on  when  it  failed  or
467              crashed  is  unchanged;  it  can  still  succeed in changing the
468              states of other event handlers registered in the same  gen_event
469              process.
470
471              If  the  callback  module exports a system_replace_state/2 func‐
472              tion, it is called in the target process to  replace  its  state
473              using  StateFun.  Its two arguments are StateFun and Misc, where
474              Misc is the same as the Misc value returned by get_status/1,2. A
475              system_replace_state/2  function is expected to return {ok, New‐
476              State, NewMisc}, where NewState is the new state of the callback
477              module,  obtained by calling StateFun, and NewMisc is a possibly
478              new value used to replace the original Misc  (required  as  Misc
479              often contains the state of the callback module within it).
480
481              If  the callback module does not export a system_replace_state/2
482              function, replace_state/2,3 assumes that Misc is  the  state  of
483              the  callback  module, passes it to StateFun and uses the return
484              value as both the new state and as the new value of Misc.
485
486              If the callback module's function system_replace_state/2 crashes
487              or  throws  an  exception,  the  caller  exits with error {call‐
488              back_failed, {Module, system_replace_state},  {Class,  Reason}},
489              where  Module  is  the name of the callback module and Class and
490              Reason indicate details of the exception. If the callback module
491              does  not provide a system_replace_state/2 function and StateFun
492              crashes or throws an exception,  the  caller  exits  with  error
493              {callback_failed, StateFun, {Class, Reason}}.
494
495              Function  system_replace_state/2  is  primarily useful for user-
496              defined behaviors and modules that implement  OTP  special  pro‐
497              cesses.  The  OTP  behavior  modules gen_server, gen_statem, and
498              gen_event export this function, so callback  modules  for  those
499              behaviors need not to supply their own.
500
501       resume(Name) -> ok
502
503       resume(Name, Timeout) -> ok
504
505              Types:
506
507                 Name = name()
508                 Timeout = timeout()
509
510              Resumes a suspended process.
511
512       statistics(Name, Flag) -> ok | {ok, Statistics}
513
514       statistics(Name, Flag, Timeout) -> ok | {ok, Statistics}
515
516              Types:
517
518                 Name = name()
519                 Flag = true | false | get
520                 Statistics = [StatisticsTuple] | no_statistics
521                 StatisticsTuple =
522                     {start_time, DateTime1} |
523                     {current_time, DateTime2} |
524                     {reductions, integer() >= 0} |
525                     {messages_in, integer() >= 0} |
526                     {messages_out, integer() >= 0}
527                 DateTime1 = DateTime2 = file:date_time()
528                 Timeout = timeout()
529
530              Enables  or  disables  the  collection of statistics. If Flag is
531              get, the statistical collection is returned.
532
533       suspend(Name) -> ok
534
535       suspend(Name, Timeout) -> ok
536
537              Types:
538
539                 Name = name()
540                 Timeout = timeout()
541
542              Suspends the process. When the process  is  suspended,  it  only
543              responds to other system messages, but not other messages.
544
545       terminate(Name, Reason) -> ok
546
547       terminate(Name, Reason, Timeout) -> ok
548
549              Types:
550
551                 Name = name()
552                 Reason = term()
553                 Timeout = timeout()
554
555              Orders  the  process to terminate with the specified Reason. The
556              termination is done asynchronously, so it is not guaranteed that
557              the process is terminated when the function returns.
558
559       trace(Name, Flag) -> ok
560
561       trace(Name, Flag, Timeout) -> ok
562
563              Types:
564
565                 Name = name()
566                 Flag = boolean()
567                 Timeout = timeout()
568
569              Prints  all system events on standard_io. The events are format‐
570              ted with a function that is defined by the process  that  gener‐
571              ated the event (with a call to handle_debug/4).
572

PROCESS IMPLEMENTATION FUNCTIONS

574       The  following  functions are used when implementing a special process.
575       This is an ordinary process, which does not use  a  standard  behavior,
576       but a process that understands the standard system messages.
577

EXPORTS

579       debug_options(Options :: [Opt :: debug_option()]) -> [dbg_opt()]
580
581              Can be used by a process that initiates a debug structure from a
582              list of options. The values of argument Opt are the same as  for
583              the corresponding functions.
584
585       get_debug(Item, Debug, Default) -> term()
586
587              Types:
588
589                 Item = log | statistics
590                 Debug = [dbg_opt()]
591                 Default = term()
592
593          Warning:
594              get_debug/3  is  deprecated since it returns data of an internal
595              type only useful for debugging.
596
597
598              Gets the  data  associated  with  a  debug  option.  Default  is
599              returned  if  Item  is  not found. Can be used by the process to
600              retrieve debug data for printing before it terminates.
601
602       handle_debug(Debug, FormFunc, Extra, Event) -> [dbg_opt()]
603
604              Types:
605
606                 Debug = [dbg_opt()]
607                 FormFunc = format_fun()
608                 Extra = term()
609                 Event = system_event()
610
611              This function is called by a process when it generates a  system
612              event.  FormFunc  is  a  formatting  function,  called  as Form‐
613              Func(Device, Event, Extra) to print the events, which is  neces‐
614              sary  if  tracing  is  activated. Extra is any extra information
615              that the process needs in the format function, for example,  the
616              process name.
617
618       handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
619                            no_return()
620
621              Types:
622
623                 Msg = term()
624                 From = {pid(), Tag :: term()}
625                 Parent = pid()
626                 Module = module()
627                 Debug = [dbg_opt()]
628                 Misc = term()
629
630              This function is used by a process module to take care of system
631              messages. The process receives a {system, From, Msg} message and
632              passes Msg and From to this function.
633
634              This  function  never  returns. It calls either of the following
635              functions:
636
637                * Module:system_continue(Parent,  NDebug,  Misc),  where   the
638                  process continues the execution.
639
640                * Module:system_terminate(Reason, Parent, Debug, Misc), if the
641                  process is to terminate.
642
643              Module must export the following:
644
645                * system_continue/3
646
647                * system_terminate/4
648
649                * system_code_change/4
650
651                * system_get_state/1
652
653                * system_replace_state/2
654
655              Argument Misc can be used to save internal data  in  a  process,
656              for  example,  its state. It is sent to Module:system_continue/3
657              or Module:system_terminate/4.
658
659       print_log(Debug) -> ok
660
661              Types:
662
663                 Debug = [dbg_opt()]
664
665              Prints the logged system events in the  debug  structure,  using
666              FormFunc  as  defined  when the event was generated by a call to
667              handle_debug/4.
668
669       get_log(Debug) -> [system_event()]
670
671              Types:
672
673                 Debug = [dbg_opt()]
674
675              Returns the logged system events in the debug structure, that is
676              the last argument to handle_debug/4.
677
678       Module:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}
679
680              Types:
681
682                 Misc = term()
683                 OldVsn = undefined | term()
684                 Module = atom()
685                 Extra = term()
686                 NMisc = term()
687
688              Called from handle_system_msg/6 when the process is to perform a
689              code change. The code change is  used  when  the  internal  data
690              structure  has  changed. This function converts argument Misc to
691              the new data structure. OldVsn is attribute vsn of the old  ver‐
692              sion  of  the  Module. If no such attribute is defined, the atom
693              undefined is sent.
694
695       Module:system_continue(Parent, Debug, Misc) -> none()
696
697              Types:
698
699                 Parent = pid()
700                 Debug = [dbg_opt()]
701                 Misc = term()
702
703              Called from handle_system_msg/6 when the process is to  continue
704              its  execution  (for example, after it has been suspended). This
705              function never returns.
706
707       Module:system_get_state(Misc) -> {ok, State}
708
709              Types:
710
711                 Misc = term()
712                 State = term()
713
714              Called from handle_system_msg/6 when the process is to return  a
715              term  that  reflects  its  current  state.  State  is  the value
716              returned by get_state/2.
717
718       Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}
719
720              Types:
721
722                 StateFun = fun((State :: term()) -> NState)
723                 Misc = term()
724                 NState = term()
725                 NMisc = term()
726
727              Called from handle_system_msg/6 when the process is  to  replace
728              its   current   state.   NState   is   the   value  returned  by
729              replace_state/3.
730
731       Module:system_terminate(Reason, Parent, Debug, Misc) -> none()
732
733              Types:
734
735                 Reason = term()
736                 Parent = pid()
737                 Debug = [dbg_opt()]
738                 Misc = term()
739
740              Called from handle_system_msg/6 when the process  is  to  termi‐
741              nate.  For  example, this function is called when the process is
742              suspended and its parent orders shutdown. It gives the process a
743              chance to do a cleanup. This function never returns.
744
745
746
747Ericsson AB                      stdlib 3.14.1                          sys(3)
Impressum