[BACK]Return to prog-8.html CVS log [TXT] [DIR] Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc
File:  [ELWIX - Embedded LightWeight unIX -] / embedaddon / bird / doc / prog-8.html
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Aug 22 12:33:54 2017 UTC (6 years, 9 months ago) by misho
Branches: bird, MAIN
CVS tags: v1_6_8p3, v1_6_3p0, v1_6_3, HEAD
bird 1.6.3

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
 <META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 1.0.9">
 <TITLE>BIRD Programmer's Documentation: Resources</TITLE>
 <LINK HREF="prog-7.html" REL=previous>
 <LINK HREF="prog.html#toc8" REL=contents>
</HEAD>
<BODY>
Next
<A HREF="prog-7.html">Previous</A>
<A HREF="prog.html#toc8">Contents</A>
<HR>
<H2><A NAME="s8">8.</A> <A HREF="prog.html#toc8">Resources</A></H2>

<H2><A NAME="ss8.1">8.1</A> <A HREF="prog.html#toc8.1">Introduction</A>
</H2>

<P>Most large software projects implemented in classical procedural
programming languages usually end up with lots of code taking care
of resource allocation and deallocation. Bugs in such code are often
very difficult to find, because they cause only `resource leakage',
that is keeping a lot of memory and other resources which nobody
references to.
<P>
<P>We've tried to solve this problem by employing a resource tracking
system which keeps track of all the resources allocated by all the
modules of BIRD, deallocates everything automatically when a module
shuts down and it is able to print out the list of resources and
the corresponding modules they are allocated by.
<P>
<P>Each allocated resource (from now we'll speak about allocated
resources only) is represented by a structure starting with a standard
header (struct <I>resource</I>) consisting of a list node (resources are
often linked to various lists) and a pointer to <I>resclass</I> -- a resource
class structure pointing to functions implementing generic resource
operations (such as freeing of the resource) for the particular resource
type.
<P>
<P>There exist the following types of resources:
<P>
<UL>
<LI><I>Resource pools</I> (<I>pool</I>)</LI>
<LI><I>Memory blocks</I></LI>
<LI><I>Linear memory pools</I> (<I>linpool</I>)</LI>
<LI><I>Slabs</I> (<I>slab</I>)</LI>
<LI><I>Events</I> (<I>event</I>) </LI>
<LI><I>Timers</I> (<I>timer</I>) </LI>
<LI><I>Sockets</I> (<I>socket</I>) </LI>
</UL>
<H2><A NAME="ss8.2">8.2</A> <A HREF="prog.html#toc8.2">Resource pools</A>
</H2>

<P>
<P>Resource pools (<I>pool</I>) are just containers holding a list of
other resources. Freeing a pool causes all the listed resources
to be freed as well. Each existing <I>resource</I> is linked to some pool
except for a root pool which isn't linked anywhere, so all the
resources form a tree structure with internal nodes corresponding
to pools and leaves being the other resources.
<P>Example: Almost all modules of BIRD have their private pool which
is freed upon shutdown of the module.
<P>
<P><HR><H3>Function</H3>
<P><I>pool *</I>
<B>rp_new</B>
(<I>pool *</I> <B>p</B>, <I>char *</I> <B>name</B>) --     create a resource pool
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>parent pool
<DT><I>char *</I> <B>name</B><DD><P>pool name (to be included in debugging dumps)
</DL>
<H3>Description</H3>
<P><B>rp_new()</B> creates a new resource pool inside the specified
parent pool.


<HR><H3>Function</H3>
<P><I>void</I>
<B>rmove</B>
(<I>void *</I> <B>res</B>, <I>pool *</I> <B>p</B>) --     move a resource
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>res</B><DD><P>resource
<DT><I>pool *</I> <B>p</B><DD><P>pool to move the resource to
</DL>
<H3>Description</H3>
<P><B>rmove()</B> moves a resource from one pool to another.


<HR><H3>Function</H3>
<P><I>void</I>
<B>rfree</B>
(<I>void *</I> <B>res</B>) --     free a resource
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>res</B><DD><P>resource
</DL>
<H3>Description</H3>
<P><B>rfree()</B> frees the given resource and all information associated
with it. In case it's a resource pool, it also frees all the objects
living inside the pool.
<P>It works by calling a class-specific freeing function.


<HR><H3>Function</H3>
<P><I>void</I>
<B>rdump</B>
(<I>void *</I> <B>res</B>) --     dump a resource
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>res</B><DD><P>resource
</DL>
<H3>Description</H3>
<P>This function prints out all available information about the given
resource to the debugging output.
<P>It works by calling a class-specific dump function.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>ralloc</B>
(<I>pool *</I> <B>p</B>, <I>struct resclass *</I> <B>c</B>) --     create a resource
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool to create the resource in
<DT><I>struct resclass *</I> <B>c</B><DD><P>class of the new resource
</DL>
<H3>Description</H3>
<P>This function is called by the resource classes to create a new
resource of the specified class and link it to the given pool.
Allocated memory is zeroed. Size of the resource structure is taken
from the <B>size</B> field of the <I>resclass</I>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>rlookup</B>
(<I>unsigned long</I> <B>a</B>) --     look up a memory location
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>unsigned long</I> <B>a</B><DD><P>memory address
</DL>
<H3>Description</H3>
<P>This function examines all existing resources to see whether
the address <B>a</B> is inside any resource. It's used for debugging
purposes only.
<P>It works by calling a class-specific lookup function for each
resource.


<HR><H3>Function</H3>
<P><I>void</I>
<B>resource_init</B>
(<B>void</B>) --     initialize the resource manager
<P>
<H3>Description</H3>
<P>
<P>This function is called during BIRD startup. It initializes
all data structures of the resource manager and creates the
root pool.

<H2><A NAME="ss8.3">8.3</A> <A HREF="prog.html#toc8.3">Memory blocks</A>
</H2>

<P>
<P>Memory blocks are pieces of contiguous allocated memory.
They are a bit non-standard since they are represented not by a pointer
to <I>resource</I>, but by a void pointer to the start of data of the
memory block. All memory block functions know how to locate the header
given the data pointer.
<P>Example: All "unique" data structures such as hash tables are allocated
as memory blocks.
<P>
<P><HR><H3>Function</H3>
<P><I>void *</I>
<B>mb_alloc</B>
(<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) --     allocate a memory block
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool
<DT><I>unsigned</I> <B>size</B><DD><P>size of the block
</DL>
<H3>Description</H3>
<P><B>mb_alloc()</B> allocates memory of a given size and creates
a memory block resource representing this memory chunk
in the pool <B>p</B>.
<P>Please note that <B>mb_alloc()</B> returns a pointer to the memory
chunk, not to the resource, hence you have to free it using
<B>mb_free()</B>, not <B>rfree()</B>.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>mb_allocz</B>
(<I>pool *</I> <B>p</B>, <I>unsigned</I> <B>size</B>) --     allocate and clear a memory block
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool
<DT><I>unsigned</I> <B>size</B><DD><P>size of the block
</DL>
<H3>Description</H3>
<P><B>mb_allocz()</B> allocates memory of a given size, initializes it to
zeroes and creates a memory block resource representing this memory
chunk in the pool <B>p</B>.
<P>Please note that <B>mb_allocz()</B> returns a pointer to the memory
chunk, not to the resource, hence you have to free it using
<B>mb_free()</B>, not <B>rfree()</B>.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>mb_realloc</B>
(<I>void *</I> <B>m</B>, <I>unsigned</I> <B>size</B>) --     reallocate a memory block
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>m</B><DD><P>memory block
<DT><I>unsigned</I> <B>size</B><DD><P>new size of the block
</DL>
<H3>Description</H3>
<P><B>mb_realloc()</B> changes the size of the memory block <B>m</B> to a given size.
The contents will be unchanged to the minimum of the old and new sizes;
newly allocated memory will be uninitialized. Contrary to <B>realloc()</B>
behavior, <B>m</B> must be non-NULL, because the resource pool is inherited
from it.
<P>Like <B>mb_alloc()</B>, <B>mb_realloc()</B> also returns a pointer to the memory
chunk, not to the resource, hence you have to free it using
<B>mb_free()</B>, not <B>rfree()</B>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>mb_free</B>
(<I>void *</I> <B>m</B>) --     free a memory block
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>m</B><DD><P>memory block
</DL>
<H3>Description</H3>
<P><B>mb_free()</B> frees all memory associated with the block <B>m</B>.

<H2><A NAME="ss8.4">8.4</A> <A HREF="prog.html#toc8.4">Linear memory pools</A>
</H2>

<P>
<P>Linear memory pools are collections of memory blocks which
support very fast allocation of new blocks, but are able to free only
the whole collection at once.
<P>Example: Each configuration is described by a complex system of structures,
linked lists and function trees which are all allocated from a single linear
pool, thus they can be freed at once when the configuration is no longer used.
<P>
<P><HR><H3>Function</H3>
<P><I>linpool *</I>
<B>lp_new</B>
(<I>pool *</I> <B>p</B>, <I>uint</I> <B>blk</B>) --     create a new linear memory pool
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool
<DT><I>uint</I> <B>blk</B><DD><P>block size
</DL>
<H3>Description</H3>
<P><B>lp_new()</B> creates a new linear memory pool resource inside the pool <B>p</B>.
The linear pool consists of a list of memory chunks of size at least
<B>blk</B>.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>lp_alloc</B>
(<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) --     allocate memory from a <I>linpool</I>
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
<DT><I>uint</I> <B>size</B><DD><P>amount of memory
</DL>
<H3>Description</H3>
<P><B>lp_alloc()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B>
and it returns a pointer to the allocated memory.
<P>It works by trying to find free space in the last memory chunk
associated with the <I>linpool</I> and creating a new chunk of the standard
size (as specified during <B>lp_new()</B>) if the free space is too small
to satisfy the allocation. If <B>size</B> is too large to fit in a standard
size chunk, an "overflow" chunk is created for it instead.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>lp_allocu</B>
(<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) --     allocate unaligned memory from a <I>linpool</I>
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
<DT><I>uint</I> <B>size</B><DD><P>amount of memory
</DL>
<H3>Description</H3>
<P><B>lp_allocu()</B> allocates <B>size</B> bytes of memory from a <I>linpool</I> <B>m</B>
and it returns a pointer to the allocated memory. It doesn't
attempt to align the memory block, giving a very efficient way
how to allocate strings without any space overhead.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>lp_allocz</B>
(<I>linpool *</I> <B>m</B>, <I>uint</I> <B>size</B>) --     allocate cleared memory from a <I>linpool</I>
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
<DT><I>uint</I> <B>size</B><DD><P>amount of memory
</DL>
<H3>Description</H3>
<P>This function is identical to <B>lp_alloc()</B> except that it
clears the allocated memory block.


<HR><H3>Function</H3>
<P><I>void</I>
<B>lp_flush</B>
(<I>linpool *</I> <B>m</B>) --     flush a linear memory pool
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>linpool *</I> <B>m</B><DD><P>linear memory pool
</DL>
<H3>Description</H3>
<P>This function frees the whole contents of the given <I>linpool</I> <B>m</B>,
but leaves the pool itself.

<H2><A NAME="ss8.5">8.5</A> <A HREF="prog.html#toc8.5">Slabs</A>
</H2>

<P>
<P>Slabs are collections of memory blocks of a fixed size.
They support very fast allocation and freeing of such blocks, prevent memory
fragmentation and optimize L2 cache usage. Slabs have been invented by Jeff Bonwick
and published in USENIX proceedings as `The Slab Allocator: An Object-Caching Kernel
Memory Allocator'. Our implementation follows this article except that we don't use
constructors and destructors.
<P>When the <CODE>DEBUGGING</CODE> switch is turned on, we automatically fill all
newly allocated and freed blocks with a special pattern to make detection
of use of uninitialized or already freed memory easier.
<P>Example: Nodes of a FIB are allocated from a per-FIB Slab.
<P>
<P><HR><H3>Function</H3>
<P><I>slab *</I>
<B>sl_new</B>
(<I>pool *</I> <B>p</B>, <I>uint</I> <B>size</B>) --     create a new Slab
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>resource pool
<DT><I>uint</I> <B>size</B><DD><P>block size
</DL>
<H3>Description</H3>
<P>This function creates a new Slab resource from which
objects of size <B>size</B> can be allocated.


<HR><H3>Function</H3>
<P><I>void *</I>
<B>sl_alloc</B>
(<I>slab *</I> <B>s</B>) --     allocate an object from Slab
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>slab *</I> <B>s</B><DD><P>slab
</DL>
<H3>Description</H3>
<P><B>sl_alloc()</B> allocates space for a single object from the
Slab and returns a pointer to the object.


<HR><H3>Function</H3>
<P><I>void</I>
<B>sl_free</B>
(<I>slab *</I> <B>s</B>, <I>void *</I> <B>oo</B>) --     return a free object back to a Slab
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>slab *</I> <B>s</B><DD><P>slab
<DT><I>void *</I> <B>oo</B><DD><P>object returned by <B>sl_alloc()</B>
</DL>
<H3>Description</H3>
<P>This function frees memory associated with the object <B>oo</B>
and returns it back to the Slab <B>s</B>.

<H2><A NAME="ss8.6">8.6</A> <A HREF="prog.html#toc8.6">Events</A>
</H2>

<P>
<P>Events are there to keep track of deferred execution.
Since BIRD is single-threaded, it requires long lasting tasks to be split to smaller
parts, so that no module can monopolize the CPU. To split such a task, just create
an <I>event</I> resource, point it to the function you want to have called and call <B>ev_schedule()</B>
to ask the core to run the event when nothing more important requires attention.
<P>You can also define your own event lists (the <I>event_list</I> structure), enqueue your
events in them and explicitly ask to run them.
<P>
<P><HR><H3>Function</H3>
<P><I>event *</I>
<B>ev_new</B>
(<I>pool *</I> <B>p</B>) --     create a new event
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>resource pool
</DL>
<H3>Description</H3>
<P>This function creates a new event resource. To use it,
you need to fill the structure fields and call <B>ev_schedule()</B>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>ev_run</B>
(<I>event *</I> <B>e</B>) --     run an event
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>event *</I> <B>e</B><DD><P>an event
</DL>
<H3>Description</H3>
<P>This function explicitly runs the event <B>e</B> (calls its hook
function) and removes it from an event list if it's linked to any.
<P>From the hook function, you can call <B>ev_enqueue()</B> or <B>ev_schedule()</B>
to re-add the event.


<HR><H3>Function</H3>
<P><I>void</I>
<B>ev_enqueue</B>
(<I>event_list *</I> <B>l</B>, <I>event *</I> <B>e</B>) --     enqueue an event
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>event_list *</I> <B>l</B><DD><P>an event list
<DT><I>event *</I> <B>e</B><DD><P>an event
</DL>
<H3>Description</H3>
<P><B>ev_enqueue()</B> stores the event <B>e</B> to the specified event
list <B>l</B> which can be run by calling <B>ev_run_list()</B>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>ev_schedule</B>
(<I>event *</I> <B>e</B>) --     schedule an event
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>event *</I> <B>e</B><DD><P>an event
</DL>
<H3>Description</H3>
<P>This function schedules an event by enqueueing it to a system-wide
event list which is run by the platform dependent code whenever
appropriate.


<HR><H3>Function</H3>
<P><I>int</I>
<B>ev_run_list</B>
(<I>event_list *</I> <B>l</B>) --     run an event list
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>event_list *</I> <B>l</B><DD><P>an event list
</DL>
<H3>Description</H3>
<P>This function calls <B>ev_run()</B> for all events enqueued in the list <B>l</B>.

<H2><A NAME="ss8.7">8.7</A> <A HREF="prog.html#toc8.7">Timers</A>
</H2>

<P>
<P>Timers are resources which represent a wish of a module to call
a function at the specified time. The platform dependent code
doesn't guarantee exact timing, only that a timer function
won't be called before the requested time.
<P>In BIRD, time is represented by values of the <I>bird_clock_t</I> type
which are integral numbers interpreted as a relative number of seconds since
some fixed time point in past. The current time can be read
from variable <B>now</B> with reasonable accuracy and is monotonic. There is also
a current 'absolute' time in variable <B>now_real</B> reported by OS.
<P>Each timer is described by a <I>timer</I> structure containing a pointer
to the handler function (<B>hook</B>), data private to this function (<B>data</B>),
time the function should be called at (<B>expires</B>, 0 for inactive timers),
for the other fields see <CODE>timer.h</CODE>.
<P>
<P><HR><H3>Function</H3>
<P><I>timer *</I>
<B>tm_new</B>
(<I>pool *</I> <B>p</B>) --     create a timer
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool
</DL>
<H3>Description</H3>
<P>This function creates a new timer resource and returns
a pointer to it. To use the timer, you need to fill in
the structure fields and call <B>tm_start()</B> to start timing.


<HR><H3>Function</H3>
<P><I>void</I>
<B>tm_start</B>
(<I>timer *</I> <B>t</B>, <I>unsigned</I> <B>after</B>) --     start a timer
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>timer *</I> <B>t</B><DD><P>timer
<DT><I>unsigned</I> <B>after</B><DD><P>number of seconds the timer should be run after
</DL>
<H3>Description</H3>
<P>This function schedules the hook function of the timer to
be called after <B>after</B> seconds. If the timer has been already
started, it's <B>expire</B> time is replaced by the new value.
<P>You can have set the <B>randomize</B> field of <B>t</B>, the timeout
will be increased by a random number of seconds chosen
uniformly from range 0 .. <B>randomize</B>.
<P>You can call <B>tm_start()</B> from the handler function of the timer
to request another run of the timer. Also, you can set the <B>recurrent</B>
field to have the timer re-added automatically with the same timeout.


<HR><H3>Function</H3>
<P><I>void</I>
<B>tm_stop</B>
(<I>timer *</I> <B>t</B>) --     stop a timer
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>timer *</I> <B>t</B><DD><P>timer
</DL>
<H3>Description</H3>
<P>This function stops a timer. If the timer is already stopped,
nothing happens.


<HR><H3>Function</H3>
<P><I>bird_clock_t</I>
<B>tm_parse_datetime</B>
(<I>char *</I> <B>x</B>) --     parse a date and time
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>char *</I> <B>x</B><DD><P>datetime string
</DL>
<H3>Description</H3>
<P><B>tm_parse_datetime()</B> takes a textual representation of
a date and time (dd-mm-yyyy hh:mm:ss)
and converts it to the corresponding value of type <I>bird_clock_t</I>.


<HR><H3>Function</H3>
<P><I>bird_clock_t</I>
<B>tm_parse_date</B>
(<I>char *</I> <B>x</B>) --     parse a date
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>char *</I> <B>x</B><DD><P>date string
</DL>
<H3>Description</H3>
<P><B>tm_parse_date()</B> takes a textual representation of a date (dd-mm-yyyy)
and converts it to the corresponding value of type <I>bird_clock_t</I>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>tm_format_datetime</B>
(<I>char *</I> <B>x</B>, <I>struct timeformat *</I> <B>fmt_spec</B>, <I>bird_clock_t</I> <B>t</B>) --     convert date and time to textual representation
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>char *</I> <B>x</B><DD><P>destination buffer of size <I>TM_DATETIME_BUFFER_SIZE</I>
<DT><I>struct timeformat *</I> <B>fmt_spec</B><DD><P>specification of resulting textual representation of the time
<DT><I>bird_clock_t</I> <B>t</B><DD><P>time
</DL>
<H3>Description</H3>
<P>This function formats the given relative time value <B>t</B> to a textual
date/time representation (dd-mm-yyyy hh:mm:ss) in real time.

<H2><A NAME="ss8.8">8.8</A> <A HREF="prog.html#toc8.8">Sockets</A>
</H2>

<P>
<P>Socket resources represent network connections. Their data structure (<I>socket</I>)
contains a lot of fields defining the exact type of the socket, the local and
remote addresses and ports, pointers to socket buffers and finally pointers to
hook functions to be called when new data have arrived to the receive buffer
(<B>rx_hook</B>), when the contents of the transmit buffer have been transmitted
(<B>tx_hook</B>) and when an error or connection close occurs (<B>err_hook</B>).
<P>Freeing of sockets from inside socket hooks is perfectly safe.
<P>
<P><HR><H3>Function</H3>
<P><I>int</I>
<B>sk_setup_multicast</B>
(<I>sock *</I> <B>s</B>) --     enable multicast for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
</DL>
<H3>Description</H3>
<P>Prepare transmission of multicast packets for given datagram socket.
The socket must have defined <B>iface</B>.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_join_group</B>
(<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) --     join multicast group for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address
</DL>
<H3>Description</H3>
<P>Join multicast group for given datagram socket and associated interface.
The socket must have defined <B>iface</B>.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_leave_group</B>
(<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>maddr</B>) --     leave multicast group for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>ip_addr</I> <B>maddr</B><DD><P>multicast address
</DL>
<H3>Description</H3>
<P>Leave multicast group for given datagram socket and associated interface.
The socket must have defined <B>iface</B>.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_setup_broadcast</B>
(<I>sock *</I> <B>s</B>) --     enable broadcast for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
</DL>
<H3>Description</H3>
<P>Allow reception and transmission of broadcast packets for given datagram
socket. The socket must have defined <B>iface</B>. For transmission, packets should
be send to <B>brd</B> address of <B>iface</B>.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_set_ttl</B>
(<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) --     set transmit TTL for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>int</I> <B>ttl</B><DD><P>TTL value
</DL>
<H3>Description</H3>
<P>Set TTL for already opened connections when TTL was not set before. Useful
for accepted connections when different ones should have different TTL.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_set_min_ttl</B>
(<I>sock *</I> <B>s</B>, <I>int</I> <B>ttl</B>) --     set minimal accepted TTL for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>int</I> <B>ttl</B><DD><P>TTL value
</DL>
<H3>Description</H3>
<P>Set minimal accepted TTL for given socket. Can be used for TTL security.
implementations.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_set_md5_auth</B>
(<I>sock *</I> <B>s</B>, <I>ip_addr</I> <B>local</B>, <I>ip_addr</I> <B>remote</B>, <I>struct iface *</I> <B>ifa</B>, <I>char *</I> <B>passwd</B>, <I>int</I> <B>setkey</B>) --     add / remove MD5 security association for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>ip_addr</I> <B>local</B><DD><P>IP address of local side
<DT><I>ip_addr</I> <B>remote</B><DD><P>IP address of remote side
<DT><I>struct iface *</I> <B>ifa</B><DD><P>Interface for link-local IP address
<DT><I>char *</I> <B>passwd</B><DD><P>Password used for MD5 authentication
<DT><I>int</I> <B>setkey</B><DD><P>Update also system SA/SP database
</DL>
<H3>Description</H3>
<P>In TCP MD5 handling code in kernel, there is a set of security associations
used for choosing password and other authentication parameters according to
the local and remote address. This function is useful for listening socket,
for active sockets it may be enough to set s-&gt;password field.
<P>When called with passwd != NULL, the new pair is added,
When called with passwd == NULL, the existing pair is removed.
<P>Note that while in Linux, the MD5 SAs are specific to socket, in BSD they are
stored in global SA/SP database (but the behavior also must be enabled on
per-socket basis). In case of multiple sockets to the same neighbor, the
socket-specific state must be configured for each socket while global state
just once per src-dst pair. The <B>setkey</B> argument controls whether the global
state (SA/SP database) is also updated.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_set_ipv6_checksum</B>
(<I>sock *</I> <B>s</B>, <I>int</I> <B>offset</B>) --     specify IPv6 checksum offset for given socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>int</I> <B>offset</B><DD><P>offset
</DL>
<H3>Description</H3>
<P>Specify IPv6 checksum field offset for given raw IPv6 socket. After that, the
kernel will automatically fill it for outgoing packets and check it for
incoming packets. Should not be used on ICMPv6 sockets, where the position is
known to the kernel.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>sock *</I>
<B>sock_new</B>
(<I>pool *</I> <B>p</B>) --     create a socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>pool *</I> <B>p</B><DD><P>pool
</DL>
<H3>Description</H3>
<P>This function creates a new socket resource. If you want to use it,
you need to fill in all the required fields of the structure and
call <B>sk_open()</B> to do the actual opening of the socket.
<P>The real function name is <B>sock_new()</B>, <B>sk_new()</B> is a macro wrapper
to avoid collision with OpenSSL.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_open</B>
(<I>sock *</I> <B>s</B>) --     open a socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
</DL>
<H3>Description</H3>
<P>This function takes a socket resource created by <B>sk_new()</B> and
initialized by the user and binds a corresponding network connection
to it.
<H3>Result</H3>
<P>0 for success, -1 for an error.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_send</B>
(<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>) --     send data to a socket
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send
</DL>
<H3>Description</H3>
<P>This function sends <B>len</B> bytes of data prepared in the
transmit buffer of the socket <B>s</B> to the network connection.
If the packet can be sent immediately, it does so and returns
1, else it queues the packet for later processing, returns 0
and calls the <B>tx_hook</B> of the socket when the tranmission
takes place.


<HR><H3>Function</H3>
<P><I>int</I>
<B>sk_send_to</B>
(<I>sock *</I> <B>s</B>, <I>unsigned</I> <B>len</B>, <I>ip_addr</I> <B>addr</B>, <I>unsigned</I> <B>port</B>) --     send data to a specific destination
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>sock *</I> <B>s</B><DD><P>socket
<DT><I>unsigned</I> <B>len</B><DD><P>number of bytes to send
<DT><I>ip_addr</I> <B>addr</B><DD><P>IP address to send the packet to
<DT><I>unsigned</I> <B>port</B><DD><P>port to send the packet to
</DL>
<H3>Description</H3>
<P>This is a <B>sk_send()</B> replacement for connection-less packet sockets
which allows destination of the packet to be chosen dynamically.
Raw IP sockets should use 0 for <B>port</B>.


<HR><H3>Function</H3>
<P><I>void</I>
<B>io_log_event</B>
(<I>void *</I> <B>hook</B>, <I>void *</I> <B>data</B>) --     mark approaching event into event log
<P>
<H3>Arguments</H3>
<P>
<DL>
<DT><I>void *</I> <B>hook</B><DD><P>event hook address
<DT><I>void *</I> <B>data</B><DD><P>event data address
</DL>
<H3>Description</H3>
<P>Store info (hook, data, timestamp) about the following internal event into
a circular event log (<B>event_log</B>). When latency tracking is enabled, the log
entry is kept open (in <B>event_open</B>) so the duration can be filled later.

<P>
<HR>
Next
<A HREF="prog-7.html">Previous</A>
<A HREF="prog.html#toc8">Contents</A>
</BODY>
</HTML>
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>