1 02/13/84  ring_zero_peek_
  2 
  3 The ring_zero_peek_ subroutine is used to copy information out of an
  4 inner ring segment.  The user must have access to either the phcs_ gate
  5 or the metering_ring_zero_peek_ gate in order to use any of the entry
  6 points in this subroutine.  The phcs_ gate allows unrestricted access
  7 to all inner ring segments; metering_ring_zero_peek_ allows the user to
  8 examine specifically those data bases that are useful for metering the
  9 system.  The program chooses the appropriate gate depending on the
 10 user's access and the segments being examined.
 11 
 12 
 13 Entry points in ring_zero_peek_:
 14    (List is generated by the help command)
 15 
 16 
 17 :Entry: ring_zero_peek_: 02/13/84 ring_zero_peek_
 18 
 19 Function: copies information out of a segment in the Multics
 20 supervisor, given a pointer to it.
 21 
 22 
 23 Syntax:
 24 declare ring_zero_peek_ entry (ptr, ptr, fixed bin(19), fixed bin(35));
 25 call ring_zero_peek_ (ptr0, ptr_user, nwords, code);
 26 
 27 
 28 Arguments:
 29 ptr0
 30    is a pointer to the data in ring 0 that is to be copied out.
 31    (Input)
 32 ptr_user
 33    is a pointer to the region in the user's address space where the
 34    data is to be copied.  (Input)
 35 nwords
 36    is the number of words to be copied.  (Input)
 37 code
 38    is the standard status code that is nonzero if the user did not have
 39    access to the requested data.  (Output)
 40 
 41 
 42 :Entry:  by_definition:  02/13/84 ring_zero_peek_$by_definition
 43 
 44 
 45 Function: copies information out of a named segment in the Multics
 46 supervisor, starting at a named symbol.  It is like
 47 ring_zero_peek_$by_name, except that the copying is done from the
 48 specified definition, rather than from the base of the segment.
 49 
 50 
 51 Syntax:
 52 declare ring_zero_peek_$by_definition entry (char(*), char(*),
 53      fixed bin(18), pointer, fixed bin(19), fixed bin(35));
 54 call ring_zero_peek_$by_definition (segment_name, symbol_name, offset,
 55      ptr_user, word_count, code);
 56 
 57 
 58 Arguments:
 59 segment_name
 60    is the name of the supervisor segment from which words are to be
 61    copied.  (Input).  It cannot be a pathname.
 62 symbol_name
 63    is the name of the external symbol in the specified segment at which
 64    copying is to start.  (Input)
 65 offset
 66    is the offset from the specified definition at which copying is to
 67    start.  (Input).  It can be specified as zero to cause copying to
 68    start at the specified definition.
 69 
 70 
 71 ptr_user
 72    is a pointer to the area in the outer ring where the data is to be
 73    copied.  (Input)
 74 word_count
 75    is the number of words to be copied.  (Input)
 76 code
 77    is a standard status code.  (Output).  It is nonzero if the segment
 78    cannot be found, if the specified external symbol does not exist or
 79    is ambiguous, or if the user does not have sufficient access to copy
 80    the requested data.
 81 
 82 
 83 Notes:  This entry point can be used to avoid a call to ring0_get_.
 84 For examining segments in the supervisor, this entry point and the
 85 by_name entry point are recommended because they are much simpler
 86 to use than ring0_get_, and they are only minimally less efficient.
 87 Generally, it is nearly as efficient to use this entry point as it is
 88 to save static pointers to inner ring objects.
 89 
 90 
 91 :Entry:  by_name:  02/13/84 ring_zero_peek_$by_name
 92 
 93 
 94 Function: copies information out of a named segment in the Multics
 95 supervisor.  It is like ring_zero_peek_, except that the name of the
 96 ring zero segment is provided, rather than a pointer to it.
 97 
 98 
 99 Syntax:
100 declare ring_zero_peek_$by_name entry (char(*), fixed bin(18), pointer,
101      fixed bin(19), fixed bin(35));
102 call ring_zero_peek_$by_name (segment_name, offset, copy_ptr,
103      word_count, code);
104 
105 
106 Arguments:
107 segment_name
108    is the name of the supervisor segment from which data is to be
109    copied.  It cannot be a pathname.  (Input)
110 offset
111    is the offset from the beginning of the segment at which copying is
112    to start.  (Input).  It can be specified as zero to cause copying to
113    start from the base of the segment.
114 copy_ptr
115    is a pointer to the area in the outer ring where the data is to be
116    copied.  (Input)
117 
118 
119 word_count
120    is the number of words to be copied.  (Input)
121 code
122    is a standard status code.  (Output).  It is nonzero if the segment
123    cannot be found, or if the user does not have sufficient access to
124    copy the requested data from it.
125 
126 
127 Notes:  This entry point can be used to avoid a call to ring0_get_.
128 For examining segments in the supervisor, this entry point and the
129 by_definition entry point are recommended because they are much simpler
130 to use than ring0_get_, and they are only minimally less efficient.
131 Generally, it is nearly as efficient to use this entry point as it is
132 to save static pointers to inner ring objects.
133 
134 
135 :Entry:  get_max_length:  02/13/84 ring_zero_peek_$get_max_length
136 
137 
138 Function: determines the maximum length of a named ring zero segment.
139 
140 
141 Syntax:
142 declare ring_zero_peek_$get_max_length entry (char(*), fixed bin(19),
143      fixed bin(35));
144 call ring_zero_peek_$get_max_length (seg_name, max_length, code);
145 
146 
147 Arguments:
148 seg_name
149    is the name of the ring zero segment.  (Input)
150 max_length
151    is the maximum length (in words) of the segment.  (Output)
152 code
153    is a standard status code.  (Output).  It is nonzero if the user
154    does not have sufficient access to copy the requested data, or if
155    the segment does not exist.
156 
157 
158 :Entry:  get_max_length_ptr:
159 02/13/84 ring_zero_peek_$get_max_length_ptr
160 
161 
162 Function: determines the maximum length of a specified segment by
163 examining its SDW.  The user must have sufficient access to examine
164 the SDW for the segment.
165 
166 
167 Syntax:
168 declare ring_zero_peek_$get_max_length_ptr entry (pointer,
169      fixed bin(19), fixed bin(35));
170 call ring_zero_peek_$get_max_length_ptr (seg_ptr, max_length, code);
171 
172 
173 Arguments:
174 seg_ptr
175    is a pointer to the segment for which the max length is to be
176    returned.  (Input).  If the segment is not active at the time of the
177    call, the user must have sufficient access to reference the segment,
178    and this reference causes a segment fault.
179 max_length
180    is the maximum length (in words) of the segment.  (Output)
181 code
182    is a standard status code.  (Output).  It is nonzero if the user
183    does not have sufficient access to copy the requested data, or if
184    the segment does not exist.