Module Name: src Committed By: pgoyette Date: Sun Jun 3 09:22:34 UTC 2018
Modified Files: src/share/man/man9: Makefile Added Files: src/share/man/man9: specificdata.9 Log Message: Make a first pass at documenting the specificdata functionality. XXX This is just a first pass, and I've probably made a ton of mistakes XXX while reading the code! Updates and corrections greatly appreciated. To generate a diff of this commit: cvs rdiff -u -r1.424 -r1.425 src/share/man/man9/Makefile cvs rdiff -u -r0 -r1.1 src/share/man/man9/specificdata.9 Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.
Modified files: Index: src/share/man/man9/Makefile diff -u src/share/man/man9/Makefile:1.424 src/share/man/man9/Makefile:1.425 --- src/share/man/man9/Makefile:1.424 Sun Jun 3 01:52:47 2018 +++ src/share/man/man9/Makefile Sun Jun 3 09:22:34 2018 @@ -1,4 +1,4 @@ -# $NetBSD: Makefile,v 1.424 2018/06/03 01:52:47 pgoyette Exp $ +# $NetBSD: Makefile,v 1.425 2018/06/03 09:22:34 pgoyette Exp $ # Makefile for section 9 (kernel function and variable) manual pages. @@ -51,7 +51,8 @@ MAN= accept_filter.9 accf_data.9 accf_ht secmodel_bsd44.9 secmodel_extensions.9 \ secmodel_overlay.9 secmodel_securelevel.9 secmodel_suser.9 \ SET.9 setbit.9 setjmp.9 shutdownhook_establish.9 \ - signal.9 skpc.9 sockopt.9 softintr.9 spl.9 splraiseipl.9 \ + signal.9 skpc.9 sockopt.9 softintr.9 spl.9 specificdata.9 \ + splraiseipl.9 \ store.9 suspendsched.9 \ sysctl.9 sysmon_envsys.9 sysmon_pswitch.9 sysmon_taskq.9 tc.9 \ tcp_congctl.9 timecounter.9 time_second.9 todr.9 ts2timo.9 tvtohz.9 \ @@ -873,6 +874,16 @@ MLINKS+=softintr.9 softintr_establish.9 softintr.9 softintr_schedule.9 softintr.9 softint.9 \ softintr.9 softint_establish.9 softintr.9 softint_disestablish.9 \ softintr.9 softint_schedule.9 +MLINKS+=specificdata.9 specificdata_domain_create.9 \ + specificdata.9 specificdata_domain_delete.9 \ + specificdata.9 specificdata_key_create.9 \ + specificdata.9 specificdata_key_delete.9 \ + specificdata.9 specificdata_init.9 \ + specificdata.9 specificdata_fini.9 \ + specificdata.9 specificdata_getspecific.9 \ + specificdata.9 specificdata_getspecific_unlocked.9 \ + specificdata.9 specificdata_setspecific.9 \ + specificdata.9 specificdata_setspecific_nowait .9 MLINKS+=spl.9 spl0.9 spl.9 splbio.9 spl.9 splclock.9 spl.9 splhigh.9 \ spl.9 splimp.9 \ spl.9 spllowersoftclock.9 spl.9 splnet.9 \ Added files: Index: src/share/man/man9/specificdata.9 diff -u /dev/null src/share/man/man9/specificdata.9:1.1 --- /dev/null Sun Jun 3 09:22:34 2018 +++ src/share/man/man9/specificdata.9 Sun Jun 3 09:22:34 2018 @@ -0,0 +1,160 @@ +.\" $NetBSD: specificdata.9,v 1.1 2018/06/03 09:22:34 pgoyette Exp $ +.\" +.\" Copyright (c) 2010 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by Jason R. Thorpe +.\" +.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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. +.\" +.Dd June 3, 2018 +.Dt MODULE 9 +.Os +.Sh NAME +.Nm specificdata , +.Nm specificdata_domain_create , +.Nm specificdata_domain_delete , +.Nm specificdata_key_create , +.Nm specificdata_key_delete , +.Nm specificdata_init , +.Nm specificdata_fini , +.Nm specificdata_getspecific , +.Nm specificdata_getspecific_unlocked , +.Nm specificdata_setspecific , +.Nm specificdata_setspecific_nowait +.Nd manipulate arbitrary data attached to objects +.Sh SYNOPSIS +.In sys/specificdata.h +.Ft specificdata_domain_t +.Fn specificdata_domain_create +.Ft void +.Fn specificdata_domain_delete "specificdata_domain_t sd" +.Ft int +.Fn specificdata_key_create "specificdata_domain_t sd" \ +"specificdata_key_t *keyp" "specificdata_dtor_t dtor" +.Ft void +.Fn specificdata_key_delete "specificdata_domain_t sd" "specificdata_key_t key" +.Ft int +.Fn specificdata_init "specificdata_domain_t sd" "specificdata_reference *ref" +.Ft void +.Fn specificdata_fini "specificdata_domain_t sd" "specificdata_reference *ref" +.Ft "void *" +.Fn specificdata_getspecific "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" +.Ft "void *" +.Fn specificdata_getspecific_unlocked "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" +.Ft void +.Fn specificdata_setspecific "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" "void *data" +.Ft int +.Fn specificdata_setspecific_nowait "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" "void *data" +.Sh DESCRIPTION +The +.Nm +facility provides a mechanism for attaching arbitrary data to the objects +within a particular domain. +.Sh FUNCTIONS +.Bl -tag -width abcd +.It Fn specificdata_domain_create +Create a new domain. +.It Fn specificdata_domain_delete sd +Delete a domain. +.It Fn specificdata_key_create sd keyp dtor +Create a new key for the domain. +The +.Fa dtor +argument specifies a destructor which is called when an item with the +specified key is deleted. +.It Fn specificdata_key_delete sd key +Delete a key for the domain, and delete any associated values. +.It Fn specificdata_init sd ref +Initialize the +.Nm +container +.Fa ref +for use in the specified domain. +.It Fn specificdata_fini sd ref +Destroy the +.Nm +container +.Fa ref , +and destroy all of the data values stuffed into the container. +.It Fn specificdata_getspecific "specificdata_domain_t sd" \ +"specificdata_reference *ref" "specificdata_key_t key" +Retrieve the data value from the +.Nm +container +.Fa ref +associated with +.Fa key . +.It Fn specificdata_getspecific_unlocked sd ref key +Retrieve the data value from the +.Nm +container +.Fa ref +associated with +.Fa key +in a lockless manner. +Care must be taken to ensure that no other thread could cause +.Fa ref +to become invalid (i.e. point at the wrong container) by issuing a +.Fn setspecific +call or by destroying the container. +.It Fn specificdata_setspecific sd ref key data +Store the value +.Fa data +in the +.Nm +container +.Fa ref +and associate it with +.Fa key . +If a value has previously been set, the new value replaces the original +value. +.It Fn specificdata_setspecific_nowait sd ref key data +(Unimplemented) +.El +.Sh CODE REFERENCES +The +.Nm +functionality is implemented in +.Pa sys/kern/subr_specificdata.c . +.Pp +The header file +.In sys/sys/specificdata.h +describes the public interface. +.Sh HISTORY +The +.Nm +subsystem first appeared in +.Nx 4.0 . +.Sh AUTHORS +.An -nosplit +The +.Nm +system was written by +.An Jason Thorpe Aq Mt thor...@netbsd.org . +This manual page was written by +.An Paul Goyette Aq Mt pgoye...@netbsd.org .