'\"macro stdmacro
'\"
'\" (C) COPYRIGHT SILICON GRAPHICS, INC.
'\" UNPUBLISHED PROPRIETARY INFORMATION.
'\" ALL RIGHTS RESERVED.
'\"
.TH SYSGET 2
.SH NAME
\*Csysget\*E \- Call for reading or writing kernel data
.SH SYNOPSIS
\*C#include <sys/sysget.h>\*E
.PP
\*Csysget
(int\ \*Vname\*C,
char\ *\*Vbuffer\*C,
int\ \*Vbuflen\*C,
int\ \*Vflags\*C,
sgt_cookie_t\ *\*Vcookie\*C);\*E
.SH DESCRIPTION
The \*Csysget\*E system call provides user access
to kernel structures and tables on Cellular and NON-Cellular IRIX systems.
\*Csysget\*E can return data for a combination of cpus, nodes, or cells
depending on the combination of \*Vflags\*C and \*Vcookie\*C settings.
.PP
The \*Csysget\*E system call accepts the following arguments:
.TP 8
\*Vname\*E
Identifies the kernel structure or table.
The \*Csys/sysget.h\*E file contains
the list of names supported.  Most come from the \*Csysmp\*E MP_SAGET options.
Here is a partial list:
.RS 8
.TP 13
\*CSGT_SINFO\*E
\*CSGT_MINFO\*E
\*CSGT_DINFO\*E
\*CSGT_SERR\*E
Returns the various sysinfo-type structures.
See the \%sys/sysinfo.h\*E file.
.TP
\*CSGT_RMINFO\*E
Returns the rminfo structure.
See the \%sys/sysmp.h\*E file.
.TP
\*CSGT_NODE_INFO\*E
Returns the nodeinfo structure for each node.
See the \%sys/sysinfo.h\*E file.
.TP
\*CSGT_KSYM\*E
Returns the structure identified by the kernel symbol specified in the cookie
by using the \*CSGT_COOKIE_SET_KSYM()\*E macro. 
Only a subset of kernel symbols are supported. See the \%sys/sysget.h\*E file.
.RE
.TP 8
\*Vbuffer\*E
Points to the user's buffer space.
.TP
\*Vbuflen\*E
Specifies the size of \*Vbuffer\*E in bytes.
.TP
\*Vflags\*E
Specifies option flags.
A user must select the \*CSGT_INFO\*E, \*CSGT_READ\*E, or \*CSGT_WRITE\*E flag.
\*Vflags\*E is combination of one or more of the following:
.RS 8
.TP 13
\*CSGT_INFO\*E
Returns information on the kernel structure or table
defined by the \*Vname\*E argument. This option is similar to
the \*Csysmp\*E MP_SASZ option.
.SP
The \*Vbuffer\*E argument points to a structure defined
in the \*Csys/sysget.h\*E file as the following:
.ES

 struct sgt_info {
       int      si_size;      
       int      si_num;      
       int      si_hiwater; 
 }
.EE
.TP
\*CSGT_READ\*E
Returns the information defined by the \*Vname\*E argument
in the buffer specified by the \*Vbuffer\*E argument.
.TP
\*CSGT_STAT\*E
Returns information about the table or server
specified by the \*Vname\*E argument.
This information is similar to that provided by the \*CSGT_INFO\*E flag.
.TP
\*CSGT_SUM\*E
Retrieves one structure that is the sum from all cells.  On a NON-cell system
this flag is ignored.
.IP
This option eliminates the need for the user to have a large buffer space
or from having to make multiple calls to retrieve all the structures.
Not all structures support this option.
.TP
\*CSGT_WRITE\*E
Writes the information specified by the \*Vbuffer\*E argument
to the kernel structure defined by the \*Vname\*E argument.
.TP
\*CSGT_CPUS\*E
Returns data for each cpu.  Not all structures support this option.
.TP
\*CSGT_NODES\*E
Returns data for each node.  Not all structures support this option.
.RE
.TP 8
\*Vcookie\*E
Specifies which cell, cpu, or node should be used
when asking for information.  The kernel also uses it as a place-holder
mechanism to allow sysget to be used iteratively to return a list of structures
when the length of the list is unknown. Other uses are to specify a
specific location to seek to in a list.
.IP
This argument points to a structure defined as follows:
.RS
.ES

 struct sgt_cookie {
        sc_status_t    sc_status;
        union {
                cell_t          cellid;
                cnodeid_t       cnodeid;
                int             cpuid;
        } sc_id;
        sc_type_t       sc_type;
        char            sc_opaque[SGT_OPAQUE_SZ];
 }
.EE
.RE
.IP
The \*Vcookie\*E must be initialized before the first call by using
the \*CSGT_COOKIE_INIT()\*E macro.  See the \%sys/sysget.h\*E file
.SH RETURN VALUES
If \*Csysget\*E completes normally,
the number of bytes copied is returned,
otherwise a value of \%\-1 is returned
and \*Cerrno\*E is set to indicate the error.
.SH ERRORS
The \*Csysget\*E system call fails
if one of the following error conditions occurs:
.TP 20
\*BError Code\*E
\*BDescription\*E
.TP
\*CEFAULT\*E
The buffer address specified is not valid.
.TP
\*CEINVAL\*E
A flag was specified in a context that was not valid
or the cookie was not set properly.
.TP
\*CENOENT\*E
The value specified in the \*Vname\*E argument or in combination with
the cookie is unknown.
.TP
\*CENOTSUP\*E
The function specified by the \*Vflags\*E parameter is not supported.
.TP
\*CEPERM\*E
The caller does not have permission to access the value
specified by the \*Vname\*E argument.
.SH EXAMPLES
The following examples show
how to use the \*Csysget\*E system call to retrieve information.
.PP
Example 1:
This example shows how to use \*Csysget\*E to obtain the number and size
of sysinfo structures in the system (a system running cells will have a
sysinfo structure per cell):
.ES

   sgt_info_t info;
   sgt_cookie_t cookie;

   SGT_COOKIE_INIT(&cookie);
   sysget(SGT_SINFO, (char *)&info, sizeof(info),
           SGT_INFO, &cookie);
   printf("number of sysinfo: %d, size: %d\\n",
           info.si_num, info.si_size);
.EE
.PP
Example 2:
In this example, \*Csysget\*E reads the list of sysinfo structures for
each cpu:
.ES

   sgt_info_t info;
   sgt_cookie_t cookie;
   struct sysinfo *si;

   SGT_COOKIE_INIT(&cookie);
   sysget(SGT_SINFO, (char *)&info, sizeof(info),
           SGT_INFO | SGT_CPUS, &cookie);

   si = (struct sysinfo *)malloc(info.si_num * info.si_size);

   SGT_COOKIE_INIT(&cookie);
   sysget(SGT_SINFO, (char *)si, info.si_num * info.si_size,
           SGT_READ | SGT_CPUS, &cookie);
.EE
.PP
Example 3:
In this example, \*Csysget\*E reads the list of sysinfo structures for
each cpu one at a time by iterating on the cookie:
.ES

   sgt_info_t info;
   sgt_cookie_t cookie;
   struct sysinfo si;

   SGT_COOKIE_INIT(&cookie);
   while (cookie.sc_status != SC_DONE) {
          sysget(SGT_SINFO, (char *)&si, sizeof(si),
              SGT_READ | SGT_CPUS, &cookie);
   }
.EE
.PP
Example 4:
This example shows how to use \*Csysget\*E to read the contents of a
structure by specifying its kernel symbol using the SGT_KSYM option:
.ES

   sgt_cookie_t cookie;
   int avenrun[3];

   SGT_COOKIE_INIT(&cookie);
   SGT_COOKIE_SET_KSYM(&cookie, "avenrun");
   sysget(SGT_KSYM, (char *)avenrun, sizeof(avenrun),
           SGT_READ, &cookie);
.EE
.SH SEE ALSO
\*Msysmp\*E(2),
\*Msyssgi\*E(2),
\*Mnlist\*E(3C),
\*Csysctl\*E(3C)