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.Dd June 27, 2022 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.In hesiod.h 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. 48To perform lookups, you must first initialize a 49.Fa context , 50an opaque object which stores information used internally by the 51library between calls. 52The 53.Fn hesiod_init 54function 55initializes a context, storing a pointer to the context in the 56location pointed to by the 57.Fa context 58argument. 59The 60.Fn hesiod_end 61function 62frees the resources used by a context. 63.Pp 64The 65.Fn hesiod_resolve 66function 67is the primary interface to the library. 68If successful, it returns a 69list of one or more strings giving the records matching 70.Fa name 71and 72.Fa type . 73The last element of the list is followed by a 74.Dv NULL 75pointer. 76It is the 77caller's responsibility to call 78.Fn hesiod_free_list 79to free the resources used by the returned list. 80.Pp 81The 82.Fn hesiod_to_bind 83function 84converts 85.Fa name 86and 87.Fa type 88into the DNS name used by 89.Fn hesiod_resolve . 90It is the caller's responsibility to free the returned string using 91.Fn free . 92.Sh RETURN VALUES 93.Rv -std hesiod_init 94On failure, 95.Fn hesiod_resolve 96and 97.Fn hesiod_to_bind 98return 99.Dv NULL 100and set the global variable 101.Va errno 102to indicate the error. 103.Sh ENVIRONMENT 104.Bl -tag -width HESIOD_CONFIG 105.It Ev HES_DOMAIN 106If the environment variable 107.Ev HES_DOMAIN 108is set, it will override the domain in the Hesiod configuration file. 109.It Ev HESIOD_CONFIG 110If the environment variable 111.Ev HESIOD_CONFIG 112is set, it specifies the location of the Hesiod configuration file. 113.El 114.Sh ERRORS 115Hesiod calls may fail because of: 116.Bl -tag -width Er 117.It Bq Er ENOMEM 118Insufficient memory was available to carry out the requested 119operation. 120.It Bq Er ENOEXEC 121The 122.Fn hesiod_init 123function 124failed because the Hesiod configuration file was invalid. 125.It Bq Er ECONNREFUSED 126The 127.Fn hesiod_resolve 128function 129failed because no name server could be contacted to answer the query. 130.It Bq Er EMSGSIZE 131The 132.Fn hesiod_resolve 133or 134.Fn hesiod_to_bind 135function 136failed because the query or response was too big to fit into the 137packet buffers. 138.It Bq Er ENOENT 139The 140.Fn hesiod_resolve 141function 142failed because the name server had no text records matching 143.Fa name 144and 145.Fa type , 146or 147.Fn hesiod_to_bind 148failed because the 149.Fa name 150argument had a domain extension which could not be resolved with type 151.Dq rhs\-extension 152in the local Hesiod domain. 153.El 154.Sh SEE ALSO 155.Xr hesiod.conf 5 156.Rs 157.%T "Hesiod - Project Athena Technical Plan -- Name Service" 158.Re 159.Sh AUTHORS 160.An Steve Dyer , 161IBM/Project Athena 162.An Greg Hudson , 163MIT Team Athena 164.Pp 165Copyright 1987, 1988, 1995, 1996 by the Massachusetts Institute of Technology. 166.Sh BUGS 167The strings corresponding to the 168.Va errno 169values set by the Hesiod functions are not particularly indicative of 170what went wrong, especially for 171.Er ENOEXEC 172and 173.Er ENOENT . 174