Hallo, dies ist ein Test.

PWD: /www/data-lst1/unixsoft/unixsoft/kaempfer/.public_html

Running in File Mode
Relative path: ./../../../../../../usr/man/man9f/kstat2_create.9f
Real path: /usr/share/man/man9f/kstat2_create.9f
Zurück

'\" te .\" Copyright (c) 2015, 2020, Oracle and/or its affiliates. .TH kstat2_create 9F "12 Aug 2016" "Oracle Solaris 11.4" "Kernel Functions" .SH NAME kstat2_create \- create and initialize a new kstat .SH SYNOPSIS .LP .nf #include <sys/types.h> #include <sys/kstat2.h> kstat2_t *kstat2_create(const char *pseg[], uint32_t npseg, const zoneid_t ks_zone, kstat2_named_t *ks_data, uint_t ks_ndata, uint32_t ks_flags, const kstat2_md_t *ks_metadata, const char *ks_desc, kstat2_metaflag_t ks_mflags); .fi .SH INTERFACE LEVEL .sp .LP Solaris DDI specific (Solaris DDI) .SH PARAMETERS .sp .ne 2 .mk .na \fB\fIks_pseg\fR\fR .ad .br .sp .6 .RS 4n The segments used to construct a path which uniquely identifies this \fBkstat\fR. For example, "unix", "cpu", "cpu_info", "1". .RE .sp .ne 2 .mk .na \fB\fIks_npseg\fR\fR .ad .br .sp .6 .RS 4n The number of path segments in the array \fBkstat_pseg\fR. .RE .sp .ne 2 .mk .na \fB\fIks_zone\fR\fR .ad .br .sp .6 .RS 4n The ID of the zone in which \fBkstat\fR will initially be visible. The constant \fBALL_ZONES\fR is used to make the \fBkstat\fR visible in all zones, and \fBGLOBAL_ZONEID\fR to make it visible only in the global zone. To make the \fBkstat\fR visible in other zones, see \fBkstat2_zone_add\fR(9F) and description of \fBKSTAT2_FLAG_GZ_VIS\fR later in the man page. .RE .sp .ne 2 .mk .na \fB\fIks_data\fR\fR .ad .br .sp .6 .RS 4n This argument must be NULL for kstats whose storage is managed by the framework, and a pointer to an array of \fBkstat2\fR name-value pairs for kstats whose data storage is managed by the \fBkstat\fR provider. .RE .sp .ne 2 .mk .na \fB\fIks_ndata\fR\fR .ad .br .sp .6 .RS 4n The number of name-value pairs in the \fBks_data\fR section of the \fBkstat\fR. .RE .sp .ne 2 .mk .na \fB\fIks_flags\fR\fR .ad .br .sp .6 .RS 4n A bit-field of various flags for this \fBkstat\fR. The only flag which is available for use by \fBkstat\fR providers is: .sp .ne 2 .mk .na \fB\fBKSTAT2_FLAG_PERSISTENT\fR\fR .ad .br .sp .6 .RS 4n Indicates that this \fBkstat\fR is persistent over time. For persistent kstats, \fBkstat2_delete\fR(9F) function marks the \fBkstat\fR as dormant; a subsequent \fBkstat2_create()\fR function reactivates the \fBkstat\fR. This feature is provided so that statistics are not lost across driver close or open (such as raw disk I/O on a disk with no mounted partitions). Note that persistent kstats cannot have their storage managed by the driver since \fBks_data\fR points to garbage as soon as the driver goes away. .RE .sp .ne 2 .mk .na \fB\fBKSTAT2_FLAG_GZ_VIS\fR\fR .ad .br .sp .6 .RS 4n Indicates that this \fBkstat\fR is created and made visible in both the global zone and \fBks_zone\fR, if \fBkz_zone\fR is the ID of a non-global zone. .RE .RE .sp .ne 2 .mk .na \fB\fBks_metadata\fR\fR .ad .br .sp .6 .RS 4n The metadata for the values held in the kstat's \fBks_data\fR structure. This metadata is an array of \fBkstat2_md_t\fR structures of the same length and in the same order as the \fBkstat\fR name-value pairs in \fBks_data\fR. .RE .sp .ne 2 .mk .na \fB\fBks_desc\fR\fR .ad .br .sp .6 .RS 4n A brief string describing the purpose of this \fBkstat\fR. This string must be statically allocated as a pointer to it, which is held in the \fBkstat\fR. .RE .sp .ne 2 .mk .na \fB\fBks_mflags\fR\fR .ad .br .sp .6 .RS 4n Meta-flags for the \fBkstat\fR as a whole. .sp .ne 2 .mk .na \fB\fBKSTAT2_MF_NONE\fR\fR .ad .br .sp .6 .RS 4n Indicates that this \fBkstat\fR has no meta-flags set. .RE .sp .ne 2 .mk .na \fB\fBKSTAT2_MF_STABLE\fR\fR .ad .br .sp .6 .RS 4n Indicates that this \fBkstat\fR is considered stable and will not be removed from Oracle Solaris without prior notification. .RE .sp .ne 2 .mk .na \fB\fBKSTAT2_MF_PRIV\fR\fR .ad .br .sp .6 .RS 4n Indicates that this \fBkstat\fR contains sensitive content which can only be read by users having the appropriate RBAC privilege. .RE .RE .SH DESCRIPTION .sp .LP \fBkstat2_create()\fR function is used in conjunction with \fBkstat2_install\fR(9F) to allocate and initialize a \fBkstat2\fR(9S) structure. The method is generally as follows: .sp .LP \fBkstat2_create()\fR function allocates and performs necessary system initialization of a \fBkstat2\fR(9S) structure. \fBkstat2_create()\fR function allocates memory for the entire \fBkstat\fR (including data if necessary), initializes all header fields and the data section, assigns a unique kstat ID (KID), and then puts the \fBkstat\fR onto the system's \fBkstat\fR chain. The returned \fBkstat\fR is marked invalid because the provider (caller) may not have initialized the data section. .sp .LP After a successful call to \fBkstat2_create()\fR function, the provider can set the \fBks2_update\fR, \fBks2_private\fR and \fBks2_lock\fR fields if necessary, and must initialize the name-value pairs in \fBks2_data\fR. .sp .LP Once the \fBkstat\fR is completely initialized, \fBkstat2_install\fR(9F) function is used to make the \fBkstat\fR accessible to the outside world. .sp .LP Kstats containing data which may be regarded as sensitive should have the \fBKSTAT_MF_PRIV\fR flag set in metadata. Kstats with this flag set are only visible to and readable by users having the RBAC privilege: \fBkstat_rd_sensitive\fR. .SH RETURN VALUES .sp .LP If successful, the \fBkstat2_create()\fR function returns a pointer to the allocated \fBkstat\fR. NULL is returned upon failure. .SH CONTEXT .sp .LP The \fBkstat2_create()\fR function can be called from user or kernel context. .SH EXAMPLES .LP \fBExample 1\fR Create a \fBkstat\fR with framework allocated storage .sp .in +2 .nf #include <sys/types.h> #include <sys/kstat2.h> static const kstat2_md_t[2] md = { { KSTAT2_NVMT_CNT, KSTAT2_NVMF_NONE, 1UL, "Caller count", KSTAT1_DATA_NONE }, { KSTAT2_NVMT_UNK, KSTAT2_NVMF_NONE, 0UL, "Last caller name", KSTAT1_DATA_NONE } }; static const uint_t ndata = sizeof (md) / sizeof (kstat2_md_t); static kmutex_t my_lock; static kstat2_t my_drv_create_kstat() { kstat2_t *ksp; const char *pseg[] = { "misc", "my_drv", "data_in", "0" }; ksp = kstat2_create(pseg, sizeof (pseg) / sizeof (char *), ALL_ZONES, NULL, ndata, 0, md, "data read by my_drv", KSTAT2_MF_NONE); if (ksp != NULL) { /* * Kstat name-value pairs must be initialized * before calling kstat2_install() */ kstat2_named_t *knp = KSTAT2_NV_PTR(ksp); kstat2_nv_init(knp, "int_data", KSTAT2_NVVT_INT, KSTAT2_NVF_NONE); kstat2_nv_init(knp+1, "str_data", KSTAT2_NVVT_STR, KSTAT2_NVF_NONE); /* * Set kstat's lock because there is variable * data in the kstat (KSTAT2_NVVT_STR). */ ksp->ks2_lock = &my_lock; kstat2_install(ksp); } return (ksp); } .fi .in -2 .sp .LP \fBExample 2\fR Create a \fBkstat\fR with driver allocated storage .sp .in +2 .nf #include <sys/types.h> #include <sys/kstat2.h> static const kstat2_md_t[2] md = { { KSTAT2_NVMT_BYTES, KSTAT2_NVMF_NONE, 1UL, "int1 byte count", KSTAT1_DATA_NONE }, { KSTAT2_NVMT_BYTES, KSTAT2_NVMF_NONE, 1UL, "int2 byte count", KSTAT1_DATA_NONE } }; static const uint_t ndata = sizeof (md) / sizeof (kstat2_md_t); static kstat2_named_t my_drv_kvals[2]; static kmutex_t my_lock; static kstat2_t my_drv_create_kstat() { kstat2_t *ksp; const char *pseg[] = { "misc", "my_drv", "data_in", "0" }; ksp = kstat2_create(pseg, sizeof (pseg) / sizeof (char *), ALL_ZONES, my_drv_kvals, ndata, 0, md, "data read by my_drv", KSTAT2_MF_NONE); if (ksp != NULL) { /* * Kstat name-value pairs must be initialized * before calling kstat2_install(). This could also be done * in a static initializer of my_drv_kvals. */ kstat2_nv_init(my_drv_kvals[0], "int1", KSTAT2_NVVT_INT, KSTAT2_NVF_NONE); kstat2_nv_init(my_drv_kvals[1], "int2", KSTAT2_NVVT_INT, KSTAT2_NVF_NONE); kstat2_install(ksp); } return (ksp); } .fi .in -2 .sp .LP \fBExample 3\fR Create a persistent \fBkstat\fR .sp .in +2 .nf #include <sys/types.h> #include <sys/kstat2.h> static const kstat2_md_t[2] md = { { KSTAT2_NVMT_CNT, KSTAT2_NVMF_NONE, 1UL, "data errors", KSTAT1_DATA_NONE }, { KSTAT2_NVMT_CNT, KSTAT2_NVMF_NONE, 1UL, "transport errors", KSTAT1_DATA_NONE } }; static const uint_t ndata = sizeof (md) / sizeof (kstat2_md_t); static kstat2_t create_dsk_error_kstat(const char *ddi_inst_str) { kstat2_t *ksp; const char *pseg[] = { "disk", "mydrv", ddi_inst_str, "err" }; /* * Create a persistent kstat for the disk error data. * Note that the kstat's framework must allocate and manage * the storage the data in a persistent kstat. */ ksp = kstat2_create(pseg, sizeof (pseg) / sizeof (char *), ALL_ZONES, NULL, ndata, KSTAT2_FLAG_PERSISTENT, md, "mydrv disk error kstat", KSTAT2_MF_NONE); if (ksp != NULL) { /* * Kstat name-value pairs must be initialized before * calling the kstat2_install() function. However, a persistent kstat * which is being reactivated has data which is already * initialized, so there is no need to do it again. It would * be an error to do so. So the kvals are * only initialized if the kstat is not in a dormant state. */ if (! (ksp->ks2_flags & KSTAT_FLAG_DORMANT)) { kstat2_named_t *err_kval = ksp->ks2_data; kstat2_nv_init(err_kval, "data_errors", KSTAT2_NVVT_INT, KSTAT2_NVF_NONE); kstat2_nv_init(err_kval+1, "transport_errors", KSTAT2_NVVT_INT, KSTAT2_NVF_NONE); } kstat2_install(ksp); } return (ksp); } .fi .in -2 .sp .SH SEE ALSO .sp .LP \fBuser_attr\fR(5), \fBprivileges\fR(7), \fBkstat2_create_histogram\fR(9F), \fBkstat2_delete\fR(9F), \fBkstat2_install\fR(9F), \fBkstat2_nv_init\fR(9F), \fBkstat2_zone_add\fR(9F), \fBkstat2_zone_remove\fR(9F), \fBkstat2\fR(9S), \fBkstat2_md\fR(9S), \fBkstat2_named\fR(9S) .SH NOTES .sp .LP When creating persistent kstats, it is important to note that the kstats framework makes an internal copy of the metadata and the strings supplied for the \fBkval\fR (kstat value) names. This is to ensure that if the driver or module is unloaded, there are no stale references held to static data in the driver's address space. This copying only happens when the kstat is first installed by a call to the \fBkstat2_install()\fR function. Therefore, if a \fBkval\fR is reinitialized after a kstat is active from a dormant state, the \fBkval\fR name pointer points to an address in the driver's address space. This space becomes invalid if the driver were subsequently unloaded. For more information, see the \fBkstat2_install\fR(9F) man page.