net/hesiod.3

   1 .\"     $NetBSD: hesiod.3,v 1.1 1999/01/25 03:43:04 lukem Exp $
   2 .\"     $FreeBSD: src/lib/libc/net/hesiod.3,v 1.3 2001/10/01 16:08:55 ru Exp $
   3 .\"
   4 .\" from: #Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp #
   5 .\"
   6 .\" Copyright 1988, 1996 by the Massachusetts Institute of Technology.
   7 .\"
   8 .\" Permission to use, copy, modify, and distribute this
   9 .\" software and its documentation for any purpose and without
  10 .\" fee is hereby granted, provided that the above copyright
  11 .\" notice appear in all copies and that both that copyright
  12 .\" notice and this permission notice appear in supporting
  13 .\" documentation, and that the name of M.I.T. not be used in
  14 .\" advertising or publicity pertaining to distribution of the
  15 .\" software without specific, written prior permission.
  16 .\" M.I.T. makes no representations about the suitability of
  17 .\" this software for any purpose.  It is provided "as is"
  18 .\" without express or implied warranty.
  19 .\"
  20 .Dd November 30, 1996
  21 .Dt HESIOD 3
  22 .Os
  23 .Sh NAME
  24 .Nm hesiod ,
  25 .Nm hesiod_init ,
  26 .Nm hesiod_resolve ,
  27 .Nm hesiod_free_list ,
  28 .Nm hesiod_to_bind ,
  29 .Nm hesiod_end
  30 .Nd Hesiod name server interface library
  31 .Sh LIBRARY
  32 .Lb libc
  33 .Sh SYNOPSIS
  34 .In hesiod.h
  35 .Ft int
  36 .Fn hesiod_init "void **context"
  37 .Ft char **
  38 .Fn hesiod_resolve "void *context" "const char *name" "const char *type"
  39 .Ft void
  40 .Fn hesiod_free_list "void *context" "char **list"
  41 .Ft char *
  42 .Fn hesiod_to_bind "void *context" "const char *name" "const char *type"
  43 .Ft void
  44 .Fn hesiod_end "void *context"
  45 .Sh DESCRIPTION
  46 This family of functions allows you to perform lookups of Hesiod
  47 information, which is stored as text records in the Domain Name
  48 Service.
  49 To perform lookups, you must first initialize a
  50 .Fa context ,
  51 an opaque object which stores information used internally by the
  52 library between calls.
  53 .Fn hesiod_init
  54 initializes a context, storing a pointer to the context in the
  55 location pointed to by the
  56 .Fa context
  57 argument.
  58 .Fn hesiod_end
  59 frees the resources used by a context.
  60 .Pp
  61 .Fn hesiod_resolve
  62 is the primary interface to the library.
  63 If successful, it returns a
  64 list of one or more strings giving the records matching
  65 .Fa name
  66 and
  67 .Fa type .
  68 The last element of the list is followed by a
  69 .Dv NULL
  70 pointer.
  71 It is the
  72 caller's responsibility to call
  73 .Fn hesiod_free_list
  74 to free the resources used by the returned list.
  75 .Pp
  76 .Fn hesiod_to_bind
  77 converts
  78 .Fa name
  79 and
  80 .Fa type
  81 into the DNS name used by
  82 .Fn hesiod_resolve .
  83 It is the caller's responsibility to free the returned string using
  84 .Fn free .
  85 .Sh RETURN VALUES
  86 .Rv -std hesiod_init
  87 On failure,
  88 .Fn hesiod_resolve
  89 and
  90 .Fn hesiod_to_bind
  91 return
  92 .Dv NULL
  93 and set the global variable
  94 .Va errno
  95 to indicate the error.
  96 .Sh ENVIRONMENT
  97 .Bl -tag -width HESIOD_CONFIG
  98 .It Ev HES_DOMAIN
  99 If the environment variable
 100 .Ev HES_DOMAIN
 101 is set, it will override the domain in the Hesiod configuration file.
 102 .It Ev HESIOD_CONFIG
 103 If the environment variable
 104 .Ev HESIOD_CONFIG
 105 is set, it specifies the location of the Hesiod configuration file.
 106 .El
 107 .Sh SEE ALSO
 108 .Xr hesiod.conf 5 ,
 109 .Xr named 8
 110 .Rs
 111 .%T "Hesiod - Project Athena Technical Plan -- Name Service"
 112 .Re
 113 .Sh ERRORS
 114 Hesiod calls may fail because of:
 115 .Bl -tag -width Er
 116 .It Bq Er ENOMEM
 117 Insufficient memory was available to carry out the requested
 118 operation.
 119 .It Bq Er ENOEXEC
 120 .Fn hesiod_init
 121 failed because the Hesiod configuration file was invalid.
 122 .It Bq Er ECONNREFUSED
 123 .Fn hesiod_resolve
 124 failed because no name server could be contacted to answer the query.
 125 .It Bq Er EMSGSIZE
 126 .Fn hesiod_resolve
 127 or
 128 .Fn hesiod_to_bind
 129 failed because the query or response was too big to fit into the
 130 packet buffers.
 131 .It Bq Er ENOENT
 132 .Fn hesiod_resolve
 133 failed because the name server had no text records matching
 134 .Fa name
 135 and
 136 .Fa type ,
 137 or
 138 .Fn hesiod_to_bind
 139 failed because the
 140 .Fa name
 141 argument had a domain extension which could not be resolved with type
 142 .Dq rhs\-extension
 143 in the local Hesiod domain.
 144 .El
 145 .Sh AUTHORS
 146 .An Steve Dyer ,
 147 IBM/Project Athena
 148 .An Greg Hudson ,
 149 MIT Team Athena
 150 .Pp
 151 Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology.
 152 .Sh BUGS
 153 The strings corresponding to the
 154 .Va errno
 155 values set by the Hesiod functions are not particularly indicative of
 156 what went wrong, especially for
 157 .Er ENOEXEC
 158 and
 159 .Er ENOENT .