1.\" $OpenBSD: rtalloc.9,v 1.12 2019/07/12 16:53:57 mpi Exp $ 2.\" 3.\" Copyright (c) 2014-2015 Martin Pieuchot 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 12 2019 $ 18.Dt RTALLOC 9 19.Os 20.Sh NAME 21.Nm rtalloc , 22.Nm rtalloc_mpath , 23.Nm rtisvalid , 24.Nm rtref , 25.Nm rtfree 26.Nd routing entry interface 27.Sh SYNOPSIS 28.In sys/types.h 29.In sys/socket.h 30.In net/route.h 31.Ft struct rtentry * 32.Fn rtalloc "struct sockaddr *dst" "int flags" "unsigned int rtableid" 33.Ft struct rtentry * 34.Fn rtalloc_mpath "struct sockaddr *dst" "uint32_t *src" "unsigned int rtableid" 35.Ft int 36.Fn rtisvalid "struct rtentry *rt" 37.Ft void 38.Fn rtref "struct rtentry *rt" 39.Ft void 40.Fn rtfree "struct rtentry *rt" 41.Sh DESCRIPTION 42The 43.Fn rtalloc 44function looks in the routing table 45.Fa rtableid 46for an entry matching 47.Fa dst . 48The following 49.Fa flags 50can be specified: 51.Bl -tag -width RT_RESOLVE -offset indent 52.It Dv RT_RESOLVE 53Allocate and return a cloned entry for 54.Fa dst 55if it does not exist and the lookup returned a cloning entry. 56.El 57.Pp 58The 59.Fn rtalloc_mpath 60function does the same as 61.Fn rtalloc 62with the 63.Dv RT_RESOLVE 64.Fa flag , 65but selects a multipath routing entry corresponding to 66.Fa src 67when possible. 68.Pp 69The 70.Fn rtisvalid 71function checks if the route entry 72.Fa rt 73is still valid and can be used. 74Cached entries that are no longer valid should be released by calling 75.Fn rtfree . 76.Pp 77The 78.Fn rtref 79function increments a reference to the routing entry 80.Fa rt . 81.Pp 82The 83.Fn rtfree 84function releases a reference to the routing entry 85.Fa rt , 86freeing it if the reference count drops to 0. 87If 88.Fa rt 89is a 90.Dv NULL 91pointer, no action occurs. 92.Sh CONTEXT 93.Fn rtalloc , 94.Fn rtalloc_mpath , 95.Fn rtisvalid , 96.Fn rtref , 97and 98.Fn rtfree 99can be called during autoconf, from process context, or from interrupt context. 100.Sh RETURN VALUES 101.Fn rtisvalid 102returns 1 if the route entry is valid, otherwise 0. 103.Sh SEE ALSO 104.Xr route 4 , 105.Xr rtable_walk 9 , 106.Xr rtrequest 9 107