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 effect 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 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 effects 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. This option will ignore the address family setting (as
  57 set with B<PING_OPT_AF>) and will set the object's address family according to
  58 the source address assigned.
  59
  60 =back
  61
  62 The I<val> argument is a pointer to the new value. It must not be NULL. It is
  63 dereferenced depending on the value of the I<opt> argument, see above. The
  64 memory pointed to by I<val> is not changed.
  65
  66 =head1 RETURN VALUE
  67
  68 B<ping_setopt> returns zero upon success or less than zero upon failure.
  69
  70 =head1 SEE ALSO
  71
  72 L<ping_construct(3)>,
  73 L<liboping(3)>
  74
  75 =head1 AUTHOR
  76
  77 liboping is written by Florian octo Forster E<lt>octo at verplant.orgE<gt>.
  78 It's homepage can be found at L<http://verplant.org/liboping/>.
  79
  80 (c) 2005-2009 by Florian octo Forster.