[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.22

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

CVSweb <webmaster@jp.NetBSD.org>