hesiod/hesiod.3

   1 .\" $Id: hesiod.3,v 1.9.2.1 1997/01/03 21:02:23 ghudson Exp $
   2 .\"
   3 .\" Copyright 1988, 1996 by the Massachusetts Institute of Technology.
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this
   6 .\" software and its documentation for any purpose and without
   7 .\" fee is hereby granted, provided that the above copyright
   8 .\" notice appear in all copies and that both that copyright
   9 .\" notice and this permission notice appear in supporting
  10 .\" documentation, and that the name of M.I.T. not be used in
  11 .\" advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\" M.I.T. makes no representations about the suitability of
  14 .\" this software for any purpose.  It is provided "as is"
  15 .\" without express or implied warranty.
  16 .\"
  17 .TH HESIOD 3 "30 November 1996"
  18 .SH NAME
  19 hesiod, hesiod_init, hesiod_resolve, hesiod_free_list, hesiod_to_bind, hesiod_end \- Hesiod name server interface library
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <hesiod.h>
  23 .PP
  24 .B int hesiod_init(void **\fIcontext\fP)
  25 .B char **hesiod_resolve(void *\fIcontext\fP, const char *\fIname\fP,
  26 .B      const char *\fItype\fP)
  27 .B void hesiod_free_list(void *\fIcontext\fP, char **\fIlist\fP);
  28 .B char *hesiod_to_bind(void *\fIcontext\fP, const char *\fIname\fP,
  29 .B      const char *\fItype\fP)
  30 .B void hesiod_end(void *\fIcontext\fP)
  31 .PP
  32 .B cc file.c \-lhesiod
  33 .fi
  34 .SH DESCRIPTION
  35 This family of functions allows you to perform lookups of Hesiod
  36 information, which is stored as text records in the Domain Name
  37 Service.  To perform lookups, you must first initialize a
  38 .IR context ,
  39 an opaque object which stores information used internally by the
  40 library between calls.
  41 .I hesiod_init
  42 initializes a context, storing a pointer to the context in the
  43 location pointed to by the
  44 .I context
  45 argument.
  46 .I hesiod_end
  47 frees the resources used by a context.
  48 .PP
  49 .I hesiod_resolve
  50 is the primary interface to the library.  If successful, it returns a
  51 list of one or more strings giving the records matching
  52 .I name
  53 and
  54 .IR type .
  55 The last element of the list is followed by a NULL pointer.  It is the
  56 caller's responsibility to call
  57 .I hesiod_free_list
  58 to free the resources used by the returned list.
  59 .PP
  60 .I hesiod_to_bind
  61 converts
  62 .I name
  63 and
  64 .I type
  65 into the DNS name used by
  66 .IR hesiod_resolve .
  67 It is the caller's responsibility to free the returned string using
  68 .IR free .
  69 .SH RETURN VALUES
  70 If successful,
  71 .I hesiod_init
  72 returns 0; otherwise it returns \-1 and sets
  73 .I errno
  74 to indicate the error.  On failure,
  75 .I hesiod_resolve
  76 and
  77 .I hesiod_to_bind
  78 return NULL and set the global variable
  79 .I errno
  80 to indicate the error.
  81 .SH ENVIRONMENT
  82 If the environment variable
  83 .B HES_DOMAIN
  84 is set, it will override the domain in the Hesiod configuration file.
  85 If the environment variable
  86 .B HESIOD_CONFIG
  87 is set, it specifies the location of the Hesiod configuration file.
  88 .SH SEE ALSO
  89 `Hesiod - Project Athena Technical Plan -- Name Service', named(8),
  90 hesiod.conf(5)
  91 .SH ERRORS
  92 Hesiod calls may fail because of:
  93 .IP ENOMEM
  94 Insufficient memory was available to carry out the requested
  95 operation.
  96 .IP ENOEXEC
  97 .I hesiod_init
  98 failed because the Hesiod configuration file was invalid.
  99 .IP ECONNREFUSED
 100 .I hesiod_resolve
 101 failed because no name server could be contacted to answer the query.
 102 .IP EMSGSIZE
 103 .I hesiod_resolve
 104 or
 105 .I hesiod_to_bind
 106 failed because the query or response was too big to fit into the
 107 packet buffers.
 108 .IP ENOENT
 109 .I hesiod_resolve
 110 failed because the name server had no text records matching
 111 .I name
 112 and
 113 .IR type ,
 114 or
 115 .I hesiod_to_bind
 116 failed because the
 117 .I name
 118 argument had a domain extension which could not be resolved with type
 119 ``rhs-extension'' in the local Hesiod domain.
 120 .SH AUTHOR
 121 Steve Dyer, IBM/Project Athena
 122 .br
 123 Greg Hudson, MIT Team Athena
 124 .br
 125 Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology.
 126 .SH BUGS
 127 The strings corresponding to the
 128 .I errno
 129 values set by the Hesiod functions are not particularly indicative of
 130 what went wrong, especially for
 131 .I ENOEXEC
 132 and
 133 .IR ENOENT .