1.\" $NetBSD: hesiod.3,v 1.5 2002/02/07 07:00:21 ross 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.Dd September 16, 2001 20.Dt HESIOD 3 21.Os 22.Sh NAME 23.Nm hesiod , 24.Nm hesiod_init , 25.Nm hesiod_resolve , 26.Nm hesiod_free_list , 27.Nm hesiod_to_bind , 28.Nm hesiod_end 29.Nd Hesiod name server interface library 30.Sh LIBRARY 31.Lb libc 32.Sh SYNOPSIS 33.Fd #include \*[Lt]hesiod.h\*[Gt] 34.Ft int 35.Fn hesiod_init "void **context" 36.Ft char 37.Fn **hesiod_resolve "void *context" "const char *name" "const char *type" 38.Ft void 39.Fn hesiod_free_list "void *context" "char **list" 40.Ft char 41.Fn *hesiod_to_bind "void *context" "const char *name" "const char *type" 42.Ft void 43.Fn hesiod_end "void *context" 44.Sh DESCRIPTION 45This family of functions allows you to perform lookups of Hesiod 46information, which is stored as text records in the Domain Name 47Service. To perform lookups, you must first initialize a 48.Fa context , 49an opaque object which stores information used internally by the 50library between calls. 51.Fn hesiod_init 52initializes a context, storing a pointer to the context in the 53location pointed to by the 54.Fa context 55argument. 56.Fn hesiod_end 57frees the resources used by a context. 58.Pp 59.Fn hesiod_resolve 60is the primary interface to the library. If successful, it returns a 61list of one or more strings giving the records matching 62.Fa name 63and 64.Fa type . 65The last element of the list is followed by a 66.Dv NULL 67pointer. It is the caller's responsibility to call 68.Fn hesiod_free_list 69to free the resources used by the returned list. 70.Pp 71.Fn hesiod_to_bind 72converts 73.Fa name 74and 75.Fa type 76into the DNS name used by 77.Fn hesiod_resolve . 78It is the caller's responsibility to free the returned string using 79.Xr free 3 . 80.Sh RETURN VALUES 81If successful, 82.Fn hesiod_init 83returns 0; otherwise it returns \-1 and sets 84.Va errno 85to indicate the error. On failure, 86.Fn hesiod_resolve 87and 88.Fn hesiod_to_bind 89return 90.Dv NULL 91and set the global variable 92.Va errno 93to indicate the error. 94.Sh ENVIRONMENT 95If the environment variable 96.Ev HES_DOMAIN 97is set, it will override the domain in the Hesiod configuration file. 98If the environment variable 99.Ev HESIOD_CONFIG 100is set, it specifies the location of the Hesiod configuration file. 101.Sh ERRORS 102Hesiod calls may fail because of: 103.Bl -tag -width ECONNREFUSED -compact 104.It Er ENOMEM 105Insufficient memory was available to carry out the requested operation. 106.It Er ENOEXEC 107.Fn hesiod_init 108failed because the Hesiod configuration file was invalid. 109.It Er ECONNREFUSED 110.Fn hesiod_resolve 111failed because no name server could be contacted to answer the query. 112.It Er EMSGSIZE 113.Fn hesiod_resolve 114or 115.Fn hesiod_to_bind 116failed because the query or response was too big to fit into the 117packet buffers. 118.It Er ENOENT 119.Fn hesiod_resolve 120failed because the name server had no text records matching 121.Fa name 122and 123.Fa type , 124or 125.Fn hesiod_to_bind 126failed because the 127.Fa name 128argument had a domain extension which could not be resolved with type 129.Dq rhs-extension 130in the local Hesiod domain. 131.El 132.Sh SEE ALSO 133.Xr hesiod.conf 5 , 134.Xr named 8 135.Rs 136.%T Hesiod - Project Athena Technical Plan -- Name Service 137.Re 138.Sh AUTHORS 139Steve Dyer, IBM/Project Athena 140.br 141Greg Hudson, MIT Team Athena 142.br 143Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology. 144.Sh BUGS 145The strings corresponding to the 146.Ev errno 147values set by the Hesiod functions are not particularly indicative of 148what went wrong, especially for 149.Er ENOEXEC 150and 151.Er ENOENT . 152