X-Git-Url: https://git.subgeniuskitty.com/unix-history/.git/blobdiff_plain/c470f385eb1d313cf29e748f56e8e108ebf0b2c1..82c7553640540b8e49368d0d594636c257b57d3c:/usr/src/lib/libc/net/resolver.3 diff --git a/usr/src/lib/libc/net/resolver.3 b/usr/src/lib/libc/net/resolver.3 index 2e273e6811..397cd26c8f 100644 --- a/usr/src/lib/libc/net/resolver.3 +++ b/usr/src/lib/libc/net/resolver.3 @@ -1,203 +1,297 @@ -.\" Copyright (c) 1985 Regents of the University of California. -.\" All rights reserved. The Berkeley software License Agreement -.\" specifies the terms and conditions for redistribution. +.\" Copyright (c) 1985, 1991 The Regents of the University of California. +.\" All rights reserved. .\" -.\" @(#)resolver.3 1.8 (Berkeley) %G% +.\" %sccs.include.redist.roff% .\" -.TH RESOLVER 3 "" -.UC 4 -.SH NAME -res_mkquery, res_send, res_init, dn_comp, dn_expand \- resolver routines -.SH SYNOPSIS -.B #include -.br -.B #include -.br -.B #include -.br -.B #include -.PP -.B "res_mkquery(op, dname, class, type, data, datalen, newrr, buf, buflen)" -.br -.B int op; -.br -.B char *dname; -.br -.B int class, type; -.br -.B char *data; -.br -.B int datalen; -.br -.B struct rrec *newrr; -.br -.B char *buf; -.br -.B int buflen; -.PP -.B res_send(msg, msglen, answer, anslen) -.br -.B char *msg; -.br -.B int msglen; -.br -.B char *answer; -.br -.B int anslen; -.PP -.B res_init() -.PP -.B dn_comp(exp_dn, comp_dn, length, dnptrs, lastdnptr) -.br -.B char *exp_dn, *comp_dn; -.br -.B int length; -.br -.B char **dnptrs, **lastdnptr; -.PP -.B dn_expand(msg, eomorig, comp_dn, exp_dn, length) -.br -.B char *msg, *eomorig, *comp_dn, exp_dn; -.br -.B int length; -.SH DESCRIPTION -These routines are used for making, sending and interpreting packets -for use with Internet domain name servers. -Global information that is used by the -resolver routines is kept in the variable -.IR _res . +.\" @(#)resolver.3 6.9 (Berkeley) %G% +.\" +.Dd +.Dt RESOLVER 3 +.Os BSD 4.3 +.Sh NAME +.Nm res_query , +.Nm res_search , +.Nm res_mkquery , +.Nm res_send , +.Nm res_init , +.Nm dn_comp , +.Nm dn_expand +.Nd resolver routines +.Sh SYNOPSIS +.Fd #include +.Fd #include +.Fd #include +.Fd #include +.Fo res_query +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "u_char *answer" +.Fa "int anslen" +.Fc +.Fo res_search +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "u_char *answer" +.Fa "int anslen" +.Fc +.Fo res_mkquery +.Fa "int op" +.Fa "char *dname" +.Fa "int class" +.Fa "int type" +.Fa "char *data" +.Fa "int datalen" +.Fa "struct rrec *newrr" +.Fa "char *buf" +.Fa "int buflen" +.Fc +.Fo res_send +.Fa "char *msg" +.Fa "int msglen" +.Fa "char *answer" +.Fa "int anslen" +.Fc +.Fn res_init +.Fo dn_comp +.Fa "char *exp_dn" +.Fa "char *comp_dn" +.Fa "int length" +.Fa "char **dnptrs" +.Fa "char **lastdnptr" +.Fc +.Fo dn_expand +.Fa "u_char *msg" +.Fa "u_char *eomorig" +.Fa "u_char *comp_dn" +.Fa "u_char *exp_dn" +.Fa "int length" +.Fc +.Sh DESCRIPTION +These routines are used for making, sending and interpreting +query and reply messages with Internet domain name servers. +.Pp +Global configuration and state information that is used by the +resolver routines is kept in the structure +.Em _res . Most of the values have reasonable defaults and can be ignored. Options stored in -.I _res.options +.Em _res.options are defined in -.I resolv.h +.Pa resolv.h and are as follows. -Options are stored a simple bit mask containing the bitwise ``or'' +Options are stored as a simple bit mask containing the bitwise ``or'' of the options enabled. -.IP RES_INIT +.Bl -tag -width RES_DEFNAMES +.It Dv RES_INIT True if the initial name server address and default domain name are initialized (i.e., -.I res_init +.Fn res_init has been called). -.IP RES_DEBUG +.It Dv RES_DEBUG Print debugging messages. -.IP RES_AAONLY +.It Dv RES_AAONLY Accept authoritative answers only. With this option, -.I res_send +.Fn res_send should continue until it finds an authoritative answer or finds an error. Currently this is not implemented. -.IP RES_USEVC -Use TCP connections for queries instead of UDP datagrams. -.IP RES_STAYOPEN -Used with RES_USEVC to keep the TCP connection open between +.It Dv RES_USEVC +Use +.Tn TCP +connections for queries instead of +.Tn UDP +datagrams. +.It Dv RES_STAYOPEN +Used with +.Dv RES_USEVC +to keep the +.Tn TCP +connection open between queries. This is useful only in programs that regularly do many queries. -UDP should be the normal mode used. -.IP RES_IGNTC -Unused currently (ignore truncation errors, i.e., don't retry with TCP). -.IP RES_RECURSE +.Tn UDP +should be the normal mode used. +.It Dv RES_IGNTC +Unused currently (ignore truncation errors, i.e., don't retry with +.Tn TCP ) . +.It Dv RES_RECURSE Set the recursion-desired bit in queries. This is the default. -( -.I res_send +.Pf ( Fn res_send does not do iterative queries and expects the name server to handle recursion.) -.IP RES_DEFNAMES +.It Dv RES_DEFNAMES If set, -.I res_mkquery +.Fn res_search will append the default domain name to single-component names (those that do not contain a dot). -This is the default. -.IP RES_DNSRCH +This option is enabled by default. +.It Dv RES_DNSRCH If this option is set, -the standard host lookup routine -.IR gethostbyname (3) +.Fn res_search will search for host names in the current domain and in parent domains; see -.IR hostname (7). -.PP -.I Res_init -.PP -reads the initialization file to get the default -domain name and the Internet address of the initial hosts -running the name server. -If this line does not exist, the host running +.Xr hostname 7 . +This is used by the standard host lookup routine +.Xr gethostbyname 3 . +This option is enabled by default. +.El +.Pp +The +.Fn res_init +routine +reads the configuration file (if any; see +.Xr resolver 5 ) +to get the default domain name, +search list and +the Internet address of the local name server(s). +If no server is configured, the host running the resolver is tried. -.I Res_mkquery -makes a standard query message and places it in -.IR buf . -.I Res_mkquery -will return the size of the query or \-1 if the query is -larger than -.IR buflen . -.I Op -is usually QUERY but can be any of the query types defined in -.IR nameser.h . -.I Dname -is the domain name. -If -.I dname -consists of a single label and the RES_DEFNAMES flag is enabled -(the default), the current domain name will be appended to -.IR dname . The current domain name is defined by the hostname -or is specified in a system file; it can be overridden -by the environment variable LOCALDOMAIN. -.I Newrr +if not specified in the configuration file; +it can be overridden by the environment variable +.Ev LOCALDOMAIN . +Initialization normally occurs on the first call +to one of the following routines. +.Pp +The +.Fn res_query +function provides an interface to the server query mechanism. +It constructs a query, sends it to the local server, +awaits a response, and makes preliminary checks on the reply. +The query requests information of the specified +.Fa type +and +.Fa class +for the specified fully-qualified domain name +.Fa dname . +The reply message is left in the +.Fa answer +buffer with length +.Fa anslen +supplied by the caller. +.Pp +The +.Fn res_search +routine makes a query and awaits a response like +.Fn res_query , +but in addition, it implements the default and search rules +controlled by the +.Dv RES_DEFNAMES +and +.Dv RES_DNSRCH +options. +It returns the first successful reply. +.Pp +The remaining routines are lower-level routines used by +.Fn res_query . +The +.Fn res_mkquery +function +constructs a standard query message and places it in +.Fa buf . +It returns the size of the query, or \-1 if the query is +larger than +.Fa buflen . +The query type +.Fa op +is usually +.Dv QUERY , +but can be any of the query types defined in +.Aq Pa arpa/nameser.h . +The domain name for the query is given by +.Fa dname . +.Fa Newrr is currently unused but is intended for making update messages. -.PP -.I Res_send -sends a query to name servers and returns an answer. +.Pp +The +.Fn res_send +routine +sends a pre-formatted query and returns an answer. It will call -.I res_init -if RES_INIT is not set, send the query to the local name server, and +.Fn res_init +if +.Dv RES_INIT +is not set, send the query to the local name server, and handle timeouts and retries. -The length of the message is returned, or +The length of the reply message is returned, or \-1 if there were errors. -.PP -.I Dn_expand -expands the compressed domain name -.I comp_dn -to a full domain name. Expanded names are converted to upper case. -.I Msg -is a pointer to the beginning of the message, -.I exp_dn -is a pointer to a buffer of size -.I length -for the result. -The size of compressed name is returned or -1 if there was an error. -.PP -.I Dn_comp +.Pp +The +.Fn dn_comp +function compresses the domain name -.I exp_dn +.Fa exp_dn and stores it in -.IR comp_dn . -The size of the compressed name is returned or -1 if there were errors. -.I length is the size of the array pointed to by -.IR comp_dn . -.I Dnptrs -is a list of pointers to previously compressed names in the current message. +.Fa comp_dn . +The size of the compressed name is returned or \-1 if there were errors. +The size of the array pointed to by +.Fa comp_dn +is given by +.Fa length . +The compression uses +an array of pointers +.Fa dnptrs +to previously-compressed names in the current message. The first pointer points to -to the beginning of the message and the list ends with NULL. -.I lastdnptr -is a pointer to the end of the array pointed to -.IR dnptrs . -A side effect is to update the list of pointers for -labels inserted into the message by -.I dn_comp +to the beginning of the message and the list ends with +.Dv NULL . +The limit to the array is specified by +.Fa lastdnptr . +A side effect of +.Fn dn_comp +is to update the list of pointers for +labels inserted into the message as the name is compressed. If -.I dnptr -is NULL, names are not compressed. +.Em dnptr +is +.Dv NULL, names are not compressed. If -.I lastdnptr -is NULL, the list of labels is not updated. -.SH FILES -/etc/resolv.conf see resolver(5) -.SH "SEE ALSO" -gethostbyname(3), named(8), resolver(5), hostname(7), -.br -RFC882, RFC883, RFC973, RFC974, -.br -SMM:11 Name Server Operations Guide for BIND +.Fa lastdnptr +is +.Dv NULL , +the list of labels is not updated. +.Pp +The +.Fn dn_expand +entry +expands the compressed domain name +.Fa comp_dn +to a full domain name +The compressed name is contained in a query or reply message; +.Fa msg +is a pointer to the beginning of the message. +The uncompressed name is placed in the buffer indicated by +.Fa exp_dn +which is of size +.Fa length . +The size of compressed name is returned or \-1 if there was an error. +.Sh FILES +.Bl -tag -width Pa +/etc/resolv.conf +The configuration file +see +.Xr resolver 5 . +.El +.Sh SEE ALSO +.Xr gethostbyname 3 , +.Xr named 8 , +.Xr resolver 5 , +.Xr hostname 7 , +.Pp +.%T RFC1032 , +.%T RFC1033 , +.%T RFC1034 , +.%T RFC1035 , +.%T RFC974 +.Rs +.%T "Name Server Operations Guide for BIND" +.Re +.Sh HISTORY +The +.Nm +function appeared in +.Bx 4.3 .