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