Sync usage with man page.
[netbsd-mini2440.git] / share / man / man9 / callback.9
blob616f12cda8561eddf6743c715190b33cb280396c
1 .\"     $NetBSD: callback.9,v 1.3 2009/10/28 18:20:41 njoly Exp $
2 .\"
3 .\" Copyright (c) 2009 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\"
15 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
16 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
19 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
20 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
21 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
22 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
23 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
24 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
25 .\" POSSIBILITY OF SUCH DAMAGE.
26 .\"
27 .Dd October 28, 2009
28 .Dt CALLBACK 9
29 .Os
30 .Sh NAME
31 .Nm callback
32 .Nd generic callback interface
33 .Sh SYNOPSIS
34 .In sys/callback.h
35 .Ft void
36 .Fn callback_head_init "struct callback_head *ch" "int ipl"
37 .Ft void
38 .Fn callback_head_destroy "struct callback_head *ch"
39 .Ft void
40 .Fn callback_register \
41 "struct callback_head *ch" "struct callback_entry *ce" "void *obj" \
42 "int (*fn)(struct callback_entry *, void *, void *)"
43 .Ft void
44 .Fn callback_unregister "struct callback_head *ch" "struct callback_entry *ce"
45 .Ft int
46 .Fn callback_run_roundrobin "struct callback_head *ch" "void *arg"
47 .Sh DESCRIPTION
48 The generic
49 .Nm callback
50 interface allows lower-level layer code to execute a registered function,
51 or set of functions, from the higher-level layer.
52 .Pp
53 Registered functions must return one of these constants:
54 .Bl -tag -width Dv
55 .It Dv CALLBACK_CHAIN_CONTINUE
56 Indicates that the function call was successful.
57 The following functions in the chain will be called.
58 .It Dv CALLBACK_CHAIN_ABORT
59 Indicates a failure case in the function call.
60 Any following functions in the chain will not be executed.
61 .El
62 .Sh FUNCTIONS
63 The callback structure
64 .Vt callback_head
65 should be initialized and destroyed using the functions described below.
66 This structure contains the list of callback entries and other internal data.
67 .Pp
68 The
69 .Vt callback_entry
70 structure is an entry, normally associated with the higher-level object.
71 It contains the internal data of the callback interface.
72 .Bl -tag -width compact
73 .It Fn callback_head_init "ch" "ipl"
74 Initialize the callback structure specified by
75 .Fa ch .
76 The highest IPL at which this callback can be used is specified by
77 .Fa ipl .
78 .It Fn callback_head_destroy "ch"
79 Destroy the callback structure specified by
80 .Fa ch .
81 The caller must unregister all functions before destroying the callback structure.
82 .It Fn callback_register "ch" "ce" "obj" "fn"
83 Register the callback function in the callback structure specified by
84 .Fa ch .
85 .Fa ce
86 should point to the entry structure of the callback object.
87 The callback object itself is specified by
88 .Fa obj .
89 The function pointer is specified by
90 .Fa fn .
91 .It Fn callback_unregister "ch" "ce"
92 Unregister the callback function from the structure specified by
93 .Fa ch .
94 The entry should be passed as
95 .Fa ce .
96 This function may block.
97 .It Fn callback_run_roundrobin "ch" "arg"
98 Executes all functions registered in the callback
99 structure, specified by
100 .Fa ch .
101 The functions are executed in round-robin fashion.
102 The value of
103 .Fa arg
104 will be passed to the callback functions.
106 .Sh CODE REFERENCES
107 This section describes places within the
109 source tree where actual code implementing the
111 interface can be found.
112 All pathnames are relative to
113 .Pa /usr/src .
117 interface is implemented within the file
118 .Pa sys/kern/subr_callback.c .
119 .Sh SEE ALSO
120 .Xr intro 9