10/17/84  sample_refs

Syntax as a command:  sample_refs -control_args


Function:  periodically samples the machine registers to determine
which segments a process is referencing.  Three output segments are
produced that are interpretable by the print_sample_refs command.


Control arguments:
-segment name, -sm name
   specifies the names to be given the three output segments; name can
   be either an absolute or relative pathname.  If name does not end
   with the suffix srf, it is assumed.  The output segments are named
   as follows:
      (entry portion of) name.srf1
      (entry portion of) name.srf2
      (entry portion of) name.srf3


   The default places the output segments in your working directory,
   with entrynames as follows:
      mm/dd/yy__hhmm.m_zzz_www.srf1
      mm/dd/yy__hhmm.m_zzz_www.srf2
      mm/dd/yy__hhmm.m_zzz_www.srf3
-time N, -tm N
   specifies the rate in milliseconds at which the process is sampled.
   N must be a positive integer.  (Default: N = 1000; i.e., the
   process is sampled once every second)


Notes:  You are allowed one active invocation per process--a second
invocation terminates the first, whereupon the new invocation proceeds
normally.

You can sample the machine registers only when the process is running
in a ring other than 0.  For example, a process using a total of 100
seconds of processor time and sample_refs running at the default sample
rate and recording 23 samples indicate that 77 seconds of processor
time were spent in ring 0.

Under certain conditions, the contents of one of the machine registers
sampled--the Temporary Segment Register (TSR)--can be invalid.  This
invalidity is noted, but does not necessarily indicate that the process
is in error.


At the maximum sample rate (one millisecond) execution time can be
increased by as much as 50 percent.  Using a one-second sample rate,
the increase in execution time is negligible.

The accuracy of sample rates less than 1000 milliseconds is not
guaranteed due to load factors.  The accuracy of such sample rates
increases with load.

If the process being sampled is terminated without an invocation of
sample_refs with the -reset option, interpretable output segments are
still produced; however, both the off-time and the last recorded sample
may be invalid.


                                          -----------------------------------------------------------


Historical Background

This edition of the Multics software materials and documentation is provided and donated
to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. 
as a contribution to computer science knowledge.  
This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology,
Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL
and BULL HN Information Systems Inc. to the development of this operating system. 
Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970),
renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership
of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture 
for managing computer hardware properly and for executing programs. Many subsequent operating systems 
incorporated Multics principles.
Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., 
as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. .

                                          -----------------------------------------------------------

Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without
fee is hereby granted,provided that the below copyright notice and historical background appear in all copies
and that both the copyright notice and historical background and this permission notice appear in supporting
documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining
to distribution of the programs without specific prior written permission.
    Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc.
    Copyright 2006 by BULL HN Information Systems Inc.
    Copyright 2006 by Bull SAS
    All Rights Reserved