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