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 un‐
13       derstand system messages, such as debug messages and code change. These
14       functions must be used to implement the use of system  messages  for  a
15       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 al‐
61       ways 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           {postpone,
75            Event :: term(),
76            State :: term(),
77            NextState :: term()} |
78           {consume,
79            Event :: term(),
80            State :: term(),
81            NextState :: term()} |
82           {start_timer, Action :: term(), State :: term()} |
83           {insert_timeout, Event :: term(), State :: term()} |
84           {enter, Module :: module(), State :: term()} |
85           {module, Module :: module(), 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  re‐
120                  turned 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} tu‐
126                  ple is returned from the callback module.
127
128                 {postpone,Event,State,NextState} :
129                  Is produced by gen_statem when the message  Event  is  post‐
130                  poned in state State. NextState is the new state.
131
132                  Event is an {EventType,EventContent} tuple.
133
134                 {consume,Event,State,NextState} :
135                  Is produced by gen_statem when the message Event is consumed
136                  in state State. NextState is the new state.
137
138                  Event is an {EventType,EventContent} tuple.
139
140                 {start_timer,Action,State} :
141                  Is produced by gen_statem when the action  Action  starts  a
142                  timer in state State.
143
144                 {insert_timeout,Event,State} :
145                  Is produced by gen_statem when a timeout zero action inserts
146                  event Event in state State.
147
148                  Event is an {EventType,EventContent} tuple.
149
150                 {enter,Module,State} :
151                  Is produced by gen_statem  when  module  Module  enters  the
152                  first state State.
153
154                 {module,Module,State} :
155                  Is  produced  by  gen_statem  when  setting module Module in
156                  state State.
157
158                 {terminate,Reason,State} :
159                  Is produced by gen_statem when  it  terminates  with  reason
160                  Reason in state State.
161
162       dbg_opt()
163
164              See the introduction of this manual page.
165
166       dbg_fun() =
167           fun((FuncState :: term(),
168                Event :: system_event(),
169                ProcState :: term()) ->
170                   done | (NewFuncState :: term()))
171
172       debug_option() =
173           trace | log |
174           {log, N :: integer() >= 1} |
175           statistics |
176           {log_to_file, FileName :: file:name()} |
177           {install,
178            {Func :: dbg_fun(), FuncState :: term()} |
179            {FuncId :: term(), Func :: dbg_fun(), FuncState :: term()}}
180
181       format_fun() =
182           fun((Device :: io:device() | file:io_device(),
183                Event :: system_event(),
184                Extra :: term()) ->
185                   any())
186

EXPORTS

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

PROCESS IMPLEMENTATION FUNCTIONS

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

EXPORTS

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