src/mans/ping_setopt.pod

   1 =head1 NAME
   2
   3 ping_setopt - Set options for a liboping object
   4
   5 =head1 SYNOPSIS
   6
   7   #include <oping.h>
   8
   9   int ping_setopt (pingobj_t *obj, int opt, void *val);
  10
  11 =head1 DESCRIPTION
  12
  13 The B<ping_setopt> method sets options that apply to all hosts associated with
  14 the object I<obj> and hosts that are yet to be added to the object.
  15
  16 The I<obj> argument is a pointer to an I<liboping> object, as returned by
  17 L<ping_construct(3)>.
  18
  19 The I<opt> argument specifies the option to set. Use one of the following
  20 constants. You can check if the required constant is supported by the library
  21 at compile time using C<#ifdef>. It is recommended to check for desired
  22 features using the C<OPING_VERSION> define.
  23
  24 =over 4
  25
  26 =item B<PING_OPT_TIMEOUT>
  27
  28 The time to wait for a "echo reply" to be received; in seconds. In this case
  29 the memory pointed to by I<val> is interpreted as a double value and must be
  30 greater than zero. The default is B<PING_DEF_TIMEOUT>.
  31
  32 =item B<PING_OPT_TTL>
  33
  34 The value written into the time-to-live (= TTL) field of generated ICMP
  35 packets. The memory pointed to by I<val> is interpreted as an integer. Valid
  36 values are 1 through 255. Default is B<PING_DEF_TTL>.
  37
  38 =item B<PING_OPT_AF>
  39
  40 The address family to use. The memory pointed to by I<val> is interpreted as an
  41 integer and must be either B<AF_UNSPEC>, B<AF_INET>, or B<AF_INET6>. This
  42 option only affects hosts that are being added B<after> this option has been
  43 set. Default is B<PING_DEF_AF>. If you change this option, and a source address
  44 is set (see B<PING_OPT_SOURCE>) that setting will be reset.
  45
  46 =item B<PING_OPT_DATA>
  47
  48 Set the data to send. The value passed must be a char-pointer to a
  49 null-terminated string. By default a 56 byte long string is used so that the
  50 packet size of an ICMPv4 packet is exactly 64 bytes. That's the behavior of the
  51 L<ping(1)> command.
  52
  53 =item B<PING_OPT_SOURCE>
  54
  55 Set the source address to use. The value passed must be a char-pointer to a
  56 null-terminated string specifying either a numerical network address or
  57 network hostname. This option will ignore the address family setting (as
  58 set with B<PING_OPT_AF>) and will set the object's address family according to
  59 the source address assigned.
  60
  61 =item B<PING_OPT_DEVICE>
  62
  63 Set the outgoing network device to be used. The value passed must be a
  64 char-pointer to a null-terminated string specifying an interface name
  65 (e.E<nbsp>g. C<eth0>). Please note that this might not be supported by all
  66 operating systems. In that case, B<ping_setopt> sets the error to
  67 C<operation not supported>.
  68
  69 =item B<PING_OPT_QOS>
  70
  71 Sets the I<Quality of Service> flags that should be used when crafting ICMP and
  72 ICMPv6 packets. The memory pointed to by I<val> is interpreted as a C<uint8_t>.
  73 The byte is passed to L<setsockopt(2)> without modification, using the
  74 C<IP_TOS> (IPv4) or C<IPV6_TCLASS> (IPv6) option. It is the caller's
  75 responsibility to chose a valid bit combination. For details, read the L<ip(7)>
  76 and L<ipv6(7)> manual pages, as well as I<RFCE<nbsp>2474>.
  77
  78 =back
  79
  80 The I<val> argument is a pointer to the new value. It must not be NULL. It is
  81 dereferenced depending on the value of the I<opt> argument, see above. The
  82 memory pointed to by I<val> is not changed.
  83
  84 =head1 RETURN VALUE
  85
  86 B<ping_setopt> returns zero upon success or less than zero upon failure.
  87
  88 =head1 SEE ALSO
  89
  90 L<ping_construct(3)>,
  91 L<liboping(3)>
  92
  93 =head1 AUTHOR
  94
  95 liboping is written by Florian "octo" Forster E<lt>ff at octo.itE<gt>.
  96 Its homepage can be found at L<http://noping.cc/>.
  97
  98 Copyright (c) 2005-2011 by Florian "octo" Forster.