[BACK]Return to ypclnt.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / yp

Annotation of src/lib/libc/yp/ypclnt.3, Revision 1.23

1.23    ! martin      1: .\"    $NetBSD: ypclnt.3,v 1.22 2003/05/10 12:14:27 wiz Exp $
1.1       deraadt     2: .\"
1.5       thorpej     3: .\" Copyright (c) 1996 The NetBSD Foundation, Inc.
1.1       deraadt     4: .\" All rights reserved.
                      5: .\"
1.5       thorpej     6: .\" This code is derived from software contributed to The NetBSD Foundation
                      7: .\" by Jason R. Thorpe.
                      8: .\"
1.1       deraadt     9: .\" Redistribution and use in source and binary forms, with or without
                     10: .\" modification, are permitted provided that the following conditions
                     11: .\" are met:
                     12: .\" 1. Redistributions of source code must retain the above copyright
                     13: .\"    notice, this list of conditions and the following disclaimer.
                     14: .\" 2. Redistributions in binary form must reproduce the above copyright
                     15: .\"    notice, this list of conditions and the following disclaimer in the
                     16: .\"    documentation and/or other materials provided with the distribution.
                     17: .\"
1.5       thorpej    18: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
                     19: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
                     20: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
1.10      jtc        21: .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
1.9       jtc        22: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
1.5       thorpej    23: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
                     24: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
                     25: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
                     26: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
                     27: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
                     28: .\" POSSIBILITY OF SUCH DAMAGE.
1.1       deraadt    29: .\"
1.6       lukem      30: .Dd May 21, 1997
1.1       deraadt    31: .Dt YPCLNT 3
                     32: .Os
                     33: .Sh NAME
                     34: .Nm yp_all ,
                     35: .Nm yp_bind ,
                     36: .Nm yp_first ,
                     37: .Nm yp_get_default_domain ,
                     38: .Nm yp_master ,
                     39: .Nm yp_match ,
                     40: .Nm yp_next ,
                     41: .Nm yp_order ,
                     42: .Nm yp_unbind ,
                     43: .Nm yperr_string ,
                     44: .Nm ypprot_err
                     45: .Nd Interface to the YP subsystem
1.12      perry      46: .Sh LIBRARY
                     47: .Lb libc
1.1       deraadt    48: .Sh SYNOPSIS
1.21      wiz        49: .In sys/types.h
                     50: .In rpc/rpc.h
                     51: .In rpcsvc/ypclnt.h
                     52: .In rpcsvc/yp_prot.h
1.1       deraadt    53: .Ft int
1.6       lukem      54: .Fn yp_all "const char *indomain" "const char *inmap" "struct ypall_callback *incallback"
1.1       deraadt    55: .Ft int
1.6       lukem      56: .Fn yp_bind "const char *dom"
1.1       deraadt    57: .Ft int
1.6       lukem      58: .Fn yp_first "const char *indomain" "const char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
1.1       deraadt    59: .Ft int
1.8       lukem      60: .Fn yp_get_default_domain "char **outdomain"
1.1       deraadt    61: .Ft int
1.6       lukem      62: .Fn yp_master "const char *indomain" "const char *inmap" "char **outname"
1.1       deraadt    63: .Ft int
1.6       lukem      64: .Fn yp_match "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"
1.1       deraadt    65: .Ft int
1.6       lukem      66: .Fn yp_next "const char *indomain" "const char *inmap" "const char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"
1.1       deraadt    67: .Ft int
1.6       lukem      68: .Fn yp_order "const char *indomain" "const char *inmap" "int *outorder"
1.1       deraadt    69: .Ft void
1.6       lukem      70: .Fn yp_unbind "const char *dom"
1.1       deraadt    71: .Ft char *
                     72: .Fn yperr_string "int incode"
                     73: .Ft int
                     74: .Fn ypprot_err "unsigned int incode"
                     75: .Sh DESCRIPTION
                     76: The
                     77: .Nm ypclnt
1.11      lukem      78: suite provides an interface to the
                     79: .Tn YP
1.20      wiz        80: subsystem.
                     81: For a general description of the
1.11      lukem      82: .Tn YP
                     83: subsystem, see
1.1       deraadt    84: .Xr yp 8 .
                     85: .Pp
                     86: For all functions, input values begin with
                     87: .Pa in
                     88: and output values begin with
                     89: .Pa out .
1.6       lukem      90: .Pp
1.4       thorpej    91: Any output values of type
1.1       deraadt    92: .Em char **
1.6       lukem      93: should be the addresses of uninitialized character pointers.
                     94: These values will be reset to the null pointer (unless the address
                     95: itself is the null pointer, in which case the error
                     96: .Er YPERR_BADARGS
                     97: will be returned).
                     98: If necessary,
1.11      lukem      99: memory will be allocated by the
                    100: .Tn YP
                    101: client routines using
1.6       lukem     102: .Fn malloc ,
                    103: and the result will be stored in the appropriate output value.
1.11      lukem     104: If the invocation of a
                    105: .Tn YP
                    106: client routine doesn't return an error,
1.7       lukem     107: and an output value is not the null pointer, then this memory
                    108: should be freed by the user when there is no additional need for
                    109: the data stored there.
1.6       lukem     110: For
1.1       deraadt   111: .Pa outkey
                    112: and
                    113: .Pa outval ,
                    114: two extra bytes of memory are allocated for a
                    115: .Ql \en
                    116: and
                    117: .Ql \e0 ,
                    118: which are not
                    119: reflected in the values of
                    120: .Pa outkeylen
                    121: or
                    122: .Pa outvallen .
1.6       lukem     123: .Pp
1.1       deraadt   124: All occurrences of
                    125: .Pa indomain
                    126: and
                    127: .Pa inmap
1.20      wiz       128: must be non-null, NUL-terminated strings.
                    129: All input strings which also have
1.6       lukem     130: a corresponding length parameter cannot be the null pointer unless the
1.20      wiz       131: corresponding length value is zero.
                    132: Such strings need not be NUL-terminated.
1.1       deraadt   133: .Pp
1.11      lukem     134: All
                    135: .Tn YP
                    136: lookup calls (the functions
1.1       deraadt   137: .Fn yp_all ,
                    138: .Fn yp_first ,
                    139: .Fn yp_master ,
                    140: .Fn yp_match ,
                    141: .Fn yp_next ,
                    142: .Fn yp_order )
1.11      lukem     143: require a
                    144: .Tn YP
                    145: domain name and a
                    146: .Tn YP
1.20      wiz       147: map name.
                    148: The default domain name may be obtained by calling
1.1       deraadt   149: .Fn yp_get_default_domain ,
1.11      lukem     150: and should thus be used before all other
                    151: .Tn YP
                    152: calls in a client program.
1.1       deraadt   153: The value it places
                    154: .Pa outdomain
                    155: is suitable for use as the
                    156: .Pa indomain
1.11      lukem     157: parameter to all subsequent
                    158: .Tn YP
                    159: calls.
                    160: .Pp
                    161: In order for
                    162: .Tn YP
                    163: lookup calls to succeed, the client process must be bound
                    164: to a
                    165: .Tn YP
1.20      wiz       166: server process.
                    167: The client process need not explicitly bind to
1.1       deraadt   168: the server, as it happens automatically whenever a lookup occurs.
                    169: The function
                    170: .Fn yp_bind
1.11      lukem     171: is provided for a backup strategy, e.g. a local file, when a
                    172: .Tn YP
1.20      wiz       173: server process is not available.
                    174: Each binding uses one socket descriptor on the client
1.1       deraadt   175: process, which may be explicitly freed using
                    176: .Fn yp_unbind ,
                    177: which frees all per-process and per-node resources to bind the domain and
                    178: marks the domain unbound.
                    179: .Pp
1.11      lukem     180: If, during a
                    181: .Tn YP
                    182: lookup, an RPC failure occurs, the domain used in the lookup
1.1       deraadt   183: is automatically marked unbound and the
                    184: .Nm ypclnt
                    185: layer retries the lookup as long as
                    186: .Xr ypbind 8
                    187: is running and either the client process cannot bind to a server for the domain
1.11      lukem     188: specified in the lookup, or RPC requests to the
                    189: .Tn YP
                    190: server process fail.
                    191: If an error is not RPC-related, one of the
                    192: .Tn YP
                    193: error codes described below
1.1       deraadt   194: is returned and control given back to the user code.
                    195: .Pp
                    196: The
                    197: .Nm ypclnt
                    198: suite provides the following functionality:
1.17      ross      199: .Bl -tag -width yp_match()xx
1.1       deraadt   200: .It Fn yp_match
                    201: Provides the value associated with the given key.
                    202: .It Fn yp_first
                    203: Provides the first key-value pair from the given map in the named domain.
                    204: .It Fn yp_next
1.20      wiz       205: Provides the next key-value pair in the given map.
                    206: To obtain the second pair,
1.1       deraadt   207: the
                    208: .Pa inkey
                    209: value should be the
                    210: .Pa outkey
                    211: value provided by the initial call to
                    212: .Fn yp_first .
                    213: In the general case, the next key-value pair may be obtained by using the
                    214: .Pa outkey
                    215: value from the previous call to
                    216: .Fn yp_next
                    217: as the value for
                    218: .Pa inkey .
                    219: .Pp
1.6       lukem     220: Of course, the notions of
                    221: .Dq first
                    222: and
                    223: .Dq next
                    224: are particular to the
1.11      lukem     225: type of
                    226: .Tn YP
1.20      wiz       227: map being accessed, and thus there is no guarantee of lexical order.
                    228: The only guarantees provided with
1.1       deraadt   229: .Fn yp_first
                    230: and
                    231: .Fn yp_next ,
1.20      wiz       232: providing that the same map on the same server is polled repeatedly until
1.1       deraadt   233: .Fn yp_next
                    234: returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed
                    235: exactly once, and if the entire procedure is repeated, the order will be
                    236: the same.
                    237: .Pp
1.19      wiz       238: If the server is heavily loaded or the server fails for some reason, the
1.20      wiz       239: domain being used may become unbound.
                    240: If this happens, and the client process re-binds, the retrieval rules
                    241: will break: some entries may be seen twice, and others not at all.
                    242: For this reason, the function
1.1       deraadt   243: .Fn yp_all
1.20      wiz       244: provides a better solution for reading all of the entries in a particular map.
1.1       deraadt   245: .It Fn yp_all
1.6       lukem     246: This function provides a way to transfer an entire map from
1.20      wiz       247: the server to the client process with a single request.
                    248: This transfer uses TCP, unlike all other functions in the
1.1       deraadt   249: .Nm ypclnt
1.20      wiz       250: suite, which use UDP.
                    251: The entire transaction occurs in a single RPC request-response.
                    252: The third argument to this function provides a way to supply
                    253: the name of a function to process each key-value pair in the map.
1.6       lukem     254: .Fn yp_all
1.1       deraadt   255: returns after the entire transaction is complete, or the
                    256: .Pa foreach
1.20      wiz       257: function decides that it does not want any more key-value pairs.
                    258: The third argument to
1.1       deraadt   259: .Fn yp_all
                    260: is:
                    261: .Bd -literal -offset indent
                    262: struct ypall_callback *incallback {
                    263:        int (*foreach)();
                    264:        char *data;
                    265: };
                    266: .Ed
                    267: .Pp
                    268: The
                    269: .Em char *data
1.20      wiz       270: argument is an opaque pointer for use by the callback function.
                    271: The
1.1       deraadt   272: .Pa foreach
                    273: function should return non-zero when it no longer wishes to process
                    274: key-value pairs, at which time
                    275: .Fn yp_all
                    276: returns a value of 0, and is called with the following arguments:
                    277: .Pp
                    278: .Bd -literal -offset indent
                    279: int foreach (
1.3       thorpej   280:        int instatus,
                    281:        char *inkey,
                    282:        int inkeylen,
                    283:        char *inval,
                    284:        int invallen,
                    285:        char *indata
1.1       deraadt   286: );
                    287: .Ed
                    288: .Pp
                    289: Where:
                    290: .Bl -tag -width "inkey, inval"
                    291: .It Fa instatus
                    292: Holds one of the return status values described in
1.22      wiz       293: .Aq Pa rpcsvc/yp_prot.h :
1.1       deraadt   294: see
                    295: .Fn ypprot_err
1.11      lukem     296: below for a function that will translate
                    297: .Tn YP
                    298: protocol errors into a
1.1       deraadt   299: .Nm ypclnt
                    300: layer error code as described in
1.22      wiz       301: .Aq Pa rpcsvc/ypclnt.h .
1.1       deraadt   302: .It Fa inkey, inval
                    303: The key and value arguments are somewhat different here than described
1.20      wiz       304: above.
                    305: In this case, the memory pointed to by
1.1       deraadt   306: .Fa inkey
                    307: and
                    308: .Fa inval
                    309: is private to
                    310: .Fn yp_all ,
                    311: and is overwritten with each subsequent key-value pair, thus the
                    312: .Pa foreach
                    313: function should do something useful with the contents of that memory during
1.20      wiz       314: each iteration.
                    315: If the key-value pairs are not terminated with either
1.1       deraadt   316: .Ql \en
                    317: or
                    318: .Ql \e0
                    319: in the map, then they will not be terminated as such when given to the
                    320: .Pa foreach
                    321: function, either.
                    322: .It Fa indata
                    323: This is the contents of the
1.18      ross      324: .Pa incallback-\*[Gt]data
1.20      wiz       325: element of the callback structure.
                    326: It is provided as a means to share state between the
1.1       deraadt   327: .Pa foreach
1.20      wiz       328: function and the user code.
                    329: Its use is completely optional: cast it to
1.1       deraadt   330: something useful or simply ignore it.
                    331: .El
                    332: .It Fn yp_order
                    333: Returns the order number for a map.
                    334: .It Fn yp_master
1.11      lukem     335: Returns the hostname for the machine on which the master
                    336: .Tn YP
                    337: server process for
1.1       deraadt   338: a map is running.
                    339: .It Fn yperr_string
1.6       lukem     340: Returns a pointer to a NUL-terminated error string that does not contain a
1.1       deraadt   341: .Ql \&.
                    342: or
                    343: .Ql \en .
                    344: .It Fn ypprot_err
1.11      lukem     345: Converts a
                    346: .Tn YP
                    347: protocol error code to a
1.1       deraadt   348: .Nm ypclnt
                    349: error code suitable for
                    350: .Fn yperr_string .
                    351: .El
                    352: .Sh RETURN VALUES
                    353: All functions in the
                    354: .Nm ypclnt
                    355: suite which are of type
                    356: .Em int
                    357: return 0 upon success or one of the following error codes upon failure:
                    358: .Bl -tag -width "YPERR_BADARGS   "
                    359: .It Bq Er YPERR_BADARGS
1.22      wiz       360: The passed arguments to the function are invalid.
1.1       deraadt   361: .It Bq Er YPERR_BADDB
1.15      wiz       362: The
1.11      lukem     363: .Tn YP
                    364: map that was polled is defective.
1.1       deraadt   365: .It Bq Er YPERR_DOMAIN
1.15      wiz       366: Client process cannot bind to server on this
1.11      lukem     367: .Tn YP
                    368: domain.
1.1       deraadt   369: .It Bq Er YPERR_KEY
                    370: The key passed does not exist.
                    371: .It Bq Er YPERR_MAP
                    372: There is no such map in the server's domain.
                    373: .It Bq Er YPERR_DOM
1.15      wiz       374: The local
1.11      lukem     375: .Tn YP
                    376: domain is not set.
1.1       deraadt   377: .It Bq Er YPERR_NOMORE
                    378: There are no more records in the queried map.
                    379: .It Bq Er YPERR_PMAP
1.14      enami     380: Cannot communicate with portmapper (see
1.15      wiz       381: .Xr rpcbind 8 ) .
1.1       deraadt   382: .It Bq Er YPERR_RESRC
                    383: A resource allocation failure occurred.
                    384: .It Bq Er YPERR_RPC
1.20      wiz       385: An RPC failure has occurred.
                    386: The domain has been marked unbound.
1.1       deraadt   387: .It Bq Er YPERR_VERS
1.20      wiz       388: Client/server version mismatch.
                    389: If the server is running version 1 of the
1.11      lukem     390: .Tn YP
                    391: protocol,
1.1       deraadt   392: .Fn yp_all
                    393: functionality does not exist.
                    394: .It Bq Er YPERR_BIND
                    395: Cannot communicate with
                    396: .Xr ypbind 8 .
                    397: .It Bq Er YPERR_YPERR
                    398: An internal server or client error has occurred.
                    399: .It Bq Er YPERR_YPSERV
1.15      wiz       400: The client cannot communicate with the
1.11      lukem     401: .Tn YP
                    402: server process.
1.1       deraadt   403: .El
                    404: .Sh SEE ALSO
                    405: .Xr malloc 3 ,
1.16      wiz       406: .Xr yp 8 ,
1.1       deraadt   407: .Xr ypbind 8 ,
1.6       lukem     408: .Xr ypserv 8
1.16      wiz       409: .Sh AUTHORS
                    410: .An Theo De Raadt

CVSweb <webmaster@jp.NetBSD.org>