Differential D21700 Diff 62676 share/man/man3/sysctlinfo.3

Changeset View

Standalone View

share/man/man3/sysctlinfo.3

Property	Old Value	New Value
svn:eol-style	null	native \ No newline at end of property
svn:keywords	null	FreeBSD=%H \ No newline at end of property
svn:mime-type	null	text/plain \ No newline at end of property

				.\"
				.\" Copyright (c) 2019 Alfonso Sabato Siciliano
				.\"
				.\" Redistribution and use in source and binary forms, with or without
				.\" modification, are permitted provided that the following conditions
				.\" are met:
				.\" 1. Redistributions of source code must retain the above copyright
				.\" notice, this list of conditions and the following disclaimer.
				.\" 2. Redistributions in binary form must reproduce the above copyright
				.\" notice, this list of conditions and the following disclaimer in the
				.\" documentation and/or other materials provided with the distribution.
				.\"
				.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
				.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
				.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
				.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
				.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
				.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
				.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
				.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
				.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
				.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
				.\" SUCH DAMAGE.
				.\"
				.\" $FreeBSD$
				.\"
				.Dd September 20, 2019
				.Dt SYSCTLINFO 3
				.Os
				.Sh NAME
				.Nm SYSCTLINFO
				.Nm SYSCTLINFO_BYNAME
				.Nm SYSCTLINFO_HELPER_ALL
				.Nm SYSCTLINFO_HELPER_ALLIWITHNEXT
				.Nm SYSCTLINFO_HELPER_ALLWITHNEXTNAME
				.Nd Interface for getting info about the sysctl tree
				.Sh SYNOPSIS
				.In sys/types.h
				.In sys/sysctl.h
				.In sysctlinfo.h
				.Fd #define ENTRYFAKENAME
				.Fd #define ENTRYNAME
				.Fd #define ENTRYDESC
				.Fd #define ENTRYLABEL
				.Fd #define ENTRYKIND
				.Fd #define ENTRYFMT
				.Fd #define ENTRYNEXTNODE
				.Fd #define ENTRYNEXTLEAF
				.Fd #define ENTRYALLINFO
				.Fd #define ENTRYALLINFO_WITHNEXTNODE
				.Fd #define ENTRYALLINFO_WITHNEXTLEAF
				.Fd #define ENTRYIDBYNAME
				.Fd #define ENTRYFAKEIDBYNAME
				.Fd #define ENTRYDESCBYNAME
				.Fd #define ENTRYLABELBYNAME
				.Fd #define ENTRYKINDBYNAME
				.Fd #define ENTRYFMTBYNAME
				.Fd #define ENTRYALLINFOBYNAME
				.Fd #define ENTRYALLINFOBYNAME_WITHNEXTNODE
				.Fd #define ENTRYALLINFOBYNAME_WITHNEXTLEAF
				.Ft "int"
				.Fo SYSCTLINFO
				.Fa "int *id"
				.Fa "size_t idlevel"
				.Fa "int prop[2]"
				.Fa "void *buf"
				.Fa "size_t *buflen"
				.Fc
				.Ft "int"
				.Fn SYSCTLINFO_BYNAME "char name" "int prop[2]" "void buf" "size_t *buflen"
				.Ft "void"
				.Fo SYSCTLINFO_HELPER_ALL
				.Fa "void *buf"
				.Fa "size_t idlevel"
				.Fa "int *id"
				.Fa "char *namep"
				.Fa "char *descrp"
				.Fa "unsigned int kind"
				.Fa "char *fmtp"
				.Fa "char *labelp"
				.Fc
				.Ft "void"
				.Fo SYSCTLINFO_HELPER_ALLWITHNEXT
				.Fa "void *buf"
				.Fa "size_t idlevel"
				.Fa "int *id"
				.Fa "char *namep"
				.Fa "char *descrp"
				.Fa "unsigned int kind"
				.Fa "char *fmtp"
				.Fa "char *labelp"
				.Fa "size_t idnextlevel"
				.Fa "int *idnext"
				.Fc
				.Ft "void"
				.Fo SYSCTLINFO_HELPER_ALLWITHNEXTNAME
				.Fa "void *buf"
				.Fa "size_t idlevel"
				.Fa "int *id"
				.Fa "char *namep"
				.Fa "char *descrp"
				.Fa "unsigned int kind"
				.Fa "char *fmtp"
				.Fa "char *labelp"
				.Fa "char *namenextp"
				.Fc
				.Sh DESCRIPTION
				Macros to wrap the
				.Xr sysctlinfo 4
				interface to explore the sysctl tree and to get info about the nodes.
				.Fn SYSCTLINFO
				and
				.Fn SYSCLINFO_BYNAME
				seek the node with
				.Fa id
				/
				.Fa idlevel
				or
				.Fa name ,
				then the information specified by
				.Fa prop
				is copied into the buffer
				.Fa buf .
				Before the call
				.Fa buflen
				gives the size of
				.Fa buf ,
				after a successful call
				.Fa buflen
				gives the amount of data copied; the size of the info can be determined with the
				NULL argument for
				.Fa buf ,
				the size will be returned in the location pointed to by
				.Fa buflen .
				The value of
				.Fa prop[0]
				should be
				.Dv CTL_SYSCTL
				and
				.Fa prop[1]
				can specify the desired info, the possible values are listed later.
				.Pp
				.Fn SYSCTLINFO
				accepts an array
				.Fa id
				of
				.Fa idlevel
				elements (between 1 and CTL_MAXNAME) and the following
				.Fa prop[1]:
				.Bl -tag -width indent
				.It Dv ENTRYFAKENAME
				if the node exists
				.Fa buf
				is set like a string with its name, otherwise
				.Nm sysctlinfo
				build a name depending on the
				.Fa id,
				e.g., with an
				.Fa id
				[1.1.100.500.1000] the name is
				.Dq kern.ostype.100.500.1000 .
				.It Dv ENTRYNAME , Dv ENTRYDESC , Dv ENTRYLABEL and Dv ENTRYFMT
				set
				.Fa buf
				like a string with the name, description, label and format, respectively.
				.It Dv ENTRYKIND
				sets
				.Fa buf
				like an unsigned int with the kind of the node, its format is: 3 bytes for
				bcrUnsubmitted Not Done Inline Actions s/format respectively/format, respectively/ bcr: s/format respectively/format, respectively/
				asicilianoAuthorUnsubmitted Done Inline Actions I' ll update, thank you asiciliano: I' ll update, thank you
				flags and 1 byte for type, they are defined in
				.In sys/sysctl.h .
				.It Dv ENTRYNEXTNODE and Dv ENTRYNEXTLEAF
				.Fa buf
				is set like an integer array with the id of the next node/leaf of a Depth-First
				Traversal, the next level is
				.Dq buflen / sizeof(int)
				to be consistent with the acceptable level range.
				.It Dv ENTRYALLINFO
				sets the
				.Fa buf
				with all the info of the node, it should be passed to the helper macro
				.Fn SYSCTLINFO_HELPER_ALL ,
				if description, format or label is NULL, descp, fmtp or labep is set to
				.Dq
				respectively.
				.It Dv ENTRYALLINFO_WITHNEXTNODE and Dv ENTRYALLINFO_WITHNEXTLEAF
				set all the info of the node like
				.Dv SYSCTLINFO_ALLINFO
				with the next node/leaf,
				.Fa buf
				should be passed to
				.Fn SYSCTLINFO_HELPER_ALLWITHNEXT ,
				if the node has not a next
				.Fa idnextlevel
				is set to 0.
				.El
				.Pp
				.Fn SYSCTLINFO_BYNAME
				accepts the following
				.Fa prop[1]:
				.Bl -tag -width indent
				.It Dv ENTRYFAKEIDBYNAME and Dv ENTRYIDBYNAME
				.Fa buf
				is set like an integer array with the id of the node, the level is
				.Dq buflen / sizeof(int) .
				ENTRYFAKEIDBYNAME does not set the last level if its last level name is
				.Dq ,
				e.g.,
				.Dq n1.n2.n3.
				the id array is set to
				[1.2.3].
				.It Dv ENTRYDESCBYNAME , Dv ENTRYLABELBYNAME and Dv ENTRYFMTBYNAME
				set
				.Fa buf
				like a string with the description, label and format respectively.
				.It Dv ENTRYKINDBYNAME
				kind of an node, see
				.Dv ENTRYKIND .
				.It Dv ENTRYALLINFOBYNAME
				sets the
				.Fa buf
				with all the info of the node, it should be passed to the helper macro
				.Fn SYSCTLINFO_HELPER_ALL ,
				if description, format or label is NULL, descp, fmtp or labep is set to
				.Dq
				respectively.
				.It Dv ENTRYALLINFOBYNAME_WITHNEXTNODE and Dv ENTRYALLINFOBYNAME_WITHNEXTLEAF
				set all the info of the node like
				.Dv SYSCTLINFO_ALLINFOBYNAME
				with the next node/leaf,
				.Fa buf
				should be passed to
				.Fn SYSCTLINFO_HELPER_ALLWITHNEXTNAME ,
				if the node has not a next node/leaf
				.Fa nextnamep
				is set to
				.Dq .
				.El
				.Sh IMPLEMENTATION NOTES
				The kernel provides an undocumented interface for the info of the sysctl tree,
				obviously
				.Nm sysctlinfo
				and the kernel interface can coexist.
				.Pp
				In
				.Dq capability mode ,
				see
				.Xr cap_enter 2 ,
				.Nm sysctlinfo
				checks if the node has the
				.Dv CTLFLAG_CAPRD
				or
				.Dv CTLFLAG_CAPWR
				flag before to return its info;
				.Xr sysctl 3
				will check the
				.Dq capability permission
				to get or set a value.
				.Dv ENTRYFAKENAME
				has no capability check for compatibility with the kernel.
				.Dv ENTRYNEXTNODE
				and
				.Dv ENTRYNEXTLEAF
				check never the capability flags to traverse the tree also in capability mode.
				.Pp
				.Fn SYSCTLINFO
				and
				.Fn SYSCTLINFO_BYNAME
				seek the node with the
				.Fa id
				/
				.Fa idlevel
				or with the
				.Fa name
				then they share the same code.
				.Sh RETURN VALUES
				.Rv -std SYSCTLINFO SYSCTLINFO_BYNAME
				.Sh EXAMPLES
				If installed:
				.Dl /usr/local/share/examples/sysctlinfo/
				.Pp
				Example to visit the sysctl tree:
				.Pp
				.Bd -literal -offset indent -compact
				int id[CTL_MAXNAME], idp_unused, idnextp;
				size_t idlevel, idnextlevel, buflen, i;
				char buf[BUFSIZE], namep, descrp, fmtp, labelp;
				unsigned int kind;
				int prop[2] = { CTL_SYSCTL, ENTRYALLINFO_WITHNEXTNODE };

				id[0]=0;
				idlevel=1;

				for (;;) {
				for (i = 0; i < idlevel; i++)
				printf("%d%c", id[i], i+1 < idlevel ? '.' : '\\n');

				buflen = BUFSIZE;
				if(SYSCTLINFO(id, idlevel, prop, buf, &buflen) != 0) {
				err(1, "ENTRYALLINFO_WITHNEXTNODE");

				SYSCTLINFO_HELPER_ALLWITHNEXT(buf, idlevel, idp_unused, namep, descrp,
				kind, fmtp, labelp, idnextlevel, idnextp);

				printf("name: %s\\n", namep);
				printf("description: %s\\n", descrp);
				printf("label: %s\\n", labelp);
				printf("kind: %u\\n", kind );
				printf("\tflags: %u\\n", kind & 0xfffffff0 );
				printf("\ttype: %u\\n", kind & CTLTYPE );
				printf("fmt: %s\\n", fmtp);
				printf("--------------------------------------\\n");

				if (idnextlevel < 1)
				break;

				memcpy(id, idnextp, idnextlevel * sizeof(int));
				idlevel = idnextlevel;
				}
				.Ed
				.Sh ERRORS
				The following errors may be reported:
				.Bl -tag -width Er
				.It Bq Er ECAPMODE
				The node has not the CTLFLAG_CAPRD or CTLFLAG_CAPWR flag in capability mode.
				.It Bq Er EINVAL
				.Fa name
				has more than CTL_MAXNAME levels.
				.It Bq Er EINVAL
				.Fa idlevel
				is either greater CTL_MAXNAME, equal to zero or is not an integer.
				.It Bq Er ENAMETOOLONG
				.Fa name
				is >= MAXPATHLEN.
				.It Bq Er ENOATTR
				The node exists but its info is NULL.
				.It Bq Er ENOENT
				The node does not exist.
				.El
				.Sh SEE ALSO
				.Xr cap_enter 2 ,
				.Xr sysctl 3 ,
				.Xr sysctlinfo 4
				.Sh HISTORY
				The
				.Nm sysctlinfo
				interface first appeared in
				.Fx 13.0 .
				.Sh AUTHORS
				The
				.Nm sysctlinfo
				interface was written by
				.An Alfonso S. Siciliano Aq Mt alf.siciliano@gmail.com