Guardian Procedure Calls Reference Manual

instance of segmentInfo, and passing as version the segmentInfoVn enumerator defined
in segmentInfoVersion. The initial contents of *info are undefined, except as explained
below for info->segID and info->verifier when the segID parameter is nullSegID.
• If the procedure returns SEGMENT_OK (O) or SEGMENT_FILE_ERROR (1), it fills in all the
accessible members of info. If it returns any other error, it makes no assignment to info.
• Two levels of version checking are defined:
The high-order portion of the version value must match the implementation; it would
change if the structure were to change in an incompatible way.
◦
◦ The low-order portion (version & segmentInfoSizeMask) must be at least 80. If
the structure changes by adding members at the end, the implementation continues to
support the earlier version by returning only as many members as fit into the structure as
defined by the earlier version.
The implemented version is reported in info->reportedVersion.
• To examine a particular segment, pass its segment ID as the segID parameter. If the ID is
reserved (outside the range users can assign), and the caller is not privileged, the procedure
returns SEGMENT_ILLEGALID (4). A privileged caller can pass a reserved ID; if it is not unique,
the first segment found with matching ID is reported.
• To iterate through and report all the segments having assigned IDs:
To start the iterations and report the first segment, assign nullSegID to info->segID
and pass nullSegID as the segID parameter.
◦
◦ To continue iterating (report the next segment), leaveinfo->segID unchanged, and
again pass nullSegID as the segID parameter. nullSegID is defined
as((segid-t)-1).
If there is no segment to report (none at the first iteration or no more at a subsequent iteration),
the procedure returns 0 (SEGMENT_OK) having set info->segID to nullSegID; other
info members have undefined values. However, if info->segID is not nullSegID and
the designated segment does not exist, the procedure returns SEGMENT_NOTFOUND (5);
further iteration is impossible. This error situation can arise if the segment was deallocated
between iterations (or if the caller changes info->segID between calls).
When the target process is different from the current process, info->verifier is used to
determine that the process associated with the PIN parameter did not change between
iterations. That datum is initialized on the first iteration (when info->segID is nullSegID),
and then examined on each subsequent iteration. Therefore, the caller must not skip the first
iteration, and must not alter info->verifier between iterations; violation of this protocol can
lead to spurious failure with error SEGMENT_PIN_REUSED (17). This check does not occur if
the info parameter and associated version value do not include space for a verifier.
• To retrieve the file name of the swap file backing the segment, pass
segmentInfoGetFileName to the options parameter. The procedure sets
info->fileNameLen to the length of the file name in bytes and puts the file name into
info->fileName as a NUL terminated string.
If the file name is not requested, or the segment is not file-backed, or an error occurred retrieving
the file name, nothing is reported (info->fileNameLen = 0,info->fileNameLen[0]=
NUL).
• The procedure reports in info->numDataSegs the number of segments in this process that
have IDs assigned (as they were allocated or shared into the process). It includes OSS shared
segments (but does not include the PFS)
1294 Guardian Procedure Calls (S)