1/*	$NetBSD: portset.h,v 1.7 2024/02/21 22:52:31 christos Exp $	*/
2
3/*
4 * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
5 *
6 * SPDX-License-Identifier: MPL-2.0
7 *
8 * This Source Code Form is subject to the terms of the Mozilla Public
9 * License, v. 2.0. If a copy of the MPL was not distributed with this
10 * file, you can obtain one at https://mozilla.org/MPL/2.0/.
11 *
12 * See the COPYRIGHT file distributed with this work for additional
13 * information regarding copyright ownership.
14 */
15
16/*! \file isc/portset.h
17 * \brief Transport Protocol Port Manipulation Module
18 *
19 * This module provides simple utilities to handle a set of transport protocol
20 * (UDP or TCP) port numbers, e.g., for creating an ACL list.  An isc_portset_t
21 * object is an opaque instance of a port set, for which the user can add or
22 * remove a specific port or a range of consecutive ports.  This object is
23 * expected to be used as a temporary work space only, and does not protect
24 * simultaneous access from multiple threads.  Therefore it must not be stored
25 * in a place that can be accessed from multiple threads.
26 */
27
28#pragma once
29
30/***
31 ***	Imports
32 ***/
33
34#include <stdbool.h>
35
36#include <isc/net.h>
37
38/***
39 *** Functions
40 ***/
41
42ISC_LANG_BEGINDECLS
43
44isc_result_t
45isc_portset_create(isc_mem_t *mctx, isc_portset_t **portsetp);
46/*%<
47 * Create a port set and initialize it as an empty set.
48 *
49 * Requires:
50 *\li	'mctx' to be valid.
51 *\li	'portsetp' to be non NULL and '*portsetp' to be NULL;
52 *
53 * Returns:
54 *\li	#ISC_R_SUCCESS
55 *\li	#ISC_R_NOMEMORY
56 */
57
58void
59isc_portset_destroy(isc_mem_t *mctx, isc_portset_t **portsetp);
60/*%<
61 * Destroy a port set.
62 *
63 * Requires:
64 *\li	'mctx' to be valid and must be the same context given when the port set
65 *       was created.
66 *\li	'*portsetp' to be a valid set.
67 */
68
69bool
70isc_portset_isset(isc_portset_t *portset, in_port_t port);
71/*%<
72 * Test whether the given port is stored in the portset.
73 *
74 * Requires:
75 *\li	'portset' to be a valid set.
76 *
77 * Returns
78 * \li	#true if the port is found, false otherwise.
79 */
80
81unsigned int
82isc_portset_nports(isc_portset_t *portset);
83/*%<
84 * Provides the number of ports stored in the given portset.
85 *
86 * Requires:
87 *\li	'portset' to be a valid set.
88 *
89 * Returns
90 * \li	the number of ports stored in portset.
91 */
92
93void
94isc_portset_add(isc_portset_t *portset, in_port_t port);
95/*%<
96 * Add the given port to the portset.  The port may or may not be stored in
97 * the portset.
98 *
99 * Requires:
100 *\li	'portlist' to be valid.
101 */
102
103void
104isc_portset_remove(isc_portset_t *portset, in_port_t port);
105/*%<
106 * Remove the given port to the portset.  The port may or may not be stored in
107 * the portset.
108 *
109 * Requires:
110 *\li	'portlist' to be valid.
111 */
112
113void
114isc_portset_addrange(isc_portset_t *portset, in_port_t port_lo,
115		     in_port_t port_hi);
116/*%<
117 * Add a subset of [port_lo, port_hi] (inclusive) to the portset.  Ports in the
118 * subset may or may not be stored in portset.
119 *
120 * Requires:
121 *\li	'portlist' to be valid.
122 *\li	port_lo <= port_hi
123 */
124
125void
126isc_portset_removerange(isc_portset_t *portset, in_port_t port_lo,
127			in_port_t port_hi);
128/*%<
129 * Subtract a subset of [port_lo, port_hi] (inclusive) from the portset.  Ports
130 * in the subset may or may not be stored in portset.
131 *
132 * Requires:
133 *\li	'portlist' to be valid.
134 *\li	port_lo <= port_hi
135 */
136
137ISC_LANG_ENDDECLS
138