ares_save_options.3

   1 .\"
   2 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   3 .\"
   4 .\" Permission to use, copy, modify, and distribute this
   5 .\" software and its documentation for any purpose and without
   6 .\" fee is hereby granted, provided that the above copyright
   7 .\" notice appear in all copies and that both that copyright
   8 .\" notice and this permission notice appear in supporting
   9 .\" documentation, and that the name of M.I.T. not be used in
  10 .\" advertising or publicity pertaining to distribution of the
  11 .\" software without specific, written prior permission.
  12 .\" M.I.T. makes no representations about the suitability of
  13 .\" this software for any purpose.  It is provided "as is"
  14 .\" without express or implied warranty.
  15 .\"
  16 .TH ARES_SAVE_OPTIONS 3 "5 March 2010"
  17 .SH NAME
  18 ares_save_options \- Save configuration values obtained from initialized ares_channel
  19 .SH SYNOPSIS
  20 .nf
  21 .B #include <ares.h>
  22 .PP
  23 .B int ares_save_options(ares_channel \fIchannel\fP, struct ares_options *\fIoptions\fP, int *\fIoptmask\fP)
  24 .fi
  25 .SH DESCRIPTION
  26 The \fBares_save_options(3)\fP function saves the channel data identified by
  27 .IR channel ,
  28 into the options struct identified by
  29 .IR options ,
  30 and saves the mask of options which are set to the integer
  31 pointer (passed by reference) identified by
  32 .IR optmask .
  33
  34 The resultant options and optmask are then able to be
  35 passed directly to ares_init_options.  When the options
  36 are no longer needed, ares_destroy_options should be called
  37 to free any associated memory.
  38 .SH RETURN VALUES
  39 .B ares_save_options(3)
  40 can return any of the following values:
  41 .TP 15
  42 .B ARES_SUCCESS
  43 The channel data was successfuly stored
  44 .TP 15
  45 .B ARES_ENOMEM
  46 The memory was exhausted
  47 .TP 15
  48 .B ARES_ENODATA
  49 The channel data identified by
  50 .IR channel
  51 were invalid.
  52 .SH NOTE
  53 Since c-ares 1.6.0 the ares_options struct has been "locked" meaning that it
  54 won't be extended to cover new functions. This function will remain
  55 functioning, but it can only return config data that can be represented in
  56 this config struct, which may no longer be the complete set of config
  57 options. \fBares_dup(3)\fP will not have that restriction.
  58
  59 The ares_options struct can not handle potential IPv6 name servers the
  60 ares_channel might be configured to use. The \fBares_save_options(3)\fP function
  61 will only return IPv4 servers, if any. In order to retrieve all name servers
  62 an ares_channel might be using, the \fBares_get_servers(3)\fP function must be
  63 used instead.
  64 .SH SEE ALSO
  65 .BR ares_destroy_options (3),
  66 .BR ares_init_options (3),
  67 .BR ares_get_servers (3),
  68 .BR ares_dup (3)
  69 .SH AVAILABILITY
  70 ares_save_options(3) was added in c-ares 1.4.0
  71 .SH AUTHOR
  72 Brad House
  73 .br
  74 Copyright 1998 by the Massachusetts Institute of Technology.