contrib/libpcap/pcap_init.3pcap

   1 .\" Copyright (c) 1994, 1996, 1997
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that: (1) source code distributions
   6 .\" retain the above copyright notice and this paragraph in its entirety, (2)
   7 .\" distributions including binary code include the above copyright notice and
   8 .\" this paragraph in its entirety in the documentation or other materials
   9 .\" provided with the distribution, and (3) all advertising materials mentioning
  10 .\" features or use of this software display the following acknowledgement:
  11 .\" ``This product includes software developed by the University of California,
  12 .\" Lawrence Berkeley Laboratory and its contributors.'' Neither the name of
  13 .\" the University nor the names of its contributors may be used to endorse
  14 .\" or promote products derived from this software without specific prior
  15 .\" written permission.
  16 .\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
  17 .\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
  18 .\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  19 .\"
  20 .TH PCAP_INIT 3PCAP "4 May 2022"
  21 .SH NAME
  22 pcap_init \- initialize the library
  23 .SH SYNOPSIS
  24 .nf
  25 .ft B
  26 #include <pcap/pcap.h>
  27 .ft
  28 .LP
  29 .nf
  30 .ft B
  31 char errbuf[PCAP_ERRBUF_SIZE];
  32 .ft
  33 .LP
  34 .ft B
  35 int pcap_init(unsigned int opts, char *errbuf);
  36 .ft
  37 .fi
  38 .SH DESCRIPTION
  39 .BR pcap_init ()
  40 is used to initialize the Packet Capture library.
  41 .I opts
  42 specifies options for the library;
  43 currently, the options are:
  44 .TP
  45 .B PCAP_CHAR_ENC_LOCAL
  46 Treat all strings supplied as arguments, and return all strings to the
  47 caller, as being in the local character encoding.
  48 .TP
  49 .B PCAP_CHAR_ENC_UTF_8
  50 Treat all strings supplied as arguments, and return all strings to the
  51 caller, as being in UTF-8.
  52 .PP
  53 On UNIX-like systems, the local character encoding is assumed to be
  54 UTF-8, so no character encoding transformations are done.
  55 .PP
  56 On Windows, the local character encoding is the local ANSI code page.
  57 .PP
  58 If
  59 .BR pcap_init ()
  60 is not called, strings are treated as being in the local ANSI code page
  61 on Windows,
  62 .BR pcap_lookupdev (3PCAP)
  63 will succeed if there is a device on which to capture, and
  64 .BR pcap_create (3PCAP)
  65 makes an attempt to check whether the string passed as an argument is a
  66 UTF-16LE string - note that this attempt is unsafe, as it may run past
  67 the end of the string - to handle
  68 .BR pcap_lookupdev ()
  69 returning a UTF-16LE string. Programs that don't call
  70 .BR pcap_init ()
  71 should, on Windows, call
  72 .BR pcap_wsockinit ()
  73 to initialize Winsock; this is not necessary if
  74 .BR pcap_init ()
  75 is called, as
  76 .BR pcap_init ()
  77 will initialize Winsock itself on Windows.
  78 .SH RETURN VALUE
  79 .BR pcap_init ()
  80 returns
  81 .B 0
  82 on success and
  83 .B PCAP_ERROR
  84 on failure.
  85 If
  86 .B PCAP_ERROR
  87 is returned,
  88 .I errbuf
  89 is filled in with an appropriate error message.
  90 .I errbuf
  91 is assumed to be able to hold at least
  92 .B PCAP_ERRBUF_SIZE
  93 chars.
  94 .SH BACKWARD COMPATIBILITY
  95 This function became available in libpcap release 1.9.0.  In previous
  96 releases, on Windows, all strings supplied as arguments, and all strings
  97 returned to the caller, are in the local character encoding.
  98 .SH SEE ALSO
  99 .BR pcap (3PCAP)