1 /* -*- Mode: c; tab-width: 8; indent-tabs-mode: 1; c-basic-offset: 8; -*- */ 2 /* 3 * Copyright (c) 1993, 1994, 1995, 1996, 1997 4 * The Regents of the University of California. 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 * 3. All advertising materials mentioning features or use of this software 15 * must display the following acknowledgement: 16 * This product includes software developed by the Computer Systems 17 * Engineering Group at Lawrence Berkeley Laboratory. 18 * 4. Neither the name of the University nor of the Laboratory may be used 19 * to endorse or promote products derived from this software without 20 * specific prior written permission. 21 * 22 * THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25 * ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32 * SUCH DAMAGE. 33 */ 34 35 #ifndef lib_pcap_funcattrs_h 36 #define lib_pcap_funcattrs_h 37 38 #include <pcap/compiler-tests.h> 39 40 /* 41 * Attributes to apply to functions and their arguments, using various 42 * compiler-specific extensions. 43 */ 44 45 /* 46 * PCAP_API_DEF must be used when defining *data* exported from 47 * libpcap. It can be used when defining *functions* exported 48 * from libpcap, but it doesn't have to be used there. It 49 * should not be used in declarations in headers. 50 * 51 * PCAP_API must be used when *declaring* data or functions 52 * exported from libpcap; PCAP_API_DEF won't work on all platforms. 53 */ 54 55 #if defined(_WIN32) 56 /* 57 * For Windows: 58 * 59 * when building libpcap: 60 * 61 * if we're building it as a DLL, we have to declare API 62 * functions with __declspec(dllexport); 63 * 64 * if we're building it as a static library, we don't want 65 * to do so. 66 * 67 * when using libpcap: 68 * 69 * if we're using the DLL, calls to its functions are a 70 * little more efficient if they're declared with 71 * __declspec(dllimport); 72 * 73 * if we're not using the dll, we don't want to declare 74 * them that way. 75 * 76 * So: 77 * 78 * if pcap_EXPORTS is defined, we define PCAP_API_DEF as 79 * __declspec(dllexport); 80 * 81 * if PCAP_DLL is defined, we define PCAP_API_DEF as 82 * __declspec(dllimport); 83 * 84 * otherwise, we define PCAP_API_DEF as nothing. 85 */ 86 #if defined(pcap_EXPORTS) 87 /* 88 * We're compiling libpcap as a DLL, so we should export functions 89 * in our API. 90 */ 91 #define PCAP_API_DEF __declspec(dllexport) 92 #elif defined(PCAP_DLL) 93 /* 94 * We're using libpcap as a DLL, so the calls will be a little more 95 * efficient if we explicitly import the functions. 96 */ 97 #define PCAP_API_DEF __declspec(dllimport) 98 #else 99 /* 100 * Either we're building libpcap as a static library, or we're using 101 * it as a static library, or we don't know for certain that we're 102 * using it as a dynamic library, so neither import nor export the 103 * functions explicitly. 104 */ 105 #define PCAP_API_DEF 106 #endif 107 #elif defined(MSDOS) 108 /* XXX - does this need special treatment? */ 109 #define PCAP_API_DEF 110 #else /* UN*X */ 111 #ifdef pcap_EXPORTS 112 /* 113 * We're compiling libpcap as a (dynamic) shared library, so we should 114 * export functions in our API. The compiler might be configured not 115 * to export functions from a shared library by default, so we might 116 * have to explicitly mark functions as exported. 117 */ 118 #if PCAP_IS_AT_LEAST_GNUC_VERSION(3,4) \ 119 || PCAP_IS_AT_LEAST_XL_C_VERSION(12,0) 120 /* 121 * GCC 3.4 and later, or some compiler asserting compatibility with 122 * GCC 3.4 and later, or XL C 13.0 and later, so we have 123 * __attribute__((visibility()). 124 */ 125 #define PCAP_API_DEF __attribute__((visibility("default"))) 126 #elif PCAP_IS_AT_LEAST_SUNC_VERSION(5,5) 127 /* 128 * Sun C 5.5 and later, so we have __global. 129 * (Sun C 5.9 and later also have __attribute__((visibility()), 130 * but there's no reason to prefer it with Sun C.) 131 */ 132 #define PCAP_API_DEF __global 133 #else 134 /* 135 * We don't have anything to say. 136 */ 137 #define PCAP_API_DEF 138 #endif 139 #else 140 /* 141 * We're not building libpcap. 142 */ 143 #define PCAP_API_DEF 144 #endif 145 #endif /* _WIN32/MSDOS/UN*X */ 146 147 #define PCAP_API PCAP_API_DEF extern 148 149 /* 150 * Definitions to 1) indicate what version of libpcap first had a given 151 * API and 2) allow upstream providers whose build environments allow 152 * APIs to be designated as "first available in this release" to do so 153 * by appropriately defining them. 154 * 155 * On macOS, Apple can tweak this to make various APIs "weakly exported 156 * symbols" to make it easier for software that's distributed in binary 157 * form and that uses libpcap to run on multiple macOS versions and use 158 * new APIs when available. (Yes, such third-party software exists - 159 * Wireshark provides binary packages for macOS, for example. tcpdump 160 * doesn't count, as that's provided by Apple, so each release can 161 * come with a version compiled to use the APIs present in that release.) 162 * 163 * We don't tweak it that way ourselves because, if you're building 164 * and installing libpcap on macOS yourself, the APIs will be available 165 * no matter what OS version you're installing it on. 166 * 167 * For other platforms, we don't define them, leaving it up to 168 * others to do so based on their OS versions, if appropriate. 169 * 170 * We start with libpcap 0.4, as that was the last LBL release, and 171 * I've never seen earlier releases. 172 */ 173 #ifdef __APPLE__ 174 /* 175 * Apple - insert #include <os/availability.h> here, and replace the two 176 * #defines below with: 177 * 178 * #define PCAP_API_AVAILABLE API_AVAILABLE 179 * 180 * and adjust availabilities as necessary, including adding information 181 * about operating systems other than macOS. 182 */ 183 #define PCAP_API_AVAILABLE(...) 184 #define PCAP_AVAILABLE_0_4 PCAP_API_AVAILABLE(macos(10.0)) 185 #define PCAP_AVAILABLE_0_5 PCAP_API_AVAILABLE(macos(10.0)) 186 #define PCAP_AVAILABLE_0_6 PCAP_API_AVAILABLE(macos(10.1)) 187 #define PCAP_AVAILABLE_0_7 PCAP_API_AVAILABLE(macos(10.4)) 188 #define PCAP_AVAILABLE_0_8 PCAP_API_AVAILABLE(macos(10.4)) 189 #define PCAP_AVAILABLE_0_9 PCAP_API_AVAILABLE(macos(10.5)) 190 #define PCAP_AVAILABLE_1_0 PCAP_API_AVAILABLE(macos(10.6)) 191 /* #define PCAP_AVAILABLE_1_1 no routines added to the API */ 192 #define PCAP_AVAILABLE_1_2 PCAP_API_AVAILABLE(macos(10.9)) 193 /* #define PCAP_AVAILABLE_1_3 no routines added to the API */ 194 /* #define PCAP_AVAILABLE_1_4 no routines added to the API */ 195 #define PCAP_AVAILABLE_1_5 PCAP_API_AVAILABLE(macos(10.10)) 196 /* #define PCAP_AVAILABLE_1_6 no routines added to the API */ 197 #define PCAP_AVAILABLE_1_7 PCAP_API_AVAILABLE(macos(10.12)) 198 #define PCAP_AVAILABLE_1_8 PCAP_API_AVAILABLE(macos(10.13)) 199 #define PCAP_AVAILABLE_1_9 PCAP_API_AVAILABLE(macos(10.13)) 200 /* 201 * The remote capture APIs are, in 1.9 and 1.10, usually only 202 * available in the library if the library was built with 203 * remote capture enabled. 204 * 205 * However, macOS Sonoma provides stub versions of those routine, 206 * which return an error. This means that we need a separate 207 * availability indicator macro for those routines, so that 208 * progras built on macOS Sonoma that attempt to use weak 209 * importing and availability tests to use those routines 210 * if they're available will get those routines weakly imported, 211 * so that if they're run on releases prior to Sonoma, they 212 * won't get an error from dyld about those routines being 213 * missing in libpcap. (If they don't use run-time availability 214 * tests, they will, instead, get crashes if they call one of 215 * those routines, as the addresses of those routines will be 216 * set to 0 by dyld, meaning the program will dereference a 217 * null pointer and crash when trying to call them.) 218 * 219 * (Not that it's useful to use those routines *anyway*, as they're 220 * stubs that always fail. The stubs were necessary in order to 221 * support weak exporting at all.) 222 */ 223 #define PCAP_AVAILABLE_1_9_REMOTE PCAP_API_AVAILABLE(macos(14.0)) 224 #define PCAP_AVAILABLE_1_10 PCAP_API_AVAILABLE(macos(12.1)) 225 #define PCAP_AVAILABLE_1_10_REMOTE PCAP_API_AVAILABLE(macos(14.0)) 226 #define PCAP_AVAILABLE_1_11 /* not released yet, so not in macOS yet */ 227 #else /* __APPLE__ */ 228 #define PCAP_AVAILABLE_0_4 229 #define PCAP_AVAILABLE_0_5 230 #define PCAP_AVAILABLE_0_6 231 #define PCAP_AVAILABLE_0_7 232 #define PCAP_AVAILABLE_0_8 233 #define PCAP_AVAILABLE_0_9 234 #define PCAP_AVAILABLE_1_0 235 /* #define PCAP_AVAILABLE_1_1 no routines added to the API */ 236 #define PCAP_AVAILABLE_1_2 237 /* #define PCAP_AVAILABLE_1_3 no routines added to the API */ 238 /* #define PCAP_AVAILABLE_1_4 no routines added to the API */ 239 #define PCAP_AVAILABLE_1_5 240 /* #define PCAP_AVAILABLE_1_6 no routines added to the API */ 241 #define PCAP_AVAILABLE_1_7 242 #define PCAP_AVAILABLE_1_8 243 #define PCAP_AVAILABLE_1_9 244 #define PCAP_AVAILABLE_1_9_REMOTE 245 #define PCAP_AVAILABLE_1_10 246 #define PCAP_AVAILABLE_1_10_REMOTE 247 #define PCAP_AVAILABLE_1_11 248 #endif /* __APPLE__ */ 249 250 /* 251 * PCAP_NORETURN, before a function declaration, means "this function 252 * never returns". (It must go before the function declaration, e.g. 253 * "extern PCAP_NORETURN func(...)" rather than after the function 254 * declaration, as the MSVC version has to go before the declaration.) 255 * 256 * PCAP_NORETURN_DEF, before a function *definition*, means "this 257 * function never returns"; it would be used only for static functions 258 * that are defined before any use, and thus have no declaration. 259 * (MSVC doesn't support that; I guess the "decl" in "__declspec" 260 * means "declaration", and __declspec doesn't work with definitions.) 261 */ 262 #if __has_attribute(noreturn) \ 263 || PCAP_IS_AT_LEAST_GNUC_VERSION(2,5) \ 264 || PCAP_IS_AT_LEAST_SUNC_VERSION(5,9) \ 265 || PCAP_IS_AT_LEAST_XL_C_VERSION(7,0) \ 266 || PCAP_IS_AT_LEAST_HP_C_VERSION(6,10) \ 267 || __TINYC__ 268 /* 269 * Compiler with support for __attribute((noreturn)), or GCC 2.5 and 270 * later, or some compiler asserting compatibility with GCC 2.5 and 271 * later, or Solaris Studio 12 (Sun C 5.9) and later, or IBM XL C 7.0 272 * and later (do any earlier versions of XL C support this?), or HP aCC 273 * A.06.10 and later, or current TinyCC. 274 */ 275 #define PCAP_NORETURN __attribute((noreturn)) 276 #define PCAP_NORETURN_DEF __attribute((noreturn)) 277 #elif defined(_MSC_VER) 278 /* 279 * MSVC. 280 */ 281 #define PCAP_NORETURN __declspec(noreturn) 282 #define PCAP_NORETURN_DEF 283 #else 284 #define PCAP_NORETURN 285 #define PCAP_NORETURN_DEF 286 #endif 287 288 /* 289 * PCAP_PRINTFLIKE(x,y), after a function declaration, means "this function 290 * does printf-style formatting, with the xth argument being the format 291 * string and the yth argument being the first argument for the format 292 * string". 293 */ 294 #if __has_attribute(__format__) \ 295 || PCAP_IS_AT_LEAST_GNUC_VERSION(2,3) \ 296 || PCAP_IS_AT_LEAST_XL_C_VERSION(7,0) \ 297 || PCAP_IS_AT_LEAST_HP_C_VERSION(6,10) 298 /* 299 * Compiler with support for it, or GCC 2.3 and later, or some compiler 300 * asserting compatibility with GCC 2.3 and later, or IBM XL C 7.0 301 * and later (do any earlier versions of XL C support this?), 302 * or HP aCC A.06.10 and later. 303 */ 304 #define PCAP_PRINTFLIKE(x,y) __attribute__((__format__(__printf__,x,y))) 305 #else 306 #define PCAP_PRINTFLIKE(x,y) 307 #endif 308 309 /* 310 * PCAP_DEPRECATED(func, msg), after a function declaration, marks the 311 * function as deprecated. 312 * 313 * The argument is a string giving the warning message to use if the 314 * compiler supports that. 315 */ 316 #if __has_attribute(deprecated) \ 317 || PCAP_IS_AT_LEAST_GNUC_VERSION(4,5) \ 318 || PCAP_IS_AT_LEAST_SUNC_VERSION(5,13) 319 /* 320 * Compiler that supports __has_attribute and __attribute__((deprecated)), 321 * or GCC 4.5 and later, or Sun/Oracle C 12.4 (Sun C 5.13) and later. 322 * 323 * Those support __attribute__((deprecated(msg))) (we assume, perhaps 324 * incorrectly, that anything that supports __has_attribute() is 325 * recent enough to support __attribute__((deprecated(msg)))). 326 */ 327 #define PCAP_DEPRECATED(msg) __attribute__((deprecated(msg))) 328 #elif PCAP_IS_AT_LEAST_GNUC_VERSION(3,1) 329 /* 330 * GCC 3.1 through 4.4. 331 * 332 * Those support __attribute__((deprecated)) but not 333 * __attribute__((deprecated(msg))). 334 */ 335 #define PCAP_DEPRECATED(msg) __attribute__((deprecated)) 336 #elif defined(_MSC_VER) && !defined(BUILDING_PCAP) 337 /* 338 * MSVC, and we're not building libpcap itself; it's VS 2015 339 * and later, so we have __declspec(deprecated(...)). 340 * 341 * If we *are* building libpcap, we don't want this, as it'll warn 342 * us even if we *define* the function. 343 */ 344 #define PCAP_DEPRECATED(msg) _declspec(deprecated(msg)) 345 #else 346 #define PCAP_DEPRECATED(msg) 347 #endif 348 349 /* 350 * For flagging arguments as format strings in MSVC. 351 */ 352 #ifdef _MSC_VER 353 #include <sal.h> 354 #define PCAP_FORMAT_STRING(p) _Printf_format_string_ p 355 #else 356 #define PCAP_FORMAT_STRING(p) p 357 #endif 358 359 #endif /* lib_pcap_funcattrs_h */ 360