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 SEE ALSO 117.Xr hesiod.conf 5 , 118.Xr named 8 119.Rs 120.%T "Hesiod - Project Athena Technical Plan -- Name Service" 121.Re 122.Sh ERRORS 123Hesiod calls may fail because of: 124.Bl -tag -width Er 125.It Bq Er ENOMEM 126Insufficient memory was available to carry out the requested 127operation. 128.It Bq Er ENOEXEC 129The 130.Fn hesiod_init 131function 132failed because the Hesiod configuration file was invalid. 133.It Bq Er ECONNREFUSED 134The 135.Fn hesiod_resolve 136function 137failed because no name server could be contacted to answer the query. 138.It Bq Er EMSGSIZE 139The 140.Fn hesiod_resolve 141or 142.Fn hesiod_to_bind 143function 144failed because the query or response was too big to fit into the 145packet buffers. 146.It Bq Er ENOENT 147The 148.Fn hesiod_resolve 149function 150failed because the name server had no text records matching 151.Fa name 152and 153.Fa type , 154or 155.Fn hesiod_to_bind 156failed because the 157.Fa name 158argument had a domain extension which could not be resolved with type 159.Dq rhs\-extension 160in the local Hesiod domain. 161.El 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