git.saurik.com Git - apple/libinfo.git/blob

1 .\" $OpenBSD: ypclnt.3,v 1.5 1996/12/28 09:06:29 downsj Exp $

2 .\"

5 .\"

6 .\" This code is derived from software contributed to The NetBSD Foundation

7 .\" by Jason R. Thorpe.

8 .\"

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:

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.

24 .\"

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

28 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE

29 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR

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.

36 .\"

37 .Dd October 26, 1994

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

53 .Sh SYNOPSIS

54 .Fd #include <rpc/rpc.h>

55 .Fd #include <rpcsvc/ypclnt.h>

56 .Fd #include <rpcsvc/yp_prot.h>

57 .Ft int

58 .Fn yp_all "char *indomain" "char *inmap" "struct ypall_callback *incallback"

59 .Ft int

60 .Fn yp_bind "char *dom"

61 .Ft int

62 .Fn yp_first "char *indomain" "char *inmap" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"

63 .Ft int

64 .Fn yp_get_default_domain "char **domp"

65 .Ft int

66 .Fn yp_master "char *indomain" "char *inmap" "char **outname"

67 .Ft int

68 .Fn yp_match "char *indomain" "char *inmap" "const char *inkey" "int inkeylen" "char **outval" "int *outvallen"

69 .Ft int

70 .Fn yp_next "char *indomain" "char *inmap" "char *inkey" "int inkeylen" "char **outkey" "int *outkeylen" "char **outval" "int *outvallen"

71 .Ft int

72 .Fn yp_order "char *indomain" "char *inmap" "char *outorder"

73 .Ft void

74 .Fn yp_unbind "char *dom"

75 .Ft char *

76 .Fn yperr_string "int incode"

77 .Ft int

78 .Fn ypprot_err "unsigned int incode"

79 .Sh DESCRIPTION

80 The

81 .Nm ypclnt

82 suite provides an interface to the YP subsystem. For a general description

83 of the YP subsystem, see

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 .

90 Any output values of type

91 .Em char **

92 should be the addresses of uninitialized character pointers. Memory will be

93 allocated by the YP client routines using

94 .Fn malloc .

95 This memory can later be freed by the user if there is no additional need for

96 the data stored there. For

97 .Pa outkey

98 and

99 .Pa outval ,

100 two extra bytes of memory are allocated for a

101 .Ql \en

102 and

103 .Ql \e0 ,

104 which are not

105 reflected in the values of

106 .Pa outkeylen

107 or

108 .Pa outvallen .

109 All occurrences of

110 .Pa indomain

111 and

112 .Pa inmap

113 must be non-null, null-terminated strings. All input strings which also have

114 a corresponding length parameter cannot be null unless the corresponding

115 length value is zero. Such strings need not be null-terminated.

116 .Pp

117 All YP lookup calls (the functions

118 .Fn yp_all ,

119 .Fn yp_first ,

120 .Fn yp_master ,

121 .Fn yp_match ,

122 .Fn yp_next ,

123 .Fn yp_order )

124 require a YP domain name and a YP map name. The default domain name may be

125 obtained by calling

126 .Fn yp_get_default_domain ,

127 and should thus be used before all other YP calls in a client program.

128 The value it places

129 .Pa outdomain

130 is suitable for use as the

131 .Pa indomain

132 parameter to all subsequent YP calls.

133 .Pp

134 In order for YP lookup calls to succeed, the client process must be bound

135 to a YP server process. The client process need not explicitly bind to

136 the server, as it happens automatically whenever a lookup occurs.

137 The function

138 .Fn yp_bind

139 is provided for a backup strategy, e.g. a local file, when a YP server process

140 is not available. Each binding uses one socket descriptor on the client

141 process, which may be explicitly freed using

142 .Fn yp_unbind ,

143 which frees all per-process and per-node resources to bind the domain and

144 marks the domain unbound.

145 .Pp

146 If, during a YP lookup, an RPC failure occurs, the domain used in the lookup

147 is automatically marked unbound and the

148 .Nm ypclnt

149 layer retries the lookup as long as

150 .Xr ypbind 8

151 is running and either the client process cannot bind to a server for the domain

152 specified in the lookup, or RPC requests to the YP server process fail.

153 If an error is not RPC-related, one of the YP error codes described below

154 is returned and control given back to the user code.

155 .Pp

156 The

157 .Nm ypclnt

158 suite provides the following functionality:

159 .Bl -tag -width ".Fn yperr_string"

160 .It Fn yp_match

161 Provides the value associated with the given key.

162 .It Fn yp_first

163 Provides the first key-value pair from the given map in the named domain.

164 .It Fn yp_next

165 Provides the next key-value pair in the given map. To obtain the second pair,

166 the

167 .Pa inkey

168 value should be the

169 .Pa outkey

170 value provided by the initial call to

171 .Fn yp_first .

172 In the general case, the next key-value pair may be obtained by using the

173 .Pa outkey

174 value from the previous call to

175 .Fn yp_next

176 as the value for

177 .Pa inkey .

178 .Pp

179 Of course, the notions of ``first'' and ``next'' are particular to the

180 type of YP map being accessed, and thus there is no guarantee of lexical

181 order. The only guarantees provided with

182 .Fn yp_first

183 and

184 .Fn yp_next ,

185 providing that the same map on the same server is polled repeatedly

186 until

187 .Fn yp_next

188 returns YPERR_NOMORE, are that all key-value pairs in that map will be accessed

189 exactly once, and if the entire procedure is repeated, the order will be

190 the same.

191 .Pp

192 If the server is heaviliy loaded or the server fails for some reason, the

193 domain being used may become unbound. If this happens, and the client process

194 re-binds, the retrieval rules will break: some entries may be seen twice, and

195 others not at all. For this reason, the function

196 .Fn yp_all

197 provides a better solution for reading all of the entries in a particular

198 map.

199 .It Fn yp_all

200 This function provides a way to transfer an entire map from

201 the server to the client process with a single request. This transfer

202 uses TCP, unlike all other functions in the

203 .Nm ypclnt

204 suite, which use UDP. The entire transaction occurs in a single RPC

205 request-response. The third argument to this function provides a way

206 to supply the name of a function to process each key-value pair in the

207 map.

208 .Fn Yp_all

209 returns after the entire transaction is complete, or the

210 .Pa foreach

211 function decides that it does not want any more key-value pairs. The third

212 argument to

213 .Fn yp_all

214 is:

215 .Bd -literal -offset indent

216 struct ypall_callback *incallback {

217 int (*foreach)();

218 char *data;

219 };

220 .Ed

221 .Pp

222 The

223 .Em char *data

224 argument is an opaque pointer for use by the callback function. The

225 .Pa foreach

226 function should return non-zero when it no longer wishes to process

227 key-value pairs, at which time

228 .Fn yp_all

229 returns a value of 0, and is called with the following arguments:

230 .Pp

231 .Bd -literal -offset indent

232 int foreach (

233 unsigned long instatus,

234 char *inkey,

235 int inkeylen,

236 char *inval,

237 int invallen,

238 void *indata

239 );

240 .Ed

241 .Pp

242 Where:

243 .Bl -tag -width "inkey, inval"

244 .It Fa instatus

245 Holds one of the return status values described in

246 .Nm <rpcsvc/yp_prot.h> :

247 see

248 .Fn ypprot_err

249 below for a function that will translate YP protocol errors into a

250 .Nm ypclnt

251 layer error code as described in

252 .Nm <rpcsvc/ypclnt.h> .

253 .It Fa inkey, inval

254 The key and value arguments are somewhat different here than described

255 above. In this case, the memory pointed to by

256 .Fa inkey

257 and

258 .Fa inval

259 is private to

260 .Fn yp_all ,

261 and is overwritten with each subsequent key-value pair, thus the

262 .Pa foreach

263 function should do something useful with the contents of that memory during

264 each iteration. If the key-value pairs are not terminated with either

265 .Ql \en

266 or

267 .Ql \e0

268 in the map, then they will not be terminated as such when given to the

269 .Pa foreach

270 function, either.

271 .It Fa indata

272 This is the contents of the

273 .Pa incallback->data

274 element of the callback structure. It is provided as a means to share

275 state between the

276 .Pa foreach

277 function and the user code. Its use is completely optional: cast it to

278 something useful or simply ignore it.

279 .El

280 .It Fn yp_order

281 Returns the order number for a map.

282 The order number is updated whenever a map is updated.

283 Clients may use the order number to check whether they are using the most

284 recent map.

285 .It Fn yp_master

286 Returns the hostname for the machine on which the master YP server process for

287 a map is running.

288 .It Fn yperr_string

289 Returns a pointer to a null-terminated error string that does not contain a

290 .Ql \&.

291 or

292 .Ql \en .

293 .It Fn ypprot_err

294 Converts a YP protocol error code to a

295 .Nm ypclnt

296 error code suitable for

297 .Fn yperr_string .

298 .El

299 .Sh RETURN VALUES

300 All functions in the

301 .Nm ypclnt

302 suite which are of type

303 .Em int

304 return 0 upon success or one of the following error codes upon failure:

305 .Bl -tag -width "YPERR_BADARGS "

306 .It Bq Er YPERR_BADARGS

307 The passed arguments to the function are invalid

308 .It Bq Er YPERR_BADDB

309 The YP map that was polled is defective.

310 .It Bq Er YPERR_DOMAIN

311 Client process cannot bind to server on this YP domain.

312 .It Bq Er YPERR_KEY

313 The key passed does not exist.

314 .It Bq Er YPERR_MAP

315 There is no such map in the server's domain.

316 .It Bq Er YPERR_DOM

317 The local YP domain is not set.

318 .It Bq Er YPERR_NOMORE

319 There are no more records in the queried map.

320 .It Bq Er YPERR_PMAP

321 Cannot communicate with portmap.

322 .It Bq Er YPERR_RESRC

323 A resource allocation failure occurred.

324 .It Bq Er YPERR_RPC

325 An RPC failure has occurred. The domain has been marked unbound.

326 .It Bq Er YPERR_VERS

327 Client/server version mismatch. If the server is running version 1

328 of the YP protocol,

329 .Fn yp_all

330 functionality does not exist.

331 .It Bq Er YPERR_BIND

332 Cannot communicate with

333 .Xr ypbind 8 .

334 .It Bq Er YPERR_YPERR

335 An internal server or client error has occurred.

336 .It Bq Er YPERR_YPSERV

337 The client cannot communicate with the YP server process.

338 .El

339 .Sh SEE ALSO

340 .Xr malloc 3 ,

341 .Xr yp 8 ,

342 .Xr ypbind 8 ,

343 .Xr ypserv 8

344 .Sh AUTHOR

345 Theo De Raadt