external/bsd/libbind/dist/doc/hesiod.cat3

   1 HESIOD(3)                                                            HESIOD(3)
   2
   3
   4
   5 N\bNA\bAM\bME\bE
   6        hesiod,  hesiod_init, hesiod_resolve, hesiod_free_list, hesiod_to_bind,
   7        hesiod_end - Hesiod name server interface library
   8
   9 S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
  10        #\b#i\bin\bnc\bcl\blu\bud\bde\be <\b<h\bhe\bes\bsi\bio\bod\bd.\b.h\bh>\b>
  11
  12        i\bin\bnt\bt h\bhe\bes\bsi\bio\bod\bd_\b_i\bin\bni\bit\bt(\b(v\bvo\boi\bid\bd *\b**\b*_\bc_\bo_\bn_\bt_\be_\bx_\bt)\b)
  13        c\bch\bha\bar\br *\b**\b*h\bhe\bes\bsi\bio\bod\bd_\b_r\bre\bes\bso\bol\blv\bve\be(\b(v\bvo\boi\bid\bd *\b*_\bc_\bo_\bn_\bt_\be_\bx_\bt,\b, c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*_\bn_\ba_\bm_\be,\b,
  14             c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*_\bt_\by_\bp_\be)\b)
  15        v\bvo\boi\bid\bd h\bhe\bes\bsi\bio\bod\bd_\b_f\bfr\bre\bee\be_\b_l\bli\bis\bst\bt(\b(v\bvo\boi\bid\bd *\b*_\bc_\bo_\bn_\bt_\be_\bx_\bt,\b, c\bch\bha\bar\br *\b**\b*_\bl_\bi_\bs_\bt)\b);\b;
  16        c\bch\bha\bar\br *\b*h\bhe\bes\bsi\bio\bod\bd_\b_t\bto\bo_\b_b\bbi\bin\bnd\bd(\b(v\bvo\boi\bid\bd *\b*_\bc_\bo_\bn_\bt_\be_\bx_\bt,\b, c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*_\bn_\ba_\bm_\be,\b,
  17             c\bco\bon\bns\bst\bt c\bch\bha\bar\br *\b*_\bt_\by_\bp_\be)\b)
  18        v\bvo\boi\bid\bd h\bhe\bes\bsi\bio\bod\bd_\b_e\ben\bnd\bd(\b(v\bvo\boi\bid\bd *\b*_\bc_\bo_\bn_\bt_\be_\bx_\bt)\b)
  19
  20 D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
  21        This family of functions allows you to perform lookups of Hesiod infor‐
  22        mation, which is stored as text records in the Domain Name Service.  To
  23        perform lookups, you must first initialize a _\bc_\bo_\bn_\bt_\be_\bx_\bt, an opaque  object
  24        which  stores information used internally by the library between calls.
  25        _\bh_\be_\bs_\bi_\bo_\bd_\b__\bi_\bn_\bi_\bt initializes a context, storing a pointer to the context  in
  26        the  location pointed to by the _\bc_\bo_\bn_\bt_\be_\bx_\bt argument.  _\bh_\be_\bs_\bi_\bo_\bd_\b__\be_\bn_\bd frees the
  27        resources used by a context.
  28
  29        _\bh_\be_\bs_\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be is the primary interface to the library.  If successful,
  30        it  returns  a  list of one or more strings giving the records matching
  31        _\bn_\ba_\bm_\be and _\bt_\by_\bp_\be.  The last element of the list  is  followed  by  a  NULL
  32        pointer.  It is the caller’s responsibility to call _\bh_\be_\bs_\bi_\bo_\bd_\b__\bf_\br_\be_\be_\b__\bl_\bi_\bs_\bt to
  33        free the resources used by the returned list.
  34
  35        _\bh_\be_\bs_\bi_\bo_\bd_\b__\bt_\bo_\b__\bb_\bi_\bn_\bd converts _\bn_\ba_\bm_\be and _\bt_\by_\bp_\be into the DNS name  used  by  _\bh_\be_\bs_\b‐
  36        _\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be.   It  is  the caller’s responsibility to free the returned
  37        string using _\bf_\br_\be_\be.
  38
  39 R\bRE\bET\bTU\bUR\bRN\bN V\bVA\bAL\bLU\bUE\bES\bS
  40        If successful, _\bh_\be_\bs_\bi_\bo_\bd_\b__\bi_\bn_\bi_\bt returns 0; otherwise it returns -1 and  sets
  41        _\be_\br_\br_\bn_\bo  to  indicate  the  error.   On  failure, _\bh_\be_\bs_\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be and _\bh_\be_\bs_\b‐
  42        _\bi_\bo_\bd_\b__\bt_\bo_\b__\bb_\bi_\bn_\bd return NULL and set the global variable _\be_\br_\br_\bn_\bo  to  indicate
  43        the error.
  44
  45 E\bEN\bNV\bVI\bIR\bRO\bON\bNM\bME\bEN\bNT\bT
  46        If  the  environment  variable  H\bHE\bES\bS_\b_D\bDO\bOM\bMA\bAI\bIN\bN is set, it will override the
  47        domain in the Hesiod configuration file.  If the  environment  variable
  48        H\bHE\bES\bSI\bIO\bOD\bD_\b_C\bCO\bON\bNF\bFI\bIG\bG  is set, it specifies the location of the Hesiod configu‐
  49        ration file.
  50
  51 S\bSE\bEE\bE A\bAL\bLS\bSO\bO
  52        ‘Hesiod - Project Athena Technical Plan -- Name Service’
  53
  54 E\bER\bRR\bRO\bOR\bRS\bS
  55        Hesiod calls may fail because of:
  56
  57        ENOMEM Insufficient memory was available to  carry  out  the  requested
  58               operation.
  59
  60        ENOEXEC
  61               _\bh_\be_\bs_\bi_\bo_\bd_\b__\bi_\bn_\bi_\bt  failed  because  the  Hesiod configuration file was
  62               invalid.
  63
  64        ECONNREFUSED
  65               _\bh_\be_\bs_\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be failed because no name server could be  contacted
  66               to answer the query.
  67
  68        EMSGSIZE
  69               _\bh_\be_\bs_\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be  failed because the query or response was too big
  70               to fit into the packet buffers.
  71
  72        ENOENT _\bh_\be_\bs_\bi_\bo_\bd_\b__\br_\be_\bs_\bo_\bl_\bv_\be failed  because  the  name  server  had  no  text
  73               records matching _\bn_\ba_\bm_\be and _\bt_\by_\bp_\be, or _\bh_\be_\bs_\bi_\bo_\bd_\b__\bt_\bo_\b__\bb_\bi_\bn_\bd failed because
  74               the _\bn_\ba_\bm_\be argument had a domain  extension  which  could  not  be
  75               resolved with type ‘‘rhs-extension’’ in the local Hesiod domain.
  76
  77 A\bAU\bUT\bTH\bHO\bOR\bR
  78        Steve Dyer, IBM/Project Athena
  79        Greg Hudson, MIT Team Athena
  80        Copyright 1987, 1988, 1995, 1996  by  the  Massachusetts  Institute  of
  81        Technology.
  82
  83 B\bBU\bUG\bGS\bS
  84        The  strings  corresponding to the _\be_\br_\br_\bn_\bo values set by the Hesiod func‐
  85        tions are not particularly indicative of what  went  wrong,  especially
  86        for _\bE_\bN_\bO_\bE_\bX_\bE_\bC and _\bE_\bN_\bO_\bE_\bN_\bT.
  87
  88
  89
  90                                30 November 1996                      HESIOD(3)