/share/man/man9/sysctl_add_oid.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 530 lines · 529 code · 1 blank · 0 comment · 0 complexity · bd5135a7b2491bbdd48a72bc9e9e1fdd MD5 · raw file

  1. .\"
  2. .\" Copyright (c) 2000, Andrzej Bialecki <abial@FreeBSD.org>
  3. .\" All rights reserved.
  4. .\"
  5. .\" Redistribution and use in source and binary forms, with or without
  6. .\" modification, are permitted provided that the following conditions
  7. .\" are met:
  8. .\" 1. Redistributions of source code must retain the above copyright
  9. .\" notice, this list of conditions and the following disclaimer.
  10. .\" 2. Redistributions in binary form must reproduce the above copyright
  11. .\" notice, this list of conditions and the following disclaimer in the
  12. .\" documentation and/or other materials provided with the distribution.
  13. .\" 3. The name of the author may not be used to endorse or promote products
  14. .\" derived from this software without specific prior written permission.
  15. .\"
  16. .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  17. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  20. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26. .\" SUCH DAMAGE.
  27. .\"
  28. .\" $FreeBSD$
  29. .\"
  30. .Dd July 15, 2000
  31. .Dt SYSCTL_ADD_OID 9
  32. .Os
  33. .Sh NAME
  34. .Nm sysctl_add_oid ,
  35. .Nm sysctl_move_oid ,
  36. .Nm sysctl_remove_oid
  37. .Nd runtime sysctl tree manipulation
  38. .Sh SYNOPSIS
  39. .In sys/types.h
  40. .In sys/sysctl.h
  41. .Ft struct sysctl_oid *
  42. .Fo sysctl_add_oid
  43. .Fa "struct sysctl_ctx_list *ctx"
  44. .Fa "struct sysctl_oid_list *parent"
  45. .Fa "int number"
  46. .Fa "const char *name"
  47. .Fa "int kind"
  48. .Fa "void *arg1"
  49. .Fa "int arg2"
  50. .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  51. .Fa "const char *format"
  52. .Fa "const char *descr"
  53. .Fc
  54. .Ft int
  55. .Fo sysctl_move_oid
  56. .Fa "struct sysctl_oid *oidp"
  57. .Fa "struct sysctl_oid_list *parent"
  58. .Fc
  59. .Ft int
  60. .Fo sysctl_remove_oid
  61. .Fa "struct sysctl_oid *oidp"
  62. .Fa "int del"
  63. .Fa "int recurse"
  64. .Fc
  65. .Ft struct sysctl_oid_list *
  66. .Fo SYSCTL_CHILDREN
  67. .Fa "struct sysctl_oid *oidp"
  68. .Fc
  69. .Ft struct sysctl_oid_list *
  70. .Fo SYSCTL_STATIC_CHILDREN
  71. .Fa "struct sysctl_oid_list OID_NAME"
  72. .Fc
  73. .Ft struct sysctl_oid *
  74. .Fo SYSCTL_ADD_OID
  75. .Fa "struct sysctl_ctx_list *ctx"
  76. .Fa "struct sysctl_oid_list *parent"
  77. .Fa "int number"
  78. .Fa "const char *name"
  79. .Fa "int kind"
  80. .Fa "void *arg1"
  81. .Fa "int arg2"
  82. .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  83. .Fa "const char *format"
  84. .Fa "const char *descr"
  85. .Fc
  86. .Ft struct sysctl_oid *
  87. .Fo SYSCTL_ADD_NODE
  88. .Fa "struct sysctl_ctx_list *ctx"
  89. .Fa "struct sysctl_oid_list *parent"
  90. .Fa "int number"
  91. .Fa "const char *name"
  92. .Fa "int access"
  93. .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  94. .Fa "const char *descr"
  95. .Fc
  96. .Ft struct sysctl_oid *
  97. .Fo SYSCTL_ADD_STRING
  98. .Fa "struct sysctl_ctx_list *ctx"
  99. .Fa "struct sysctl_oid_list *parent"
  100. .Fa "int number"
  101. .Fa "const char *name"
  102. .Fa "int access"
  103. .Fa "char *arg"
  104. .Fa "int len"
  105. .Fa "const char *descr"
  106. .Fc
  107. .Ft struct sysctl_oid *
  108. .Fo SYSCTL_ADD_INT
  109. .Fa "struct sysctl_ctx_list *ctx"
  110. .Fa "struct sysctl_oid_list *parent"
  111. .Fa "int number"
  112. .Fa "const char *name"
  113. .Fa "int access"
  114. .Fa "int *arg"
  115. .Fa "int len"
  116. .Fa "const char *descr"
  117. .Fc
  118. .Ft struct sysctl_oid *
  119. .Fo SYSCTL_ADD_UINT
  120. .Fa "struct sysctl_ctx_list *ctx"
  121. .Fa "struct sysctl_oid_list *parent"
  122. .Fa "int number"
  123. .Fa "const char *name"
  124. .Fa "int access"
  125. .Fa "unsigned int *arg"
  126. .Fa "int len"
  127. .Fa "const char *descr"
  128. .Fc
  129. .Ft struct sysctl_oid *
  130. .Fo SYSCTL_ADD_LONG
  131. .Fa "struct sysctl_ctx_list *ctx"
  132. .Fa "struct sysctl_oid_list *parent"
  133. .Fa "int number"
  134. .Fa "const char *name"
  135. .Fa "int access"
  136. .Fa "long *arg"
  137. .Fa "const char *descr"
  138. .Fc
  139. .Ft struct sysctl_oid *
  140. .Fo SYSCTL_ADD_ULONG
  141. .Fa "struct sysctl_ctx_list *ctx"
  142. .Fa "struct sysctl_oid_list *parent"
  143. .Fa "int number"
  144. .Fa "const char *name"
  145. .Fa "int access"
  146. .Fa "unsigned long *arg"
  147. .Fa "const char *descr"
  148. .Fc
  149. .Ft struct sysctl_oid *
  150. .Fo SYSCTL_ADD_QUAD
  151. .Fa "struct sysctl_ctx_list *ctx"
  152. .Fa "struct sysctl_oid_list *parent"
  153. .Fa "int number"
  154. .Fa "const char *name"
  155. .Fa "int access"
  156. .Fa "int64_t *arg"
  157. .Fa "const char *descr"
  158. .Fc
  159. .Ft struct sysctl_oid *
  160. .Fo SYSCTL_ADD_OPAQUE
  161. .Fa "struct sysctl_ctx_list *ctx"
  162. .Fa "struct sysctl_oid_list *parent"
  163. .Fa "int number"
  164. .Fa "const char *name"
  165. .Fa "int access"
  166. .Fa "void *arg"
  167. .Fa "int len"
  168. .Fa "const char *format"
  169. .Fa "const char *descr"
  170. .Fc
  171. .Ft struct sysctl_oid *
  172. .Fo SYSCTL_ADD_STRUCT
  173. .Fa "struct sysctl_ctx_list *ctx"
  174. .Fa "struct sysctl_oid_list *parent"
  175. .Fa "int number"
  176. .Fa "const char *name"
  177. .Fa "int access"
  178. .Fa "void *arg"
  179. .Fa STRUCT_NAME
  180. .Fa "const char *descr"
  181. .Fc
  182. .Ft struct sysctl_oid *
  183. .Fo SYSCTL_ADD_PROC
  184. .Fa "struct sysctl_ctx_list *ctx"
  185. .Fa "struct sysctl_oid_list *parent"
  186. .Fa "int number"
  187. .Fa "const char *name"
  188. .Fa "int access"
  189. .Fa "void *arg1"
  190. .Fa "int arg2"
  191. .Fa "int (*handler) (SYSCTL_HANDLER_ARGS)"
  192. .Fa "const char *format"
  193. .Fa "const char *descr"
  194. .Fc
  195. .Sh DESCRIPTION
  196. These functions and macros provide an interface
  197. for creating and deleting sysctl oids at runtime
  198. (e.g.\& during lifetime of a module).
  199. The alternative method,
  200. based on linker sets (see
  201. .In sys/linker_set.h
  202. and
  203. .\" XXX Manual pages should avoid referencing source files
  204. .Pa src/sys/kern/kern_sysctl.c
  205. for details), only allows creation and deletion
  206. on module load and unload respectively.
  207. .Pp
  208. Dynamic oids of type
  209. .Dv CTLTYPE_NODE
  210. are reusable
  211. so that several code sections can create and delete them,
  212. but in reality they are allocated and freed
  213. based on their reference count.
  214. As a consequence,
  215. it is possible for two or more code sections
  216. to create partially overlapping trees that they both can use.
  217. It is not possible to create overlapping leaves,
  218. nor to create different child types with the same name and parent.
  219. .Pp
  220. Newly created oids are connected to their parent nodes.
  221. In all these functions and macros
  222. (with the exception of
  223. .Fn sysctl_remove_oid ) ,
  224. one of the required parameters is
  225. .Fa parent ,
  226. which points to the head of the parent's list of children.
  227. .Pp
  228. Most top level categories are created statically.
  229. When connecting to existing static oids,
  230. this pointer can be obtained with the
  231. .Fn SYSCTL_STATIC_CHILDREN
  232. macro, where the
  233. .Fa OID_NAME
  234. argument is name of the parent oid of type
  235. .Dv CTLTYPE_NODE
  236. (i.e., the name displayed by
  237. .Xr sysctl 8 ,
  238. preceded by underscore, and with all dots replaced with underscores).
  239. .Pp
  240. When connecting to an existing dynamic oid, this pointer
  241. can be obtained with the
  242. .Fn SYSCTL_CHILDREN
  243. macro, where the
  244. .Fa oidp
  245. argument points to the parent oid of type
  246. .Dv CTLTYPE_NODE .
  247. .Pp
  248. The
  249. .Fn sysctl_add_oid
  250. function creates raw oids of any type.
  251. If the oid is successfully created,
  252. the function returns a pointer to it;
  253. otherwise it returns
  254. .Dv NULL .
  255. Many of the arguments for
  256. .Fn sysctl_add_oid
  257. are common to the macros.
  258. The arguments are as follows:
  259. .Bl -tag -width handler
  260. .It Fa ctx
  261. A pointer to an optional sysctl context, or
  262. .Dv NULL .
  263. See
  264. .Xr sysctl_ctx_init 9
  265. for details.
  266. Programmers are strongly advised to use contexts
  267. to organize the dynamic oids which they create,
  268. unless special creation and deletion sequences are required.
  269. If
  270. .Fa ctx
  271. is not
  272. .Dv NULL ,
  273. the newly created oid will be added to this context
  274. as its first entry.
  275. .It Fa parent
  276. A pointer to a
  277. .Li struct sysctl_oid_list ,
  278. which is the head of the parent's list of children.
  279. .It Fa number
  280. The oid number that will be assigned to this oid.
  281. In almost all cases this should be set to
  282. .Dv OID_AUTO ,
  283. which will result in the assignment of the next available oid number.
  284. .It Fa name
  285. The name of the oid.
  286. The newly created oid will contain a copy of the name.
  287. .It Fa kind
  288. The kind of oid,
  289. specified as a bit mask of the type and access values defined in the
  290. .In sys/sysctl.h
  291. header file.
  292. Oids created dynamically always have the
  293. .Dv CTLFLAG_DYN
  294. flag set.
  295. Access flags specify whether this oid is read-only or read-write,
  296. and whether it may be modified by all users
  297. or by the superuser only.
  298. .It Fa arg1
  299. A pointer to any data that the oid should reference, or
  300. .Dv NULL .
  301. .It Fa arg2
  302. The size of
  303. .Fa arg1 ,
  304. or 0 if
  305. .Fa arg1
  306. is
  307. .Dv NULL .
  308. .It Fa handler
  309. A pointer to the function
  310. that is responsible for handling read and write requests
  311. to this oid.
  312. There are several standard handlers
  313. that support operations on nodes,
  314. integers, strings and opaque objects.
  315. It is possible also to define new handlers using the
  316. .Fn SYSCTL_ADD_PROC
  317. macro.
  318. .It Fa format
  319. A pointer to a string
  320. which specifies the format of the oid symbolically.
  321. This format is used as a hint by
  322. .Xr sysctl 8
  323. to apply proper data formatting for display purposes.
  324. Currently used format names are:
  325. .Dq N
  326. for node,
  327. .Dq A
  328. for
  329. .Li "char *" ,
  330. .Dq I
  331. for
  332. .Li "int" ,
  333. .Dq IU
  334. for
  335. .Li "unsigned int" ,
  336. .Dq L
  337. for
  338. .Li "long" ,
  339. .Dq LU
  340. for
  341. .Li "unsigned long"
  342. and
  343. .Dq S,TYPE
  344. for
  345. .Li "struct TYPE"
  346. structures.
  347. .It Fa descr
  348. A pointer to a textual description of the oid.
  349. .El
  350. .Pp
  351. The
  352. .Fn sysctl_move_oid
  353. function reparents an existing oid.
  354. The oid is assigned a new number as if it had been created with
  355. .Fa number
  356. set to
  357. .Dv OID_AUTO .
  358. .Pp
  359. The
  360. .Fn sysctl_remove_oid
  361. function removes a dynamically created oid from the tree,
  362. optionally freeing its resources.
  363. It takes the following arguments:
  364. .Bl -tag -width recurse
  365. .It Fa oidp
  366. A pointer to the dynamic oid to be removed.
  367. If the oid is not dynamic, or the pointer is
  368. .Dv NULL ,
  369. the function returns
  370. .Er EINVAL .
  371. .It Fa del
  372. If non-zero,
  373. .Fn sysctl_remove_oid
  374. will try to free the oid's resources
  375. when the reference count of the oid becomes zero.
  376. However, if
  377. .Fa del
  378. is set to 0,
  379. the routine will only deregister the oid from the tree,
  380. without freeing its resources.
  381. This behaviour is useful when the caller expects to rollback
  382. (possibly partially failed)
  383. deletion of many oids later.
  384. .It Fa recurse
  385. If non-zero, attempt to remove the node and all its children.
  386. If
  387. .Pa recurse
  388. is set to 0,
  389. any attempt to remove a node that contains any children
  390. will result in a
  391. .Er ENOTEMPTY
  392. error.
  393. .Em WARNING : "use recursive deletion with extreme caution" !
  394. Normally it should not be needed if contexts are used.
  395. Contexts take care of tracking inter-dependencies
  396. between users of the tree.
  397. However, in some extreme cases it might be necessary
  398. to remove part of the subtree no matter how it was created,
  399. in order to free some other resources.
  400. Be aware, though, that this may result in a system
  401. .Xr panic 9
  402. if other code sections continue to use removed subtrees.
  403. .El
  404. .Pp
  405. .\" XXX sheldonh finished up to here
  406. Again, in most cases the programmer should use contexts,
  407. as described in
  408. .Xr sysctl_ctx_init 9 ,
  409. to keep track of created oids,
  410. and to delete them later in orderly fashion.
  411. .Pp
  412. There is a set of macros defined
  413. that helps to create oids of given type.
  414. They are as follows:
  415. .Bl -tag -width SYSCTL_ADD_STRINGXX
  416. .It Fn SYSCTL_ADD_OID
  417. creates a raw oid.
  418. This macro is functionally equivalent to the
  419. .Fn sysctl_add_oid
  420. function.
  421. .It Fn SYSCTL_ADD_NODE
  422. creates an oid of type
  423. .Dv CTLTYPE_NODE ,
  424. to which child oids may be added.
  425. .It Fn SYSCTL_ADD_STRING
  426. creates an oid that handles a zero-terminated character string.
  427. .It Fn SYSCTL_ADD_INT
  428. creates an oid that handles an
  429. .Li int
  430. variable.
  431. .It Fn SYSCTL_ADD_UINT
  432. creates an oid that handles an
  433. .Li unsigned int
  434. variable.
  435. .It Fn SYSCTL_ADD_LONG
  436. creates an oid that handles a
  437. .Li long
  438. variable.
  439. .It Fn SYSCTL_ADD_ULONG
  440. creates an oid that handles an
  441. .Li unsigned long
  442. variable.
  443. .It Fn SYSCTL_ADD_QUAD
  444. creates an oid that handles an
  445. .Li int64_t
  446. variable.
  447. .It Fn SYSCTL_ADD_OPAQUE
  448. creates an oid that handles any chunk of opaque data
  449. of the size specified by the
  450. .Fa len
  451. argument,
  452. which is a pointer to a
  453. .Li "size_t *" .
  454. .It Fn SYSCTL_ADD_STRUCT
  455. creates an oid that handles a
  456. .Li "struct TYPE"
  457. structure.
  458. The
  459. .Fa format
  460. parameter will be set to
  461. .Dq S,TYPE
  462. to provide proper hints to the
  463. .Xr sysctl 8
  464. utility.
  465. .It Fn SYSCTL_ADD_PROC
  466. creates an oid with the specified
  467. .Pa handler
  468. function.
  469. The handler is responsible for handling read and write requests
  470. to the oid.
  471. This oid type is especially useful
  472. if the kernel data is not easily accessible,
  473. or needs to be processed before exporting.
  474. .El
  475. .Sh EXAMPLES
  476. The following is an example of
  477. how to create a new top-level category
  478. and how to hook up another subtree to an existing static node.
  479. This example does not use contexts,
  480. which results in tedious management of all intermediate oids,
  481. as they need to be freed later on:
  482. .Bd -literal
  483. #include <sys/sysctl.h>
  484. ...
  485. /* Need to preserve pointers to newly created subtrees, to be able
  486. * to free them later.
  487. */
  488. struct sysctl_oid *root1, *root2, *oidp;
  489. int a_int;
  490. char *string = "dynamic sysctl";
  491. ...
  492. root1 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(/* tree top */),
  493. OID_AUTO, "newtree", CTLFLAG_RW, 0, "new top level tree");
  494. oidp = SYSCTL_ADD_INT( NULL, SYSCTL_CHILDREN(root1),
  495. OID_AUTO, "newint", CTLFLAG_RW, &a_int, 0, "new int leaf");
  496. ...
  497. root2 = SYSCTL_ADD_NODE( NULL, SYSCTL_STATIC_CHILDREN(_debug),
  498. OID_AUTO, "newtree", CTLFLAG_RW, 0, "new tree under debug");
  499. oidp = SYSCTL_ADD_STRING( NULL, SYSCTL_CHILDREN(root2),
  500. OID_AUTO, "newstring", CTLFLAG_RD, string, 0, "new string leaf");
  501. .Ed
  502. .Pp
  503. This example creates the following subtrees:
  504. .Bd -literal -offset indent
  505. debug.newtree.newstring
  506. newtree.newint
  507. .Ed
  508. .Pp
  509. .Em "Care should be taken to free all oids once they are no longer needed!"
  510. .Sh SEE ALSO
  511. .Xr sysctl 8 ,
  512. .Xr sysctl 9 ,
  513. .Xr sysctl_ctx_free 9 ,
  514. .Xr sysctl_ctx_init 9
  515. .Sh HISTORY
  516. These functions first appeared in
  517. .Fx 4.2 .
  518. .Sh AUTHORS
  519. .An Andrzej Bialecki Aq abial@FreeBSD.org
  520. .Sh BUGS
  521. Sharing nodes between many code sections
  522. causes interdependencies that sometimes may lock the resources.
  523. For example,
  524. if module A hooks up a subtree to an oid created by module B,
  525. module B will be unable to delete that oid.
  526. These issues are handled properly by sysctl contexts.
  527. .Pp
  528. Many operations on the tree involve traversing linked lists.
  529. For this reason, oid creation and removal is relatively costly.